hls4ml-tutorial: what the notebooks actually cover, and what they assume you already have

The gap these notebooks are written to close

A model that trains to a good accuracy in Keras or PyTorch does not become FPGA firmware by itself. Between the two there is a chain of decisions: how many bits each weight and activation gets, which layers can be pruned without destroying accuracy, what the HLS tool will accept as synthesizable code, and how the resulting design maps onto the DSP and LUT budget of a specific part. Each of those steps has its own vocabulary, and none of them appear in a typical machine learning course. The hls4ml-tutorial repository exists to put that chain in front of you as runnable notebooks rather than as a paper. The topics listed on the repository page (fpga, hls4ml, machine-learning, pruning, quantization-aware-training, tutorial) describe the intended scope fairly precisely. The audience is someone who already knows how to train a network and now needs to understand what changes when the inference target is an FPGA rather than a GPU. It is not an introduction to machine learning, and the README does not present it as one.

How the tutorial is packaged and served

The repository is a Jupyter Book, and the README embeds a table of contents directive rather than a static list, which means the notebook order is generated when the book is built. A GitHub Actions workflow named deploy-book is referenced by a badge, so the published site at fastmachinelearning.org/hls4ml-tutorial is built from the repository rather than maintained by hand. That is a meaningful detail for anyone deciding whether to trust the material: the notebooks you read on the site correspond to the notebooks in the default branch at the time of the last build. The README also links a Binder badge, which points at the repository's HEAD rather than a tagged release. There are no releases retrieved for this repository, so there is no version number to pin to. If you need to cite the exact state of the tutorial in a report, the commit hash is the only stable identifier you have.

Two ways to run the notebooks, and only one of them builds firmware

The README lists three routes: online via Binder, conda locally, and a set of companion slides. The conda route is the one that matters for synthesis work. It requires AMD Vitis HLS to be installed first, with the README pointing at the Xilinx download page for Vitis. After installation you source the toolchain settings script, shown in the README as `source /path/to/your/installtion/Xilinx/Vitis_HLS/202X.X/settings64.(c)sh`. Note the typo in the path placeholder, and note that the file extension is given as either `.csh` or `.sh` depending on which shell you use. The Python side is then created from the environment file with `conda env create -f environment.yml` followed by `conda activate hls4ml-tutorial`. The ordering in the README puts the environment creation before the settings script, but the environment variables from the Xilinx script are what the HLS steps need at run time, so in practice you source it in every shell where you execute those cells. Binder gives you the Python environment without Vitis HLS, so the cells that call the HLS toolchain cannot complete there. The README does not spell that distinction out, and it is the single most common source of confusion for a first-time reader.

What the repository deliberately does not contain

The licence field for this repository is not stated in the material available. That is not a minor omission for anyone planning to reuse the notebook code or the accompanying text in internal training material. There is also no `setup.py`, no package published under this name, and no API to import. The notebooks are the artifact. Anything you want to reuse has to be copied out of them. The environment file pins the Python dependencies, but the Vitis HLS version is left as `202X.X` in the README, which means the tutorial does not commit to a specific toolchain release. HLS tool behaviour changes between versions, and a notebook that synthesizes cleanly under one release may need edits under another. The README's placeholder is honest about the range of versions that might work, but it also means the repository cannot tell you which one was used to produce the outputs you see on the published site.

Where the tutorial format stops being enough

A notebook is a linear sequence of cells with outputs saved from a previous run. When you change a quantization scheme and re-run, you are editing a teaching example, not a project. There is no test suite in the repository that would catch a broken cell after a dependency bump, and no CI job described in the README other than the book deployment. The consequence is that the tutorial can go stale in the parts that matter most: the HLS conversion and synthesis steps, which depend on an external proprietary toolchain the maintainers cannot install in a GitHub runner. If a cell fails on your machine, the repository gives you no supported path to a fix. You are reading the notebook, comparing it against the hls4ml documentation, and working it out. That is a reasonable expectation for a tutorial, but it is not a reasonable expectation for a production dependency, and the two should not be confused.

The realistic alternative: going straight to hls4ml

The hls4ml project itself is the library the tutorial teaches. Its own documentation covers the conversion API, the configuration dictionary that controls per-layer precision and reuse factor, and the supported backends. If you already know what you want to build and you know which layers need which bit widths, the tutorial adds a layer of narration you do not need. The difference in approach is straightforward: the tutorial is organized around a sequence of exercises with saved outputs, so you learn by following a worked example from a trained model to a converted design; the library documentation is organized around the API surface, so you look up the function or config key you need and apply it to your own model. For a first encounter with FPGA inference, the tutorial order is the better one because it shows the whole chain in one place. For the second project onward, the library documentation is faster, and the tutorial becomes something you consult when a specific step misbehaves.

Maintenance and upgrade cost

Two dependencies drive the maintenance burden here, and they move on different schedules. The Python environment is pinned in `environment.yml`, and conda environments of that kind tend to break when a transitive dependency is yanked or when a package drops support for the Python version in the file. Recreating the environment from scratch with `conda env create -f environment.yml` is the recovery step, and it is also the step most likely to fail a year after the file was last touched. The Vitis HLS side is worse, because it is a large proprietary install with its own licensing, its own installer, and its own release cadence. Upgrading Vitis means re-sourcing a different settings64 script and re-running the synthesis cells to see what changed. Neither of those costs appears in the README, which is a gap if you are estimating effort. Treat the tutorial as something you run once to learn the shape of the problem, and budget separately for the toolchain you will actually keep installed.

A note on the companion slides and the published book

The README links a Google Slides deck described as containing an introduction and more detail on each of the exercises. That deck lives outside the repository, on a Google-hosted URL, which means it is not versioned alongside the notebooks and can be edited without any corresponding commit. If you are building a course or an internal walkthrough on top of this material, the slides are the part you cannot pin. The published Jupyter Book is the opposite: it is rebuilt by the deploy-book workflow from the default branch, so it tracks the notebooks. The practical consequence is that when the slides and the notebooks disagree, the notebooks are the version that was actually executed. The last push to the repository is dated 2026-08-31, so the material is being maintained rather than abandoned, but the absence of releases means there is no changelog to read when something behaves differently than you remember.

Editorial conclusion

Adopt hls4ml-tutorial if you already have an FPGA target in mind and want to see how quantization, pruning and HLS conversion fit together before committing engineering time; the notebooks are the cheapest way to learn that vocabulary. Do not adopt it if you need a supported pipeline, a pinned toolchain or a licence you can put in a procurement document, because the repository supplies none of those. Before anything else, confirm that you can install AMD Vitis HLS and source its settings64 script, then open the Binder link and check whether the notebook kernels run in the hosted environment, since that tells you more about your own setup than any of the prose in the README.

Official sources

1. fastmachinelearning/hls4ml-tutorial on GitHub
2. Issues
3. Project website
4. README