pyfebiopt.optimize.cases
========================

.. py:module:: pyfebiopt.optimize.cases

.. autoapi-nested-parse::

   Case definitions for FEBio optimization workflows.



Classes
-------

.. autoapisummary::

   pyfebiopt.optimize.cases.SimulationCase
   pyfebiopt.optimize.cases.CaseJob
   pyfebiopt.optimize.cases.EvaluationResult
   pyfebiopt.optimize.cases.CasePreparer
   pyfebiopt.optimize.cases.CaseRunner
   pyfebiopt.optimize.cases.MetricsAssembler
   pyfebiopt.optimize.cases.CaseEvaluator


Module Contents
---------------

.. py:class:: SimulationCase

   Container describing how to generate and collect a FEBio simulation.


   .. py:attribute:: template
      :type:  pyfebiopt.optimize.feb_bindings.FebTemplate


   .. py:attribute:: subfolder
      :type:  str


   .. py:attribute:: experiments
      :type:  collections.abc.Mapping[str, pyfebiopt.optimize.experiments.ExperimentSeries]


   .. py:attribute:: adapters
      :type:  collections.abc.Mapping[str, pyfebiopt.optimize.adapters.SimulationAdapter]


   .. py:attribute:: omp_threads
      :type:  int | None
      :value: None



   .. py:attribute:: grids
      :type:  collections.abc.Mapping[str, Any] | None
      :value: None



   .. py:method:: __post_init__() -> None

      Initialize helper objects and validate experiment coverage.



   .. py:method:: 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.

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

      :returns: Absolute path to the generated FEB file.



   .. py:method:: collect(feb_path: pathlib.Path) -> dict[str, tuple[numpy.ndarray, numpy.ndarray]]

      Read back simulation data produced by FEBio.

      :param feb_path: Path to the FEB file used for the simulation run.

      :returns: Mapping from experiment identifier to simulated x/y arrays.



   .. py:method:: environment() -> dict[str, str]

      Return environment overrides for this simulation.

      :returns: Mapping with per-case environment definitions.



   .. py:method:: grid_policy(experiment: str) -> pyfebiopt.optimize.options.GridPolicyOptions

      Return the configured grid policy for a given experiment.



.. py:class:: CaseJob

   Handle for a scheduled FEBio run.


   .. py:attribute:: case
      :type:  SimulationCase


   .. py:attribute:: feb_path
      :type:  pathlib.Path


   .. py:attribute:: handle
      :type:  pyfebiopt.optimize.runners.RunHandle


   .. py:attribute:: label
      :type:  str | None
      :value: None



.. py:class:: EvaluationResult

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


   .. py:attribute:: residual
      :type:  Array


   .. py:attribute:: metrics
      :type:  dict[str, Any]


   .. py:attribute:: series
      :type:  dict[str, dict[str, Any]]


.. py:class:: 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.


   .. py:attribute:: logger


   .. py:method:: 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.



   .. py:method:: 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.



   .. py:method:: 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.



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

   Launch and wait for FEBio simulations.

   Store case metadata and a runner implementation.


   .. py:attribute:: runner


   .. py:method:: 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.



   .. py:method:: 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.



.. py:class:: MetricsAssembler(logger: LoggerProtocol)

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

   Create a metrics helper with a logger for warnings.


   .. py:attribute:: logger


   .. py:method:: 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.



.. py:class:: 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.


   .. py:attribute:: runner


   .. py:attribute:: logger


   .. py:attribute:: preparer


   .. py:attribute:: case_runner


   .. py:attribute:: metrics


   .. py:attribute:: residual_assembler


   .. py:method:: describe_cases() -> list[collections.abc.Mapping[str, Any]]

      Return structured description of configured cases.



   .. py:method:: 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.



