pyfebiopt.optimize.parameters
=============================

.. py:module:: pyfebiopt.optimize.parameters

.. autoapi-nested-parse::

   Parameter reparameterization utilities for optimization workflows.



Attributes
----------

.. autoapisummary::

   pyfebiopt.optimize.parameters.BoundsPayload


Classes
-------

.. autoapisummary::

   pyfebiopt.optimize.parameters.Parameter
   pyfebiopt.optimize.parameters.ParameterSpace
   pyfebiopt.optimize.parameters.Reparameterizer
   pyfebiopt.optimize.parameters.ParameterMapper


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

.. py:data:: BoundsPayload

.. py:class:: Parameter

   Scalar optimization parameter metadata.


   .. py:attribute:: name
      :type:  str


   .. py:attribute:: theta0
      :type:  float


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



   .. py:attribute:: bounds
      :type:  tuple[float | None, float | None]
      :value: (None, None)



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


.. py:class:: ParameterSpace(names: collections.abc.Sequence[str] | None = None, theta0: collections.abc.Mapping[str, float] | None = None, *, xi: float = 10.0, vary: collections.abc.Mapping[str, bool] | None = None, theta_bounds: collections.abc.Mapping[str, tuple[float | None, float | None]] | None = None, parameters: collections.abc.Iterable[Parameter] | None = None)

   Mapping between :math:`\phi` (optimizer space) and :math:`\theta`.

   Each physical parameter :math:`\theta_i` is related to its optimization
   counterpart :math:`\phi_i` by:

   .. math::

      \theta_i = \theta_{0,i} \xi^{\phi_i}

   The exponential reparameterization keeps :math:`\theta` positive while allowing
   unconstrained optimization in :math:`\phi`-space. Parameters can be supplied
   either through the legacy
   constructor arguments or incrementally via :meth:`add_parameter`.

   Create a parameter space using legacy args or explicit Parameter objects.


   .. py:attribute:: xi


   .. py:method:: add_parameter(parameter: Parameter | None = None, *, name: str | None = None, theta0: float | None = None, vary: bool = True, bounds: tuple[float | None, float | None] | None = None) -> Parameter

      Register a new optimization parameter.

      Parameters can be supplied either as a :class:`Parameter` instance or through
      the keyword arguments ``name``/``theta0``/``vary``/``bounds``.

      :returns: The registered Parameter instance.



   .. py:method:: parameters() -> list[Parameter]

      Return a copy of the registered parameter specifications.

      :returns: List of Parameter definitions.



   .. py:method:: active_mask() -> BoolArray

      Return a boolean mask describing which parameters vary.

      :returns: Boolean array aligned with ``names``.



   .. py:method:: pack_dict(d: collections.abc.Mapping[str, float]) -> Array

      Pack a parameter dictionary into a vector ordered by ``names``.

      :returns: θ vector ordered to match ``names``.



   .. py:method:: unpack_vec(v: collections.abc.Sequence[float]) -> dict[str, float]

      Convert a vector into a parameter dictionary.

      :returns: Mapping from parameter name to θ value.



   .. py:property:: names
      :type: list[str]


      Names of all registered parameters.


   .. py:property:: theta0
      :type: dict[str, float]


      Initial θ values keyed by name.


   .. py:property:: theta_bounds
      :type: dict[str, tuple[float | None, float | None]]


      Return θ-space bounds keyed by parameter name.


   .. py:property:: vary
      :type: dict[str, bool]


      Flags indicating whether each parameter varies.


.. py:class:: Reparameterizer(space: ParameterSpace, enabled: bool)

   Encapsulate :math:`\theta \leftrightarrow \phi` transformations and bounds.

   Store references and cache θ-space bounds.


   .. py:property:: enabled
      :type: bool


      Whether reparameterization is active.


   .. py:property:: names
      :type: collections.abc.Sequence[str]


      Parameter names.


   .. py:method:: initial_phi() -> Array

      Return starting φ vector respecting reparameterization.



   .. py:method:: phi_to_theta(phi_vec: Array) -> Array

      Convert φ vector to θ, clamping to bounds.

      :returns: θ vector after applying bounds.



   .. py:method:: bounds() -> BoundsPayload

      Return bounds appropriate for the current parameterisation.



   .. py:method:: theta_bounds_array() -> tuple[Array, Array] | None

      Return θ-space bounds as dense arrays.



   .. py:method:: phi_bounds() -> tuple[Array, Array] | None

      Transform θ-space bounds into φ-space bounds.

      :returns: Tuple of lower/upper φ bounds or ``None`` when unbounded.



   .. py:method:: phi_from_theta(theta_vec: Array) -> Array

      Map θ values back into φ-space, tolerating zero bounds via eps nudging.

      :returns: φ vector corresponding to supplied θ.



   .. py:method:: dtheta_dphi(phi_vec: Array) -> Array

      Return ∂θ/∂φ for the provided φ vector.

      :returns: θ-space gradient for each φ component.



   .. py:method:: theta_from_phi(phi_vec: Array) -> Array

      Map φ values to θ-space.

      :returns: θ vector produced from φ.



   .. py:method:: clamp_theta(theta_vec: Array) -> Array

      Clamp θ values according to stored bounds.

      :returns: Bounded θ vector.



.. py:class:: ParameterMapper(space: ParameterSpace, use_reparam: bool)

   Helper object that exposes φ/θ conversions and bounds for the engine.

   Bridge the engine to parameter-space transformations.


   .. py:property:: names
      :type: collections.abc.Sequence[str]


      Parameter names in optimizer order.


   .. py:property:: reparam_enabled
      :type: bool


      Whether reparameterization is enabled.


   .. py:method:: initial_phi(phi0: collections.abc.Sequence[float] | None) -> Array

      Return initial φ vector, using overrides when provided.



   .. py:method:: bounds(bounds: collections.abc.Sequence[tuple[float, float]] | None) -> BoundsPayload

      Return bounds payload, preferring caller-provided bounds when set.

      Parameters flagged with ``vary=False`` are pinned to their initial value by
      forcing lower==upper for that component.



   .. py:method:: phi_to_theta(phi_vec: Array) -> Array

      Map φ vector to θ vector.

      :returns: θ vector corresponding to the provided φ values.



   .. py:method:: theta_dict(theta_vec: Array) -> dict[str, float]

      Convert θ vector to dict keyed by parameter name.

      :returns: Mapping of parameter names to θ values.



   .. py:method:: theta_from_phi(phi_vec: Array) -> Array

      Alias to phi_to_theta for clarity in callers.

      :returns: θ vector corresponding to φ.



   .. py:method:: clamp_theta(theta_vec: Array) -> Array

      Clamp θ vector to bounds.

      :returns: Bounded θ vector.



