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.