neofoam.framework.initialization.staged

3-stage initialization framework: spec + runner.

A solver’s pre-run setup is split into three explicit stages — LOAD, RESOLVE, BUILD — registered as decorator-driven callbacks on a StagedInitSpec and executed by a StagedInitRunner:

  • LOAD reads configuration files and instantiates model objects in isolation. Returns a LoadResult carrying the core and optional models.

  • RESOLVE wires inter-model dependencies through a ConfigContext so models can adapt their configuration to their peers.

  • BUILD produces a list of InitStep objects describing how to construct runtime objects (fields, operators, models). The framework topologically sorts and runs them via execute_initialization().

The split separates the immutable description of a pipeline (StagedInitSpec, populated by StagedInitSpecBuilder) from the mutable execution state that the run produces (StagedInitRunner’s argv, core_models, optional_models, state). The spec is hashable, reusable, and safe to share; the runner is per-instance.

See Three-stage initialization for the stage semantics and how the pipeline fits into the solver lifecycle.