Running and monitoring

Treat a run as a reproducible image computation, not just a shell command that happened to finish. Record the input selection and physical frame, source revision, operation parameters, block shape, workers and memory policy. Keep fixture preparation outside the timed processing path.

Run a complete prepared example

The camera example provides a small route through acquisition selection, planned statistics, calibration maps and correction:

cargo run --release -p blockflow-camera-calibration -- \
  prepare --out /tmp/camera-demo
cargo run --release -p blockflow-camera-calibration -- \
  run --config /tmp/camera-demo/config.json --out /tmp/camera-demo/calibrated

Preparation writes data and a JSON configuration. Processing reads that configuration and uses a new output directory. Inspect the reported fit quality and validity images before replacing the fixture with real acquisitions. A command exiting successfully establishes software completion, not that a camera noise model fits your instrument.

The generated configuration separates acquisition selections from runtime settings. Keeping that distinction lets you change block shape and worker count without silently changing thresholds, image level or model parameters. Preserve the exact effective configuration with the output rather than relying on a mutable shared config file.

Observe the executor

execute_phases returns Stats and accepts a list of EventListener observers. ExecutionLog implements that listener contract; OrderLog is an alias for it. Events expose task admission, operation applications, reads, writes and other runtime behavior. An observer receives evidence about what the executor did; it does not supply a second set of numerical decisions.

The distinction between counts matters. Stats::ops_applied counts pixel-chain slot applications, not every kind of phase. Stats::blocks_admitted is the phase-kind-independent count of admitted blocks, while tasks distinguish a block in one phase from the same spatial block in another. A fragment-only run can correctly have zero pixel-chain applications while still doing substantial work.

flowchart TB
  P["Binding plan"] --> X["Executor"]
  H["Runtime hints"] --> X
  X --> S["Statistics and event listeners"]
  S --> L["Saved execution log"]
  S --> V["Progress observer"]
  L --> R["Offline replay or analysis"]
Figure 1: The plan controls dependencies; listeners receive observations after execution decisions.

For large runs, consider the retention policy of the listener itself. Keeping a complete event stream is an application allocation and can grow even when the image tasks use bounded memory. The progress module also provides streaming records for consumers that do not need the complete trace resident.

Browser progress and replay

The gui feature builds the progress binary. Its current command help is the most direct description of accepted replay, bind and asset arguments:

cargo run --release -p blockflow --features gui --bin block_gui -- --help

The binary can replay an exported order-log JSON or watch its demonstration run. It serves browser assets from its configured asset directory, --assets, or BLOCKFLOW_GUI_ASSETS; enabling the Rust feature alone does not supply a separately built browser frontend. For embedding the observer in an application, follow the live wiring in block_gui.rs. Use a saved log for repeatable inspection of scheduling behavior.

Diagnose a slow run in the right order

First inspect the dependency shape and task count. A whole-volume stage has one block, so raising block-worker concurrency cannot create independent tasks. A barrier must wait for prerequisites. Memory admission may intentionally use fewer workers than requested when their simultaneous buffers would exceed the budget. None of those cases is evidence of a stuck thread pool by itself.

Next compare CPU time, elapsed time and I/O. Low CPU with many reads can indicate storage or decoding costs; high CPU with small cores and wide neighborhoods can indicate repeated halo computation. Compare phase traffic and source footprints before assuming that a cache size or thread count is the dominant problem. Measure release builds on representative data with fixed numerical parameters.

Finally retain the intermediate that can answer the question. Hints::keep_images prevents selected images from being released after their last reader. Keep only the useful diagnostics, because retaining every phase can dominate disk use. Resume and overwrite behavior are example-specific: the finite-PSF deconvolution CLI does not implement a general resume protocol.