Installation

Requirements

  • Python 3.11 or newer.

  • A C-free install: the core dependencies are pure Python plus NumPy and Pandas (pydantic, typer, rich, pandas, numpy, pyarrow, pyyaml), all installed for you.

  • Nothing else for the command line. The optional extras below add capabilities rather than fixing missing basics.

Install from source

WS4 is installed from its repository:

git clone https://github.com/UBC-FRESH/ws4.git
cd ws4
python -m pip install -e .

ws4 --help

ws4 --help lists one command per step of a study: build, ingest, validate, simulate, optimize, watch, calibrate, and report. Each prints where it wrote its output.

Optional dependencies

Extra

Install

What it adds

geo

pip install -e ".[geo]"

Reading a shapefile fragment inventory. A CSV or Parquet inventory needs nothing extra, so skip this unless your fragments are spatial files.

opt

pip install -e ".[opt]"

The optional numerics and solver stack: numba (compiled patch-state kernels, which have an equivalent pure-Python fallback), scipy (the --mip-bound penalty bound, which raises a clear error without it), networkx, and ray.

carbon

pip install -e ".[carbon]"

The optional libcbm carbon engine behind ws4 carbon and carbon targets. A core install does not import it; see Running a carbon study.

Development and documentation builds need more:

python -m pip install -r requirements-dev.txt   # pytest, ruff, mypy, numpydoc, hypothesis
python -m pip install -r docs/requirements.txt  # Sphinx

Platform notes

WS4 is developed and measured on Linux, on a many-core host. Nothing in the runtime is Linux-specific, but only Linux is exercised: treat macOS and Windows as unverified. The one place a platform shows through is the documentation build, which follows the repository layout with a symlink (see the repository’s docs/ directory); on Windows, clone with symlink support enabled.

Check the install

Three commands, in order, prove that the pieces work:

ws4 --help                                                # the command line is installed
ws4 build --xml examples/synthetic/recipe.xml \
          --fragments examples/synthetic/fragments.csv \
          --out tmp/check/compiled                        # the compiler works
ws4 validate --dataset tmp/check/compiled                 # the dataset is coherent
Built dataset → tmp/check/compiled
Dataset is valid → tmp/check/compiled

If build complains that a dependency is missing, install the extra it names. If validate reports problems, it lists the file, the column, and what is wrong with it — the dataset is a contract, and it is checked on the way in (see Compiled dataset).

Next

Continue with Quickstart: the command line to run a simulation and a search, or How WS4 is put together to see how the parts fit together first.