{ "cells": [ { "cell_type": "markdown", "id": "3fba75fe", "metadata": {}, "source": [ "# Checking your WS4 installation\n", "\n", "This notebook checks that the pieces are where they should be: the interpreter, the\n", "package, the command line, and the compiler. It writes only into `tmp/`.\n", "\n", "This one is a **command-line** session: it checks a WS4 install by running the tool.\n" ] }, { "cell_type": "markdown", "id": "fc2f2a2f", "metadata": {}, "source": [ "## The interpreter and the package" ] }, { "cell_type": "code", "execution_count": 1, "id": "a68a08fe", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:44.478272Z", "iopub.status.busy": "2026-10-17T20:20:44.477808Z", "iopub.status.idle": "2026-10-17T20:20:44.486848Z", "shell.execute_reply": "2026-10-17T20:20:44.485338Z" } }, "outputs": [], "source": [ "import subprocess\n", "\n", "\n", "def run(command: str) -> None:\n", " \"\"\"Run a WS4 command, printing what it printed.\"\"\"\n", " result = subprocess.run(command, shell=True, text=True, capture_output=True)\n", " print((result.stdout or result.stderr).strip())\n", " result.check_returncode()\n" ] }, { "cell_type": "code", "execution_count": 2, "id": "52215ccc", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:44.490690Z", "iopub.status.busy": "2026-10-17T20:20:44.490265Z", "iopub.status.idle": "2026-10-17T20:20:44.500571Z", "shell.execute_reply": "2026-10-17T20:20:44.499067Z" }, "tags": [ "no-drift-check" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "python 3.12.3\n", "import ws4\n", "ws4 0.1.0\n" ] } ], "source": [ "import importlib.metadata\n", "import sys\n", "\n", "import ws4\n", "\n", "print(\"python\", sys.version.split()[0])\n", "print(\"import \", ws4.__name__)\n", "print(\"ws4 \", importlib.metadata.version(\"ws4\"))" ] }, { "cell_type": "markdown", "id": "0b391e30", "metadata": {}, "source": [ "## The optional numerics\n", "\n", "`numba` compiles the patch-state kernels; `scipy` is needed for `--mip-bound`.\n", "Both are optional, and both are reported as found or absent." ] }, { "cell_type": "code", "execution_count": 3, "id": "47541334", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:44.504221Z", "iopub.status.busy": "2026-10-17T20:20:44.503795Z", "iopub.status.idle": "2026-10-17T20:20:45.035833Z", "shell.execute_reply": "2026-10-17T20:20:45.034644Z" }, "tags": [ "no-drift-check" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "numba 0.68.0\n", "scipy 1.18.1\n" ] }, { "name": "stdout", "output_type": "stream", "text": [ "geopandas 1.2.0\n" ] } ], "source": [ "for module in (\"numba\", \"scipy\", \"geopandas\"):\n", " try:\n", " imported = __import__(module)\n", " print(f\"{module:10} {getattr(imported, '__version__', 'present')}\")\n", " except ImportError:\n", " print(f\"{module:10} not installed (optional)\")" ] }, { "cell_type": "markdown", "id": "bcb23271", "metadata": {}, "source": [ "## The command line" ] }, { "cell_type": "code", "execution_count": 4, "id": "4d691374", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:45.038895Z", "iopub.status.busy": "2026-10-17T20:20:45.038652Z", "iopub.status.idle": "2026-10-17T20:20:45.954071Z", "shell.execute_reply": "2026-10-17T20:20:45.952769Z" }, "tags": [ "no-drift-check" ] }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1m \u001b[0m\n", "\u001b[1m \u001b[0m\u001b[1;33mUsage: \u001b[0m\u001b[1mws4 [OPTIONS] COMMAND [ARGS]...\u001b[0m\u001b[1m \u001b[0m\u001b[1m \u001b[0m\n", "\u001b[1m \u001b[0m\n", " WS4 — Wood Supply Simulation System (Spatially explicit) \n", " \n", "\u001b[2m╭─\u001b[0m\u001b[2m Options \u001b[0m\u001b[2m───────────────────────────────────────────────────────────────────\u001b[0m\u001b[2m─╮\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m-\u001b[0m\u001b[1;36m-install\u001b[0m\u001b[1;36m-completion\u001b[0m Install completion for the current shell. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m-\u001b[0m\u001b[1;36m-show\u001b[0m\u001b[1;36m-completion\u001b[0m Show completion for the current shell, to copy \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m it or customize the installation. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m-\u001b[0m\u001b[1;36m-help\u001b[0m Show this message and exit. \u001b[2m│\u001b[0m\n", "\u001b[2m╰──────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n", "\u001b[2m╭─\u001b[0m\u001b[2m Commands \u001b[0m\u001b[2m──────────────────────────────────────────────────────────────────\u001b[0m\u001b[2m─╮\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36mbuild \u001b[0m\u001b[1;36m \u001b[0m Compile a canonical dataset from an XML recipe and a *fragments* \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m shapefile. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36msimulate \u001b[0m\u001b[1;36m \u001b[0m Simulate a schedule over a compiled dataset and write a run \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m directory. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36moptimize \u001b[0m\u001b[1;36m \u001b[0m Search for a schedule that satisfies the targets and write a \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m summary. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36mwatch \u001b[0m\u001b[1;36m \u001b[0m Watch realized versus target account values while the search \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m runs. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36mcalibrate\u001b[0m\u001b[1;36m \u001b[0m Balance target weights from a pilot search and write a targets \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m file. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36mingest \u001b[0m\u001b[1;36m \u001b[0m Ingest a legacy matrix dataset into the WS4 schema. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36mreport \u001b[0m\u001b[1;36m \u001b[0m Write an account summary and a target status for a run. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36mvalidate \u001b[0m\u001b[1;36m \u001b[0m Validate a compiled dataset against its manifest and schema \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m invariants. \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36mserve \u001b[0m\u001b[1;36m \u001b[0m Serve the read-only web API over a dataset and its runs (needs \u001b[2m│\u001b[0m\n", "\u001b[2m│\u001b[0m \u001b[1;36m \u001b[0m the ``web`` extra). \u001b[2m│\u001b[0m\n", "\u001b[2m╰──────────────────────────────────────────────────────────────────────────────╯\u001b[0m\n" ] } ], "source": [ "run(\"ws4 --help\")" ] }, { "cell_type": "markdown", "id": "0f2b63bb", "metadata": {}, "source": [ "## The compiler\n", "\n", "`ws4 build` compiles the recipe and inventory in `examples/synthetic` into a dataset, and\n", "`ws4 validate` checks it against its manifest and schema invariants." ] }, { "cell_type": "code", "execution_count": 5, "id": "c6a6b165", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:45.957287Z", "iopub.status.busy": "2026-10-17T20:20:45.956990Z", "iopub.status.idle": "2026-10-17T20:20:46.851332Z", "shell.execute_reply": "2026-10-17T20:20:46.849804Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mBuilt dataset\u001b[0m → tmp/examples/compiled\n" ] } ], "source": [ "run(\"ws4 build --xml examples/synthetic/recipe.xml --fragments examples/synthetic/fragments.csv --out tmp/examples/compiled\")" ] }, { "cell_type": "code", "execution_count": 6, "id": "9f10637b", "metadata": { "execution": { "iopub.execute_input": "2026-10-17T20:20:46.854860Z", "iopub.status.busy": "2026-10-17T20:20:46.854413Z", "iopub.status.idle": "2026-10-17T20:20:47.805284Z", "shell.execute_reply": "2026-10-17T20:20:47.803472Z" } }, "outputs": [ { "name": "stdout", "output_type": "stream", "text": [ "\u001b[1;32mDataset is valid\u001b[0m → tmp/examples/compiled\n" ] } ], "source": [ "run(\"ws4 validate --dataset tmp/examples/compiled\")" ] }, { "cell_type": "markdown", "id": "c46d02ea", "metadata": {}, "source": [ "If both commands print a destination and no error, the install is complete. Continue with\n", "`010_quickstart.ipynb`." ] } ], "metadata": { "kernelspec": { "display_name": "Python 3", "language": "python", "name": "python3" }, "language_info": { "codemirror_mode": { "name": "ipython", "version": 3 }, "file_extension": ".py", "mimetype": "text/x-python", "name": "python", "nbconvert_exporter": "python", "pygments_lexer": "python", "version": "3.12.3" } }, "nbformat": 4, "nbformat_minor": 5 }