[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()

The sample estate

examples/estate is a small self-contained estate: 64 blocks on an 8 x 8 grid, one clearcut treatment that can be applied more than once, a seral feature that marks fresh openings, and a road network with two mills. Everything below runs against it.

This one is mostly a command-line session, with one compile through the library.

The files

File

What it holds

recipe.xml

two lanes, one clearcut operable from age 40, the volume curves, and a seral curve that is 1 while an opening is fresh

fragments.csv

64 blocks, 8-12 ha, ages 0-100, all natural

topology.csv

the grid adjacency that makes adjacent openings a patch

vertices.csv, segments.csv, destinations.csv, linkages.csv

the road network and the two mills

route.yaml, patches.yaml, eligibility.csv

the route configuration and the patch account

Compile it

[2]:
from pathlib import Path

from ws4.build.compiler import build_canonical_dataset

work = Path("tmp/examples/estate")
work.mkdir(parents=True, exist_ok=True)
dataset = build_canonical_dataset(
    "examples/estate/recipe.xml", "examples/estate/fragments.csv", work / "compiled"
)
print(dataset)
tmp/examples/estate/compiled

Simulate a schedule: openings, and two mills

Cutting eight blocks at offset 0 opens patches on the grid and ships the volume to whichever mill is cheaper to reach.

[3]:
import pandas as pd

schedule = pd.DataFrame({"block_id": [1, 2, 9, 10, 57, 58, 63, 64], "treatment": ["CC"] * 8, "offset": [0] * 8})
(work / "schedule.csv").write_text(schedule.to_csv(index=False))

run("ws4 simulate --dataset tmp/examples/estate/compiled --schedule tmp/examples/estate/schedule.csv --years 10 --topology examples/estate/topology.csv --route-config examples/estate/route.yaml --out tmp/examples/estate/run")
Simulation complete → tmp/examples/estate/run
[4]:
values = pd.read_csv(work / "run" / "account_values.csv")
print(values[values.offset == -1].to_string(index=False))
 offset                account        value
     -1    feature.Seral.regen     0.000000
     -1 feature.Volume.managed     0.000000
     -1 feature.Volume.natural 80026.785714

feature.Seral.regen is the area in fresh openings — the criterion the patch account reads. The two product.Mill* accounts and the two haul accounts say how the volume split, and route.Total.haul is the duplicate account that adds them.

[5]:
routed = pd.read_csv(work / "run" / "route_values.csv")
print(routed.groupby("destination")[["volume", "haul_cost"]].sum().to_string())
print()
print(routed[["block_id", "destination", "volume", "length_m", "haul_cost"]].head(4).to_string(index=False))
                        volume  haul_cost
destination
destination.MILL1  3423.514286        0.4
destination.MILL2  5370.300000        0.6

 block_id       destination      volume  length_m  haul_cost
        1 destination.MILL1 1918.714286    4000.0        0.2
        2 destination.MILL1 1504.800000    4000.0        0.2
        9 destination.MILL2 1272.000000    4000.0        0.2
       10 destination.MILL2 1932.000000    4000.0        0.2

Blocks near the west end go to destination.MILL1, blocks further east to destination.MILL2: the choice is the least haul cost along the segments, not the distance to a mill.

The openings themselves

[6]:
metrics = pd.read_csv(work / "run" / "patch_metrics.csv")
print(metrics[metrics.offset <= 2].to_string(index=False))
 offset  patch_count  mean_patch_area  max_patch_area  le5  le10  le50  over
      0          3.0             27.3            42.9    0     0     3     0

Search, and read the run

A volume floor plus a haul-cost ceiling behaves predictably, and shows the route accounts folding into the objective.

[7]:
(work / "targets.yaml").write_text(
    "targets:\n"
    "- account: product.Harvested.CC\n"
    "  period: 1\n"
    "  minimum: 20000\n"
    "  period_width: 10\n"
    "- account: route.Total.haul\n"
    "  period: 1\n"
    "  maximum: 3000\n"
    "  period_width: 10\n"
)

run("ws4 optimize --dataset tmp/examples/estate/compiled --targets tmp/examples/estate/targets.yaml --years 100 --iterations 20000 --route-config examples/estate/route.yaml --threads 1 --out tmp/examples/estate/search")
                                                                                                            Optimization Summary
┏━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ key                     ┃ value                                                                                                                                                                                                           ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ incumbent_objective     │ 0.0                                                                                                                                                                                                             │
│ iterations              │ 20000                                                                                                                                                                                                           │
│ patience                │ 0                                                                                                                                                                                                               │
│ reversion               │ 0                                                                                                                                                                                                               │
│ seed                    │ 42                                                                                                                                                                                                              │
│ metaheuristic           │ sa                                                                                                                                                                                                              │
│ threshold               │ 1.0                                                                                                                                                                                                             │
│ starts                  │ 1                                                                                                                                                                                                               │
│ initial_schedule_path   │ None                                                                                                                                                                                                            │
│ blocks_scheduled        │ 24                                                                                                                                                                                                              │
│ 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': 99, 'accounts': {'feature.Seral.regen': 143.49999999999997, 'feature.Volume.managed': 29307.574999999997, 'feature.Volume.natural': 99698.14285714286}}                                              │
│ ending_inventory_report │ ending_inventory.csv                                                                                                                                                                                            │
│ status                  │ ok                                                                                                                                                                                                              │
│ time_limit_reached      │ False                                                                                                                                                                                                           │
│ dataset                 │ {'schema_version': '0.1', 'sources': [{'path': 'recipe.xml', 'sha256': 'ff05c1de6ac54f9509d423fae0597abc17b03ee9965e75819f2d6778e30f5288'}, {'path': 'fragments.csv', 'sha256':                                 │
│                         │ '5f371cb7421d65f5839f334f94911d315d8200606c29a53d87352b875b4589d9'}], 'manifest_sha256': 'd26ad2c906f0d4fe6768999b4418534c72eeadf1d4b3bdc93d7cf3b5ca1aa35a'}                                                    │
└─────────────────────────┴─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────┘
[8]:
import json

summary = json.loads((work / "search" / "summary.json").read_text())
print({key: summary[key] for key in ("incumbent_objective", "blocks_scheduled", "iterations", "status")})
print()
print(pd.read_csv(work / "search" / "report_targets.csv").to_string(index=False))
{'incumbent_objective': 0.0, 'blocks_scheduled': 24, 'iterations': 20000, 'status': 'ok'}

             account  period  year        value  minimum  maximum  raw_penalty  penalty  scale normalization  priority  kind status
product.Harvested.CC       1    10 20443.057143  20000.0      NaN          0.0      0.0    1.0          none         1 level    met
    route.Total.haul       1    10   136.092857      NaN   3000.0          0.0      0.0    1.0          none         1 level    met

What to look at next

  • docs/howto/route-products.rst walks through the road tables and the route configuration.

  • docs/howto/patch-targets.rst covers the patch accounts, the size classes and the shape-aware operators; a run’s report and a simulation of the same schedule agree on the classes.

  • docs/getting-started/architecture.rst explains why the search prices a move instead of re-simulating.