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.