pyfebiopt.optimize.engine
=========================

.. py:module:: pyfebiopt.optimize.engine

.. autoapi-nested-parse::

   Unified optimization engine for FEBio parameter fitting.



Attributes
----------

.. autoapisummary::

   pyfebiopt.optimize.engine.Array


Classes
-------

.. autoapisummary::

   pyfebiopt.optimize.engine.OptimizeResult
   pyfebiopt.optimize.engine.IterationState
   pyfebiopt.optimize.engine.JacobianHelper
   pyfebiopt.optimize.engine.Engine


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

.. py:data:: Array

.. py:class:: OptimizeResult

   Final state of an optimization run.


   .. py:attribute:: phi
      :type:  Array


   .. py:attribute:: theta
      :type:  dict[str, float]


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


.. py:class:: IterationState

   Track iteration bookkeeping and cached evaluations.


   .. py:attribute:: progress_index
      :type:  int
      :value: 0



   .. py:attribute:: pending_initial_log
      :type:  bool
      :value: True



   .. py:attribute:: log_progress
      :type:  bool
      :value: True



   .. py:attribute:: last_phi
      :type:  Array | None
      :value: None



   .. py:attribute:: last_theta_vec
      :type:  Array | None
      :value: None



   .. py:attribute:: last_residual
      :type:  Array | None
      :value: None



   .. py:attribute:: last_iter_dir
      :type:  pathlib.Path | None
      :value: None



   .. py:attribute:: last_cost
      :type:  float | None
      :value: None



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


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


   .. py:attribute:: cached_jac_phi
      :type:  Array | None
      :value: None



   .. py:attribute:: cached_jacobian
      :type:  Array | None
      :value: None



   .. py:method:: reset(*, log_progress: bool) -> None

      Clear state between optimization runs.



   .. py:method:: cache_evaluation(phi_vec: Array, theta_vec: Array, residual: Array, iter_dir: pathlib.Path, metrics: collections.abc.Mapping[str, Any], series: collections.abc.Mapping[str, dict[str, Any]]) -> None

      Persist the latest evaluation payload.



   .. py:method:: next_index() -> int

      Return and increment the iteration index.



   .. py:method:: cache_jacobian(phi_vec: Array, J: Array) -> None

      Store a Jacobian associated with a specific phi vector.



   .. py:method:: cached_jac(phi_vec: Array) -> Array | None

      Return a cached Jacobian matching ``phi_vec`` if available.



.. py:class:: JacobianHelper(jacobian: pyfebiopt.optimize.jacobian.JacobianComputer, case_evaluator: pyfebiopt.optimize.cases.CaseEvaluator, mapper: pyfebiopt.optimize.parameters.ParameterMapper, workspace: pyfebiopt.optimize.storage.StorageWorkspace, param_names: collections.abc.Sequence[str])

   Handle Jacobian scheduling/finalisation to keep Engine slim.

   Coordinate Jacobian evaluations, optionally in parallel.


   .. py:attribute:: jacobian


   .. py:attribute:: case_evaluator


   .. py:attribute:: mapper


   .. py:attribute:: workspace


   .. py:attribute:: param_names


   .. py:method:: compute(phi_vec: Array, state: IterationState) -> Array

      Return a forward-difference Jacobian for ``phi_vec``.



.. py:class:: Engine(parameter_space: pyfebiopt.optimize.parameters.ParameterSpace, cases: collections.abc.Sequence[pyfebiopt.optimize.cases.SimulationCase], *, options: pyfebiopt.optimize.options.EngineOptions | None = None)

   Coordinate FEBio simulations and optimization loops.

   Initialize the engine, wiring runner, reporter, mapper, and helpers.


   .. py:attribute:: parameter_space


   .. py:attribute:: workspace


   .. py:attribute:: workdir
      :value: None



   .. py:attribute:: persist_root


   .. py:attribute:: jacobian
      :type:  pyfebiopt.optimize.jacobian.JacobianComputer | None


   .. py:attribute:: case_evaluator


   .. py:attribute:: artifact_exporter


   .. py:attribute:: interrupts


   .. py:attribute:: parameter_mapper


   .. py:attribute:: optimizer_adapter


   .. py:attribute:: reporter
      :type:  pyfebiopt.optimize.reporting.Reporter


   .. py:attribute:: state


   .. py:attribute:: jac_helper


   .. py:method:: run(*, phi0: collections.abc.Sequence[float] | None = None, bounds: collections.abc.Sequence[tuple[float, float]] | None = None, verbose: bool = True, callbacks: collections.abc.Iterable[collections.abc.Callable[[Array, float], None]] | None = None) -> OptimizeResult

      Execute the optimization loop and return the optimizer's final solution.

      :returns: OptimizeResult with optimal φ/θ and optimizer metadata.



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

      Cleanly stop the runner.