Write targets

A target states what the schedule should achieve. This guide covers the vocabulary, the two things that most often go wrong (a term that drowns out the others, and a target that never fires), and how to fix both.

Prerequisites

  • A compiled dataset (Prepare a dataset).

  • A rough idea of the accounts you care about. feature.* accounts are standing values, product.* accounts are what treatments produced, and patch.* accounts describe the shape of the map (see Patch size-distribution targets).

Procedure

1. Write the targets. A target names an account, an accounting period, and a bound. The simplest useful file has two targets: a floor on harvest, and a floor that stops the search stripping the later years.

# tmp/howto/targets.yaml
targets:
  - account: product.Harvested.CC     # produce at least 30,000 m3 in period 1
    period: 1
    minimum: 30000
    period_width: 10
  - account: feature.Volume.managed   # and keep at least 100,000 m3 standing in period 1
    period: 1
    minimum: 100000
    period_width: 10

An inactive target is kept in the file and reported, but the search does not price it. Use active: false to park a target while you compare alternatives, or the On checkbox in the web targets table:

- account: feature.Volume.managed
  period: 1
  minimum: 100000
  period_width: 10
  active: false

2. Decide the weights. min_weight and max_weight say how much a deviation costs. Defaults are 1.0. A weight much larger than the others makes its term dominate, which is sometimes exactly what you want (a hard constraint you never want violated) and sometimes the bug (one term eats the whole objective).

- account: patch.harvest.10_50.size
  period: 1
  minimum: 25
  min_weight: 2000        # a share, in percent: worth 2000 per percent below 25
  shape: non_linear       # squared, so small misses are cheap and large ones are not

3. Choose the shape. linear charges the weighted deviation; non_linear charges the weighted squared deviation. Use non-linear when you care about being close rather than merely on the right side, which is the usual choice for a share or a flow term.

4. Say which periods. period_width groups offsets into the period a target reads: 10 means a decade, 1 a single offset. Period p >= 1 covers offsets (p - 1) * period_width through p * period_width - 1, so period: 1 with period_width: 10 is the first accounting period, covering offsets 0 to 9 and displaying as the decade ending in year 10. Period 0 is the zero-length pre-simulation snapshot at offset -1, so it is not a treatment slot. year is a display label only; write period. Add one target per period you care about, or leave later periods out — but remember that an unconstrained offset is free, and a free offset will be spent (see Your first model).

5. Search, and read the statuses.

ws4 optimize --dataset tmp/howto/compiled --targets tmp/howto/targets.yaml \
             --years 100 --time-limit 00:02:00 \
             --seed 1 --out tmp/howto/run

report_targets.csv in the run directory has one row per target: the realized value, the bounds, the penalty, and a status of met, below, or above. Read the penalties, not just the statuses: a run with every status met and a large objective is meeting the targets other than the ones you wrote.

6. Balance the weights when one term dominates. ws4 calibrate runs a short pilot search, records the largest penalty each target reaches, and writes a new targets file whose weights are rescaled so the peaks are comparable:

ws4 calibrate --dataset tmp/howto/compiled --targets tmp/howto/targets.yaml \
              --out tmp/howto/calibrated.yaml --years 100 --iterations 2000

ws4 optimize --dataset tmp/howto/compiled --targets tmp/howto/calibrated.yaml \
             --years 100 --time-limit 00:05:00 \
             --seed 1 --out tmp/howto/run

7. The same in Python. Targets are Target objects, and a YAML file is just a loader for them:

from ws4.opt.objective import Target, load_targets

targets = load_targets("tmp/howto/targets.yaml")
targets.append(Target("feature.Volume.managed", period=10, minimum=100000, period_width=10))

print(targets[0])
Target(account='product.Harvested.CC', year=10, minimum=30000, maximum=None, min_weight=1.0,
       max_weight=1.0, period_width=10, shape='linear', flow='', flow_start=0, flow_end=None,
       flow_reference=None, active=True)

In-memory targets are what the incremental evaluator takes (Quickstart: the Python API), so a script can build targets in a loop and price them without writing a file.

Troubleshooting

  • Every status is ``met`` but the result is wrong — the terms you did not state are free, so the search spent them arbitrarily. Add a target for the years and the shape you care about.

  • The search does not move — the weights are unbalanced: one term is so expensive that every move is worse. Run ws4 calibrate, or lower that term’s weight.

  • A term never fires — its weight is small next to the others, or the target is already satisfied. ws4 calibrate reports the peaks it observed, which shows you what fired.

  • A target is always ``below`` — it may be infeasible. Try it alone, with the other targets removed; if it is still below, the estate cannot deliver it in those years.

  • The search ignores a weights file — --weights is optional and kept for compatibility. The weights that apply are the min_weight and max_weight fields above; ws4 calibrate writes them into a targets file for you.