Patch size-distribution targets

A patch is a set of adjacent blocks that share a criterion — a recently disturbed stand, a band of young forest, a productive stand. A patch account reports the distribution of patch sizes: how much area sits in each size class, how many patches there are, and how compact they are. Target those sub-accounts and the search has to arrange harvesting into openings of the size you choose.

Patches are not additive over blocks: a patch spans blocks, so a move is priced through a patch model and patch statistics are kept only at the years a target reads. Expect a patch run to cost more per iteration than a volume run.

Prerequisites

  • A compiled dataset with blocks that have geometry-derived adjacency, and a topology edge list (see Spatial structure and constraints).

  • A feature to define membership: a criterion curve, and the value a block must exceed.

Procedure

1. Provide the topology. A CSV of proximal block pairs, with the shortest distance between their polygons. The sample estate ships one for its 8 x 8 grid:

head -4 examples/estate/topology.csv
src_block,dst_block,distance_m
1,2,0
2,3,0
1,9,0

A distance of 0 means the polygons touch. Building this file is a one-off GIS step; the established BLOCK1,BLOCK2,DISTANCE,LENGTH column names are accepted too.

2. Define the accounts.

# examples/estate/patches.yaml
accounts:
  - name: patch.opening
    criteria: feature.Seral.regen   # what a patch is made of: a fresh opening
    threshold: 0.5                  # a block joins when its criterion exceeds this
    size_classes: [10.0, 50.0, 150.0, 400.0, .inf]
    search_distance: 0.0            # 0 joins only blocks that literally touch

size_classes are the upper bounds, in hectares. They produce the labels 0_10, 10_50, 50_150, 150_400 and 400_9999999, and each label carries the sub-accounts area, size (the share of total patch area, in percent), frequency, shape, and, for an attractor class, attractor.

Simulate a schedule and read the openings, which is the reliable way to see the classes:

ws4 simulate --dataset tmp/estate/compiled --schedule tmp/estate/schedule.csv \
             --years 10 --topology examples/estate/topology.csv --out tmp/estate/run
year  patch_count  mean_patch_area  max_patch_area  le5  le10  le50  over
   0          4.0           20.125            50.4    0     1     2     1

A run’s report_targets.csv prices these classes too: the run replays its incumbent through the simulator and folds the patch accounts into the values the report reads, so a patch target shows the same share the search priced. Simulating the same schedule is the honest cross-check, and the two agree.

3. Target a class. A size class is a share, so the usual target is a floor on the share of harvesting that lands in the class:

# tmp/howto/patch-targets.yaml
targets:
  - account: patch.harvest.10_50.size
    period: 1
    minimum: 25
    min_weight: 2000
    shape: non_linear
    period_width: 10
  # ... one per period you care about

4. Give the patch operators a weight. Two operators exist for exactly this job and ship disabled:

ws4 optimize --dataset tmp/howto/compiled --targets tmp/howto/patch-targets.yaml \
             --years 100 \
             --topology tmp/howto/topology.csv \
             --patch-accounts tmp/howto/patches.yaml \
             --merge-weight 0.3 --split-weight 0.1 \
             --time-limit 00:05:00 --seed 1 --out tmp/howto/patches-run

merge treats a gap block — the negative space between two proximal patches — so a small treatment joins two patches instead of scattering harvest. split clears an articulation point, separating one patch into two. Both follow the topology, so they change patch structure far more directly than a random move. The cluster operator (--cluster-weight) is the third shape-aware move: it rechooses a connected set of blocks.

5. Read the result. patch_accounts.csv in the run directory has one row per period, with a column per class and sub-account:

year,account,value
0,patch.harvest.10_50.size,31.2
0,patch.harvest.10_50.frequency,7
0,patch.harvest.10_50.shape,64.8

and report_targets.csv prices the class the way any other target is priced.

6. The same in Python.

from ws4.patch.accounts import PatchAccount

account = PatchAccount(
    name="patch.harvest",
    criteria="feature.Volume.managed",
    threshold=20.0,
    size_classes=(10.0, 50.0, 150.0, float("inf")),
    search_distance=0.0,
)

Pass patch_accounts=(account,) to Simulator.run for a single simulation, or point OptimizeConfig.patch_accounts_path at the YAML for a search. Optimizer.delta_evaluator takes the same accounts, which is how a script prices a patch move (Quickstart: the Python API).

Troubleshooting

  • ``KeyError`` on ``patch.*.size`` — the class label does not exist. The labels come from size_classes: bounds 10, 50, 150 give 0_10, 10_50, 50_150, so a target on 10_150 is a class you never defined.

  • Every patch is a single block — search_distance defaults to 0, which joins only blocks that share a polygon vertex. If your blocks do not touch in the topology, raise the distance; the distance_m column is the real gap, so a non-zero value means a road, a creek, or a right-of-way and the default deliberately keeps those out of a patch.

  • The patch term never fires — the criterion may match nothing (a threshold above every block’s value), or the period you targeted is one the search never disturbs. Check the criterion first: feature.Seral.regen is what a recent opening looks like, while feature.Seral.young is a band of young forest years later, so a patch of it is not an opening.

  • The search is slow — patch statistics are maintained at the years a target reads, so a patch target on every period of a 200-year horizon keeps twenty states alive. Target the periods you actually care about.

  • The share is met but the map looks wrong — a share says nothing about where the patches are. Add the spatial rules (--max-opening-ha, --min-green-up-years, --core-buffer-m) to constrain the openings themselves, and check spatial_violations.csv in a simulation run.