Checking your WS4 installation
This notebook checks that the pieces are where they should be: the interpreter, the package, the command line, and the compiler. It writes only into tmp/.
This one is a command-line session: it checks a WS4 install by running the tool.
The interpreter and the package
[1]:
import subprocess
def run(command: str) -> None:
"""Run a WS4 command, printing what it printed."""
result = subprocess.run(command, shell=True, text=True, capture_output=True)
print((result.stdout or result.stderr).strip())
result.check_returncode()
[2]:
import importlib.metadata
import sys
import ws4
print("python", sys.version.split()[0])
print("import ", ws4.__name__)
print("ws4 ", importlib.metadata.version("ws4"))
python 3.12.3
import ws4
ws4 0.1.0
The optional numerics
numba compiles the patch-state kernels; scipy is needed for --mip-bound. Both are optional, and both are reported as found or absent.
[3]:
for module in ("numba", "scipy", "geopandas"):
try:
imported = __import__(module)
print(f"{module:10} {getattr(imported, '__version__', 'present')}")
except ImportError:
print(f"{module:10} not installed (optional)")
numba 0.68.0
scipy 1.18.1
geopandas 1.2.0
The command line
[4]:
run("ws4 --help")
Usage: ws4 [OPTIONS] COMMAND [ARGS]...
WS4 — Wood Supply Simulation System (Spatially explicit)
╭─ Options ────────────────────────────────────────────────────────────────────╮
│ --install-completion Install completion for the current shell. │
│ --show-completion Show completion for the current shell, to copy │
│ it or customize the installation. │
│ --help Show this message and exit. │
╰──────────────────────────────────────────────────────────────────────────────╯
╭─ Commands ───────────────────────────────────────────────────────────────────╮
│ build Compile a canonical dataset from an XML recipe and a *fragments* │
│ shapefile. │
│ simulate Simulate a schedule over a compiled dataset and write a run │
│ directory. │
│ optimize Search for a schedule that satisfies the targets and write a │
│ summary. │
│ watch Watch realized versus target account values while the search │
│ runs. │
│ calibrate Balance target weights from a pilot search and write a targets │
│ file. │
│ ingest Ingest a legacy matrix dataset into the WS4 schema. │
│ report Write an account summary and a target status for a run. │
│ validate Validate a compiled dataset against its manifest and schema │
│ invariants. │
│ serve Serve the read-only web API over a dataset and its runs (needs │
│ the ``web`` extra). │
╰──────────────────────────────────────────────────────────────────────────────╯
The compiler
ws4 build compiles the recipe and inventory in examples/synthetic into a dataset, and ws4 validate checks it against its manifest and schema invariants.
[5]:
run("ws4 build --xml examples/synthetic/recipe.xml --fragments examples/synthetic/fragments.csv --out tmp/examples/compiled")
Built dataset → tmp/examples/compiled
[6]:
run("ws4 validate --dataset tmp/examples/compiled")
Dataset is valid → tmp/examples/compiled
If both commands print a destination and no error, the install is complete. Continue with 010_quickstart.ipynb.