WS4

Getting started

  • Getting started

Concepts

  • Concepts

How-to guides

  • How-to guides

Examples

  • Examples
    • Checking your WS4 installation
    • Quickstart: compile, simulate, target, search
      • Compile a dataset
      • Simulate a schedule
      • State a target and check the run against it
      • Search for a schedule that meets it
      • Watch a search
      • Where to go next
    • Even flow: shape first, level second
    • The sample estate
    • Patch size-distribution targets
    • Route products to mills
    • Sweep a parameter
    • The library path

Guides

  • Guides

Reference

  • Reference

Tooling

  • API reference
WS4
  • Examples
  • Quickstart: compile, simulate, target, search
  • View page source

Quickstart: compile, simulate, target, search

The command-line walkthrough, run here on the two-block example in examples/synthetic. Its numbers are checkable by hand: with no schedule the natural-track volume at offset 0 is 3.0 * 120 + 2.0 * 170 = 700, and clearing block 1 leaves 2.0 * 170 = 340.

This one is a command-line session: every step is a ws4 command.

Compile a dataset

[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]:
run("ws4 build --xml examples/synthetic/recipe.xml --fragments examples/synthetic/fragments.csv --out tmp/examples/quickstart/compiled")
Built dataset → tmp/examples/quickstart/compiled
[3]:
run("ws4 validate --dataset tmp/examples/quickstart/compiled")
Dataset is valid → tmp/examples/quickstart/compiled

Simulate a schedule

A schedule is a CSV of block_id, treatment, and offset, where the offset is the number of years after the start of the simulation.

[4]:
from pathlib import Path

work = Path("tmp/examples/quickstart")
work.mkdir(parents=True, exist_ok=True)
(work / "schedule.csv").write_text("block_id,treatment,offset\n1,CC,0\n")

run("ws4 simulate --dataset tmp/examples/quickstart/compiled --schedule tmp/examples/quickstart/schedule.csv --years 5 --out tmp/examples/quickstart/sim")
Simulation complete → tmp/examples/quickstart/sim
[5]:
import pandas as pd

values = pd.read_csv(work / "sim" / "account_values.csv")
print(values.head(4).to_string(index=False))
 offset        account  value
     -1 feature.Volume  700.0
      0 feature.Volume  340.0
      0 product.Volume  360.0
      1 feature.Volume  360.0

340.0 is the figure from the example: block 1’s 3.0 ha of natural track is gone, and block 2’s 2.0 ha of natural volume remains.

State a target and check the run against it

[6]:
(work / "targets.yaml").write_text(
    "targets:\n"
    "- account: feature.Volume\n"
    "  period: 1\n"
    "  minimum: 700\n"
    "  maximum: 700\n"
    "  period_width: 1\n"
)

run("ws4 report --run tmp/examples/quickstart/sim --targets tmp/examples/quickstart/targets.yaml")
Report written → tmp/examples/quickstart/sim
[7]:
print(pd.read_csv(work / "sim" / "report_targets.csv").to_string(index=False))
       account  period  year  value  minimum  maximum  raw_penalty  penalty  scale normalization  priority  kind status
feature.Volume       1     1  340.0      700      700        360.0    360.0    1.0          none         1 level  below

The status is below: clearing block 1 drops the natural volume to 340 against a floor of 700, and the penalty is the shortfall.

Search for a schedule that meets it

[8]:
run("ws4 optimize --dataset tmp/examples/quickstart/compiled --targets tmp/examples/quickstart/targets.yaml --years 5 --time-limit 00:00:05 --seed 1 --threads 1 --out tmp/examples/quickstart/opt")
                                                                                                            Optimization Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ key                     ┃ value                                                                                                                                                                                                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ incumbent_objective     │ 0.0                                                                                                                                                                                                             │
