Watch a run
ws4 watch runs the same search as ws4 optimize and paints the result in place: one column per
period, the target window shaded, the realized value drawn on it. It is the fastest way to see which
term is binding, and the only way to see a term that never fires.
Prerequisites
A compiled dataset and a targets file (Write targets).
A terminal. The live view repaints on a fixed heartbeat, independent of the search, so the iteration rate and the objective stay current between improvements.
Procedure
1. Watch one account.
ws4 watch --dataset tmp/howto/compiled --targets tmp/howto/targets.yaml \
--account product.Harvested.CC --years 100 --period-width 10 --iterations 20000
╭───────────────────────────────── ws4 watch ──────────────────────────────────╮
│ product.Harvested.CC objective (sum of penalties): 26.1k │
│ iteration 18400/20000 1280.44 eval/s elapsed 14.4s seed 1 sa │
╰──────────────────────────────────────────────────────────────────────────────╯
product.Harvested.CC Z +26.1k
67.3k │:::::::::: min 30.0k
│ :::::::
│ :::::::
│ :::::::
30.0k │ #######
└──────────
1 2 3 4 5 6 7 8 9 10
The header carries the objective, the iteration rate, and the seed. Z is the weighted
contribution of each watched account to the objective, which is how you see which term dominates.
2. Watch several accounts side by side. Repeat --account; each gets its own window, axis,
and title, so accounts with different units read correctly:
ws4 watch --dataset tmp/howto/compiled --targets tmp/howto/level-and-flow.yaml \
--account product.Harvested.CC --account feature.Volume.managed \
--years 100 --period-width 10 --iterations 20000
A share account (a patch size class) is averaged over a period rather than summed, because summing a share would multiply it by the period length; a volume account is summed. That is how a volume target in cubic metres and a patch target in percent can be watched together.
3. Print one frame. --plain prints a single final frame instead of the live view, which is
what you want in a script or a report:
ws4 watch --dataset tmp/howto/compiled --targets tmp/howto/targets.yaml \
--account product.Harvested.CC --years 100 --period-width 10 \
--iterations 2000 --plain
4. Watch from Python. run_watch takes an optimizer, the targets, the accounts, and,
optionally, a schedule to start from — which is how a primed run continues into a flow run
without writing files in between:
from ws4.opt.watch import run_watch
run_watch(
optimizer,
targets,
["product.Harvested.CC", "feature.Volume.managed"],
period_width=10,
initial=primed_schedule,
)
Troubleshooting
The screen sits still — the repaint is on a heartbeat (
--refreshseconds, default 2), not on every improvement. Wait a beat; the header shows the iteration count advancing.Nothing appears at all — the live view needs a real terminal. Piping the output to a file or through
tailshows nothing until it exits; use--plainthere.An account shows no window — the account name does not match any target. Account names are exact:
product.Harvested.CC, notproduct.harvested.cc.The profile is flat immediately — the search started from a schedule that was already flat (a primed run, for instance), and the band has nothing left to do.
The search is slow and the iteration rate low — expected while a patch or route term is active: those terms are not additive, so more work happens per move (Performance and scale).