Skip to main content

⚙️ Setup

Status:Preliminary
Tags:Onboarding
Last modified:

This page describes the baseline setup for working on 🚂ENABOL locally, including notebooks under workspace/.

Requirements​

  • Python 3.11 or newer.
  • pip from the same Python environment you plan to use.
  • (Optional) Node.js 20 or newer, only if you want to run the documentation site.
  • (Optional) nvm, recommended for matching the documentation site's Node version.

Clone the repository​

cd ~
git clone git@github.com:manuelblancovalentin/kappa_budgeting.git ENABOL
cd ENABOL

Clone hls4ml-trainable​

The development requirements install ./hls4ml-trainable in editable mode, so the hls4ml fork must exist next to enabol/ before running pip install -r requirements-dev.txt.

For the current ENABOL trainable workflow, clone the maintained fork and branch:

git clone --branch hls4ml-trainable git@github.com:manuelblancovalentin/hls4ml.git hls4ml-trainable

If SSH is not configured on the machine, use HTTPS:

git clone --branch hls4ml-trainable https://github.com/manuelblancovalentin/hls4ml.git hls4ml-trainable

Verify the layout from the ENABOL repository root:

test -d enabol && echo "enabol exists"
test -d hls4ml-trainable/hls4ml && echo "hls4ml-trainable exists"
Most users should not create a new hls4ml fork

The commands above clone the existing ENABOL hls4ml-trainable dependency. You only need to create a fresh personal hls4ml fork if you are changing the upstream integration strategy or preparing a separate hls4ml pull request. That advanced workflow is documented in Advanced: creating a fresh hls4ml fork.

Python Environment Setup​

Create and activate a Python environment for the project:

conda create -n enabol python=3.11
conda activate enabol

Using venv:​

python -m venv enabol-env
source enabol-env/bin/activate # On Windows: enabol-env\Scripts\activate

Install the development requirements from the repository root:

python -m pip install -r requirements-dev.txt

The current requirements-dev.txt includes:

-e .
-e ./hls4ml-trainable
jupyter
ipykernel
pytest

The -e . entry installs the local enabol package in editable mode, while the -e ./hls4ml-trainable entry installs the local hls4ml package in editable mode. This means notebooks, scripts, and tests can import 🚂ENABOL without manually editing sys.path:

import enabol

Editable mode also means local changes under enabol/ are picked up without reinstalling the package.

Register the Notebook Kernel​

If you use Jupyter notebooks, register the environment as a kernel:

python -m ipykernel install --user --name enabol --display-name "Python (enabol)"

Then select Python (enabol) in notebooks under workspace/.

Verify the Setup​

From the repository root:

python -c "import enabol; print(enabol.__file__)"
python -m pytest

Which should print a message like:

import check
[INFO] - ENABOL imported successfully! Version: 0.1.0, URL: https://manuelblancovalentin.github.io/ENABOL/

Also verify that hls4ml resolves to the local trainable fork:

python - <<'PY'
import enabol
import hls4ml

print("enabol:", enabol.__file__)
print("hls4ml:", hls4ml.__file__)
PY

The hls4ml path should point inside the local hls4ml-trainable directory.

Server Toolchain Check​

On kona-ubuntu, ENABOL uses toolchain profiles so notebooks do not have to source Vivado/Vitis shell files manually. The default profile is:

kona-vitis-2024_1

Verify the profile machinery from the repository root:

python - <<'PY'
from enabol.toolchain import list_toolchain_profiles, toolchain_environment

print(list_toolchain_profiles())
with toolchain_environment("auto", backend="Vitis") as profile:
print(profile)
PY

The 2024.1 profile should be the default because CSIM with 2023.2 is not reliable on Ubuntu 24.04 without a container. Before running the first hls4ml build on kona-ubuntu, also check:

which vitis-run
which vitis_hls
vitis_hls -version

The older compatibility profile kona-vivado-2023_2 is still documented because /usr/local/bin/vivado_hls exists on kona-ubuntu, but it should not be the default compile path.

First hls4ml Compilation Check​

On a laptop without Vitis/Vivado, you can still run ENABOL conversion and hls4ml project generation:

from enabol.compile import compile

hls_model, hls_config = compile(
model=model,
dataset=dataset,
backend="Vitis",
toolchain="auto",
part="xcku035-fbva676-2-e",
trainable=True,
controller="none",
write=True,
compile_cpp=False,
build=False,
output_dir=f"../../sandbox/{model.name}_hls",
)

Set compile_cpp=True or build=True only on a machine where the required local C++/HLS toolchain works. For the current trainable hardware path, use controller="none" for the first validation because the global-throttle controllers are not wired yet.

On kona-ubuntu, the next validation step is to run the same notebook with:

compile_cpp=True
build=True
csim=True
synth=False

That runs the generated testbench through the configured Vitis HLS toolchain.

Advanced: creating a fresh hls4ml fork​

You probably do not need this

This section is only for maintainers who need to create a new hls4ml fork/branch from official fastmachinelearning/hls4ml. Normal ENABOL users should clone the existing hls4ml-trainable dependency using the commands near the top of this page.

  1. Fork the hls4ml repository directly on GitHub.

  2. Clone that fork inside the ENABOL folder:

git clone git@github.com:<YOUR_USERNAME>/hls4ml.git hls4ml-trainable
  1. Add the official repository as upstream:
cd hls4ml-trainable
git remote add upstream https://github.com/fastmachinelearning/hls4ml.git
git remote -v

You should see something like:

git remote -v
origin    git@github.com:YOUR_USERNAME/hls4ml.git (fetch)
origin    git@github.com:YOUR_USERNAME/hls4ml.git (push)
upstream  https://github.com/fastmachinelearning/hls4ml.git (fetch)
upstream  https://github.com/fastmachinelearning/hls4ml.git (push)
  1. Fetch upstream and create the development branch:
git fetch upstream
git checkout -b hls4ml-trainable upstream/main
git push -u origin hls4ml-trainable
  1. Return to ENABOL and reinstall editable dependencies:
cd ..
python -m pip install -r requirements-dev.txt

Build the documentation site​

Documentation is optional for test-only users

If you are only supposed to run experiments or tests, you probably do not need to build the documentation site. This section is mainly for active documentation/site developers.

The documentation site lives under site/, so run Node commands from that directory:

cd site
nvm use
npm ci
npm run start

Common setup problems​

ProblemLikely causeSolution
ModuleNotFoundError: No module named 'enabol'The active environment does not have the local package installed.Activate the project environment and rerun python -m pip install -r requirements-dev.txt from the repository root.
pip install -e . reports multiple top-level packagesSetuptools is trying to auto-discover packages in the flat repository layout.Keep the package discovery rule in pyproject.toml restricted to enabol*.
Notebook imports work in one notebook but not anotherThe notebook is using a different kernel/environment.Select the Python (enabol) kernel or register it with python -m ipykernel install --user --name enabol --display-name "Python (enabol)".
nvm use fails in site/Node Version Manager is not installed or not loaded in the shell.Install/load nvm, or manually use Node.js 20 or newer.