neofoam.framework.initialization.helpers

Helper Functions for Lazy Initialization

Provides convenience functions for creating InitStep objects with common patterns.

class neofoam.framework.initialization.helpers.BuildsInitSteps(*args, **kwargs)

Bases: Protocol

Protocol matched by objects that contribute InitStep lists.

Models / sub-systems implement run_build() to expose their initialization steps to InitializerBuilder. The Protocol gives the contract a name (mypy can check it) and replaces the duck-typed hasattr(item, "run_build") checks used elsewhere.

class neofoam.framework.initialization.helpers.InitializerBuilder

Bases: object

Fluent builder for constructing lazy initializers.

Provides a chainable API for building lists of InitStep objects, making initialization code more readable and maintainable.

Example:

builder = InitializerBuilder() initializers = (

builder .add_resource(“mesh”, mesh_config) .add_model(“algorithm”, algorithm) .add_field(“U”, depends_on=[“mesh”], value=initial_velocity) .add_field(“p”, depends_on=[“mesh”], value=lambda ctx: compute_pressure(ctx)) .build()

)

add(initializer: InitStep) → InitializerBuilder

Add a pre-constructed InitStep object.

Args:

initializer: InitStep object to add

Returns:

Self for chaining

add_core_models(core_models: List[Any]) → InitializerBuilder

Add core models with their build() InitStep objects.

For each core model: 1. Adds the model instance to the models registry 2. Calls build() if available and adds normalized InitStep objects

Args:

core_models: List of core model instances with optional names

Returns:

Self for chaining

Example:

builder.add_core_models([(“algorithm”, algorithm), (“core2”, core_model2)])

add_field(name: str, depends_on: List[str], value: Any | Callable[[dict[str, Any]], Any]) → InitializerBuilder

Add a field with ‘fields.’ prefix.

Args:

name: Field name (without ‘fields.’ prefix) depends_on: List of dependency names value: Constant value or callable that computes the value

Returns:

Self for chaining

add_model(name: str, value: Any) → InitializerBuilder

Add a model with ‘models.’ prefix.

Args:

name: Model name (without ‘models.’ prefix) value: The model instance or callable to create it

Returns:

Self for chaining

add_operator(name: str, depends_on: List[str], value: Any | Callable[[dict[str, Any]], Any]) → InitializerBuilder

Add an operator with ‘operators.’ prefix.

Args:

name: Operator name (without ‘operators.’ prefix) depends_on: List of dependency names value: Operator instance or callable to create it

Returns:

Self for chaining

add_optional_models(optional_models: List[Any]) → InitializerBuilder

Add optional models by calling their run_build() methods.

Args:

optional_models: List of optional model instances

Returns:

Self for chaining

add_resource(name: str, value: Any) → InitializerBuilder

Add a top-level resource (mesh, domain, config, etc.).

Args:

name: Resource name value: The resource value (will be captured in lambda)

Returns:

Self for chaining

build() → List[InitStep]

Return the constructed list of initializers.

Returns:

List of InitStep objects

extend(initializers: List[InitStep]) → InitializerBuilder

Add multiple InitStep objects at once.

Args:

initializers: List of InitStep objects

Returns:

Self for chaining

neofoam.framework.initialization.helpers.field(name: str, create: Callable[[dict[str, Any]], Any], depends_on: List[str] | None = None) → InitStep

Helper for creating field lazy initializers.

Automatically prefixes name with “fields.” and sets category.

Args:

name: Field name (e.g., “U”, “p”, “nu”) create: Function that creates the field depends_on: List of dependencies (default: [])

Returns:

InitStep for the field

Example:

field(“U”, create=lambda ctx: create_vector_field(ctx[“mesh”], U0), depends_on=[“mesh”])

neofoam.framework.initialization.helpers.lazy(name: str, create: Callable[[dict[str, Any]], Any], depends_on: List[str] | None = None) → InitStep

General-purpose helper for creating lazy initializers.

Use this for objects that don’t fit the field/operator/model categories (e.g., mesh, runtime, solver loops).

Args:

name: Object name (e.g., “mesh”, “runtime”, “piso_loop”) create: Function that creates the object depends_on: List of dependencies (default: [])

Returns:

InitStep for the object

Example:

lazy(“mesh”, create=lambda ctx: mesh)

neofoam.framework.initialization.helpers.model(name: str, create: Callable[[dict[str, Any]], Any], depends_on: List[str] | None = None) → InitStep

Helper for creating model instance lazy initializers.

Automatically prefixes name with “models.” and sets category.

Args:

name: Model name (e.g., “transport”, “turbulence”, “algorithm”) create: Function that creates the model depends_on: List of dependencies

Returns:

InitStep for the model

Example:

model(“transport”, depends_on=[“fields.U”], create=lambda ctx: …)

neofoam.framework.initialization.helpers.operator(name: str, create: Callable[[dict[str, Any]], Any], depends_on: List[str] | None = None) → InitStep

Helper for creating operator lazy initializers.

Automatically prefixes name with “operators.” and sets category.

Args:

name: Operator name (e.g., “momentum”, “pressure_poisson”) create: Function that creates the operator depends_on: List of dependencies

Returns:

InitStep for the operator

Example:

operator(“momentum”, depends_on=[“fields.U”, “fields.p”], create=lambda ctx: …)