pyfebiopt.optimize.cases

Case definitions for FEBio optimization workflows.

Classes

`SimulationCase`	Container describing how to generate and collect a FEBio simulation.
`CaseJob`	Handle for a scheduled FEBio run.
`EvaluationResult`	Bundle residuals, metrics, and series from a solver run.
`CasePreparer`	Cache experiment data and resolve grid policies per case.
`CaseRunner`	Launch and wait for FEBio simulations.
`MetricsAssembler`	Compute fixed metrics (NRMSE, R²) from residual alignment details.
`CaseEvaluator`	Launch FEBio simulations and assemble residuals for all configured cases.

Module Contents

class pyfebiopt.optimize.cases.SimulationCase

Container describing how to generate and collect a FEBio simulation.

template: pyfebiopt.optimize.feb_bindings.FebTemplate

subfolder: str

experiments: collections.abc.Mapping[str, pyfebiopt.optimize.experiments.ExperimentSeries]

adapters: collections.abc.Mapping[str, pyfebiopt.optimize.adapters.SimulationAdapter]

omp_threads: int | None = None

grids: collections.abc.Mapping[str, Any] | None = None

__post_init__() → None: Initialize helper objects and validate experiment coverage.

prepare(theta: collections.abc.Mapping[str, float], out_root: pathlib.Path, ctx: pyfebiopt.optimize.feb_bindings.BuildContext | None = None, out_name: str | None = None) → pathlib.Path

Render a FEB file populated with the provided parameters.

Parameters:

theta – Mapping of parameter names to θ-space values.
out_root – Directory where generated files should be stored.
ctx – Optional FEB builder context with formatting preferences.
out_name – Name of the generated FEB file.

Returns:

Absolute path to the generated FEB file.

collect(feb_path: pathlib.Path) → dict[str, tuple[numpy.ndarray, numpy.ndarray]]

Read back simulation data produced by FEBio.

Parameters:: feb_path – Path to the FEB file used for the simulation run.
Returns:: Mapping from experiment identifier to simulated x/y arrays.

environment() → dict[str, str]

Return environment overrides for this simulation.

Returns:: Mapping with per-case environment definitions.

grid_policy(experiment: str) → pyfebiopt.optimize.options.GridPolicyOptions: Return the configured grid policy for a given experiment.

class pyfebiopt.optimize.cases.CaseJob

Handle for a scheduled FEBio run.

case: SimulationCase

feb_path: pathlib.Path

handle: pyfebiopt.optimize.runners.RunHandle

label: str | None = None

class pyfebiopt.optimize.cases.EvaluationResult

Bundle residuals, metrics, and series from a solver run.

residual: Array

metrics: dict[str, Any]

series: dict[str, dict[str, Any]]

class pyfebiopt.optimize.cases.CasePreparer(cases: collections.abc.Sequence[SimulationCase], logger: LoggerProtocol)

Cache experiment data and resolve grid policies per case.

Preload experiments so alignment can be reused across iterations.

logger

describe_cases() → list[collections.abc.Mapping[str, Any]]

Summarize configured cases for logging/reporting.

Returns:: List of case descriptors containing setup details for logs/monitoring.

experiments_for(case: SimulationCase) → dict[str, tuple[numpy.ndarray, numpy.ndarray, numpy.ndarray | None]]

Return cached (x, y, weight) arrays for a case.

Returns:: Mapping of experiment name to tuple of x, y, and optional weights.

target_grids(case: SimulationCase, simulations: collections.abc.Mapping[str, tuple[numpy.ndarray, numpy.ndarray]]) → dict[str, Array]

Resolve evaluation grids for each experiment/simulation pair.

Returns:: Mapping of experiment name to evaluation grid.

class pyfebiopt.optimize.cases.CaseRunner(cases: collections.abc.Sequence[SimulationCase], runner: pyfebiopt.optimize.runners.Runner)

Launch and wait for FEBio simulations.

Store case metadata and a runner implementation.

runner

launch_cases(theta: collections.abc.Mapping[str, float], iter_dir: pathlib.Path, label: str | None) → list[CaseJob]

Render FEB files for each case and submit runs to the runner.

Returns:: List of job handles keyed to their simulation cases.

finalize_cases(jobs: collections.abc.Sequence[CaseJob], residual_assembler: pyfebiopt.optimize.residuals.ResidualAssembler, preparer: CasePreparer) → tuple[list[Array], dict[str, dict[str, Any]]]

Wait for completion, collect results, and assemble residuals.

Returns:: Residual arrays per job and per-experiment detail maps.

class pyfebiopt.optimize.cases.MetricsAssembler(logger: LoggerProtocol)

Compute fixed metrics (NRMSE, R²) from residual alignment details.

Create a metrics helper with a logger for warnings.

logger

compute(details_by_key: collections.abc.Mapping[str, collections.abc.Mapping[str, object]], *, track_series: bool) → tuple[dict[str, float | dict[str, float]], dict[str, dict[str, list[float]]]]

Calculate NRMSE and R², optionally capturing the latest series.

Returns:: Tuple of metrics dict and latest series payload.

class pyfebiopt.optimize.cases.CaseEvaluator(cases: collections.abc.Sequence[SimulationCase], runner: pyfebiopt.optimize.runners.Runner, logger: LoggerProtocol)

Launch FEBio simulations and assemble residuals for all configured cases.

Wire preparer, runner, residual assembler, and metrics helpers.

runner

logger

preparer

case_runner

metrics

residual_assembler

describe_cases() → list[collections.abc.Mapping[str, Any]]: Return structured description of configured cases.

evaluate(theta: collections.abc.Mapping[str, float], iter_dir: pathlib.Path, *, label: str | None = None, track_series: bool = True) → EvaluationResult

Run all cases for the given parameters and compute metrics/residuals.

Returns:: EvaluationResult containing residuals, metrics, and series data.