Configuration and feature boundaries

Separate algorithm settings, binding plan choices and runtime preferences. All three affect resource use, but they do not have the same numerical meaning. Recording only a worker count is insufficient to reproduce an image result.

Algorithm, plan and execution

Layer Examples Why keep it separate?
Algorithm Gaussian sigma, threshold, PSF, interpolation, boundary and stopping policy These define the answer being computed
Plan Phase boundaries, block grids, source footprints and element types These define a valid partition and its intermediate representation
Execution Concurrency, ready-task ranking, cache reservation and retained intermediates These govern when work runs and how much temporary state is kept

PlanBuilder records a requested assembly. Constraints and a selected Strategy can guide partitioning where the relevant API supports it. Hints carries runtime preferences. An application that explicitly appends phases has already made a materialisation choice; a runtime priority field does not later turn those phases into one kernel.

An operation’s reach follows from its algorithm and parameters. For example, changing Gaussian truncation changes both the numerical kernel and its radius. A halo is the read margin supplied to satisfy that radius. Reducing a halo independently until the plan fits memory is not a valid performance setting. See halo kinds for operations whose requirements are asymmetric, tile-dependent or whole-axis.

Runtime fields with practical consequences

Hints::concurrency limits concurrent work. Hints::priority chooses how the ready set is ranked: SchedulePriority::PhaseMajor favors a phase across blocks; SchedulePriority::BlockMajor favors advancing blocks through available phases. Both preserve dependency edges and phase images. An apparently local order can keep more phase images alive, so benchmark it rather than assuming that block-major means less memory.

Cache and prefetch settings are reservations and preferences, with actual behavior depending on the storage/execution route. A cache can retain decoded chunks read by overlapping halos. Prefetch needs a future-read source and an integrated fetch path; assigning a depth does not prove that reads overlap compute in a particular application. Storage layout and compression also affect whether repeated traffic is I/O, decompression or memory-copy work.

Hints::keep_images retains internal images beyond their last reader, which is useful for debugging or publication. Hints::release_images states that the caller will not inspect selected otherwise published images after execution. Keeping an image wins if both sets name it. These settings change lifetime, not the pixels an operation is allowed to read.

Memory policy and chosen geometry

Resolve the process cap before choosing the grid. MemoryCap records both the byte value and where it came from. Its precedence accounts for explicit values, environment and cgroups before a host-based fallback. A cap also retains an overhead reserve, so it is not identical to active compute bytes.

ChosenGrid exposes the chosen grid, assembly, predicted makespan and active sets when the grid chooser is used. Inspect these results for phases limited by memory, rather than assuming requested worker count equals actual simultaneous work. The memory guide gives a buffer calculation and explains why reducing concurrency cannot rescue a single oversized task.

For repeatable experiments, save the effective values after defaults and input metadata have been resolved. Record the selected source level’s physical frame, not only the requested level number; two datasets can use that number for different spacings.

Feature gates are not execution guarantees

The exact dependency and feature definitions live in Cargo.toml. zarr enables the filesystem image route. distributed exposes coordinator and worker binaries. gui enables progress serving. Model and non-model GPU features select separate stacks with their own model/device requirements.

A compiled backend does not imply that every operation uses it, that every phase is supported remotely, or that a resident helper becomes out-of-core. Use the chosen example’s configuration and implementation route as the starting point. Treat flags such as --workers, --memory-mb and --block as example CLI interfaces rather than universal library command-line syntax.