Installing the Python packages

The course uses two Python packages. Knowing which is which will save you a lot of confusion later:

Package	Where it lives	What it is
waveflow	separate repository	A general-purpose, Python-first hardware modeling and synthesis framework. It is not specific to this course, and is used for the simulation, timing analysis, code generation, and HLS/Vivado tooling throughout. Documentation
hwdesign	this repository	A thin, course-specific layer on top of waveflow — autograder glue, lab scaffolding, and helpers that only make sense for this class.

You install waveflow from GitHub; you install hwdesign from your clone of this repository. You do not need to clone waveflow.

Before you start: Python 3.10 or newer

Check your Python version:

python --version

waveflow requires Python 3.10 or newer. On an older interpreter the install fails at dependency resolution with a message about Python>=3.10, rather than anything obviously version-related. If yours is older, install a current Python before continuing — on the NYU EDA servers, whose system Python is 3.9, see Using Python on the NYU server, which uses uv to install a newer interpreter without administrator access.

1. Clone the course repository

If you have not already, follow Cloning the Repository. The rest of this page assumes you are in the hwdesign directory that produced.

2. Create and activate a virtual environment

Create an environment named env (any name works). I usually run this in the directory just outside hwdesign:

python -m venv env

This may take several minutes without showing progress. The resulting env directory may be large.

Activate it:

.\env\Scripts\Activate.ps1   [Windows PowerShell]
.\env\Scripts\activate.bat   [Windows command prompt]
source env/bin/activate      [macOS / Linux]

On Windows PowerShell you may get “…Activate.ps1 is not digitally signed. The script will not execute on the system.” If so, run:

Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass

Your prompt should now be prefixed with (env). Everything below must be run inside the activated environment.

3. Install waveflow

(env) pip install git+https://github.com/sdrangan/waveflow.git

This pulls waveflow and its dependencies (numpy, pandas, simpy, scikit-learn, and others), so it will take a few minutes.

Do not pip install pywaveflow yet. waveflow is published on PyPI under the name pywaveflow — the different name is normal and not a mistake, in the same way pip install scikit-learn gives you import sklearn. But the version currently on PyPI is only a placeholder reserving the name: it contains a single file and none of the actual framework. Until a real release is published, install from GitHub as shown above. Installing both puts two packages in conflict over the same waveflow directory.

4. Install hwdesign

From inside your clone of this repository:

(env) pip install -e .

The -e (“editable”) flag means Python reads the package straight from your clone, so a git pull updates it with no reinstall.

⚠️ Do steps 3 and 4 in that order. hwdesign declares waveflow as a dependency, but waveflow is distributed from GitHub rather than PyPI. If you run pip install -e . in a fresh environment before installing waveflow, pip will search PyPI, fail to find it, and stop with No matching distribution found for waveflow. Installing waveflow first satisfies the dependency and everything resolves.

5. Verify the installation

import importlib.metadata as md
import hwdesign, waveflow

print("hwdesign", md.version("hwdesign"))
print("waveflow", md.version("waveflow"))
print("waveflow loaded from", waveflow.__file__)

You should see a version number for each and a path for waveflow. If either import raises ModuleNotFoundError, the most common cause is that the virtual environment is not activated.

If you get an error mentioning pysilicon, you have hit course material that has not yet been updated — see the note at the bottom of this page.

Using the environment later

Activate the environment in every new terminal before running course material:

.\env\Scripts\Activate.ps1   [Windows PowerShell]
source env/bin/activate      [macOS / Linux]

Leave it with:

(env) deactivate

Updating

To pick up new course material, pull this repository — the editable install means there is nothing to reinstall:

git pull

To pick up a newer waveflow, reinstall it. The --force-reinstall is required because waveflow’s version number does not change on every update, so pip would otherwise decide you are already up to date:

(env) pip install --force-reinstall --no-deps git+https://github.com/sdrangan/waveflow.git

Note: material still being migrated

The course tooling is being moved onto waveflow one unit at a time. Material that has not been converted yet will fail with a message beginning:

The vendored 'pysilicon' package has been removed - this course material has
not been migrated to waveflow yet.

That is expected, not a broken install — it means that particular demo or lab is still queued for conversion. Your environment is fine.