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 |
|---|---|---|
|
|
Reading a shapefile fragment inventory. A CSV or Parquet inventory needs nothing extra, so skip this unless your fragments are spatial files. |
|
|
The optional numerics and solver stack: |
|
|
The optional |
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.