│ iterations              │ 500                                                                                                                                                                                                             │
│ patience                │ 0                                                                                                                                                                                                               │
│ reversion               │ 0                                                                                                                                                                                                               │
│ seed                    │ 1                                                                                                                                                                                                               │
│ metaheuristic           │ sa                                                                                                                                                                                                              │
│ threshold               │ 1.0                                                                                                                                                                                                             │
│ starts                  │ 1                                                                                                                                                                                                               │
│ initial_schedule_path   │ None                                                                                                                                                                                                            │
│ blocks_scheduled        │ 0                                                                                                                                                                                                               │
│ operators               │ ['toggle', 'shift', 'swap', 'lns', 'cluster', 'coalesce', 'merge', 'split']                                                                                                                                     │
│ constraint_strategy     │ penalize                                                                                                                                                                                                        │
│ constraint_stats        │ {'strategy': 'penalize', 'enabled': False, 'proposed': 0, 'feasible': 0, 'rejected': 0, 'repaired': 0, 'initial_removed': 0, 'initial_repairs': 0, 'available': True}                                           │
│ constraint_feasible     │ True                                                                                                                                                                                                            │
│ constraint_report       │ constraint_report.json                                                                                                                                                                                          │
│ run_manifest            │ run_manifest.json                                                                                                                                                                                               │
│ data_quality            │ {'status': 'unknown', 'metadata_supplied': False, 'provenance_supplied': False, 'warnings': ['data-quality metadata is not supplied', 'dataset provenance is not supplied'], 'table_count': 12}                 │
│ data_quality_report     │ data_quality.json                                                                                                                                                                                               │
│ ending_inventory        │ {'offset': 4, 'accounts': {'feature.Volume': 750.0}}                                                                                                                                                            │
│ ending_inventory_report │ ending_inventory.csv                                                                                                                                                                                            │
│ status                  │ ok                                                                                                                                                                                                              │
│ time_limit_reached      │ False                                                                                                                                                                                                           │
│ dataset                 │ {'schema_version': '0.1', 'sources': [{'path': 'recipe.xml', 'sha256': 'fae361c3f333850d45b1509d95be0a183e4d809fb133a2b102721196aeb78f2a'}, {'path': 'fragments.csv', 'sha256':                                 │
│                         │ '9fe1655c619cd8b40eabdba84af8ed986c1cedab343855ba67ba46cb84da018a'}], 'manifest_sha256': '84ed52a984442dfbf148a67582869c872915e69c5adfb09f057d3107b10f2600'}                                                    │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
[9]:
import json

summary = json.loads((work / "opt" / "summary.json").read_text())
print({key: summary[key] for key in ("incumbent_objective", "blocks_scheduled", "iterations", "seed", "status")})
print((work / "opt" / "schedule.csv").read_text())
{'incumbent_objective': 0.0, 'blocks_scheduled': 0, 'iterations': 500, 'seed': 1, 'status': 'ok'}
block_id,treatment,offset

The incumbent is an empty schedule: leaving the stand alone holds feature.Volume at 700, which meets the floor, so nothing can beat a penalty of zero. On a two-block landscape that is the whole answer.

Watch a search

ws4 watch paints the realized-versus-target window; --plain prints one frame instead of the live view, which is what a notebook wants.

[10]:
run("ws4 watch --dataset tmp/examples/quickstart/compiled --targets tmp/examples/quickstart/targets.yaml --account feature.Volume --years 5 --period-width 1 --iterations 200 --plain")
╭──────────────────────────────────────────────────────────────────────────────────────────────────────────────── ws4 watch ────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮
│ feature.Volume   objective (sum of penalties): 0                                                                                                                                                                                          │
│ iteration 200/200   6642.31 eval/s   elapsed 0.0s   seed 1   sa                                                                                                                                                                           │
╰───────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯

feature.Volume   Z +0                                                                                                                                                                                                                        
    748.1 │  ::::::::
          │####::::::
          │####::::::
          │####::::::
          │####::::::
          │####::::::
          │####::::##
          │##########
          │##########
          │##########
          │##########
        0 │##########
          └──────────                                                                                                                                                                                                                        
           1 2 3 4 5 

          feature.Volume — per 1-year period
 period  min  realized  max  shortfall  excess  status 
      1  700       700  700          0       0      ok
      2    —     712.5    —          0       0      ok
      3    —       350    —          0       0      ok
      4    —       370    —          0       0      ok
      5    —       390    —          0       0      ok
      Watch summary
┏━━━━━━━━━━━━━┳━━━━━━━━━┓
┃ key         ┃ value   ┃
┡━━━━━━━━━━━━━╇━━━━━━━━━┩
│ objective   │ 0       │
│ penalty     │ 0       │
│ evaluations │ 200     │
│ blocks      │ 0       │
│ elapsed     │ 0.03011 │
└─────────────┴─────────┘

Where to go next

  • The how-to guides, for targets with teeth, even flow, and patch size distributions.

  • 020_even_flow.ipynb, which uses the Python API on a larger estate.

Previous Next

© Copyright 2026, UBC-FRESH.

Built with Sphinx using a theme provided by Read the Docs.