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.