pyfebiopt.optimize.parameters

Parameter reparameterization utilities for optimization workflows.

Attributes

BoundsPayload

Classes

Parameter	Scalar optimization parameter metadata.
ParameterSpace	Mapping between \(\phi\) (optimizer space) and \(\theta\).
Reparameterizer	Encapsulate \(\theta \leftrightarrow \phi\) transformations and bounds.
ParameterMapper	Helper object that exposes φ/θ conversions and bounds for the engine.

Module Contents

pyfebiopt.optimize.parameters.BoundsPayload

class pyfebiopt.optimize.parameters.Parameter

Scalar optimization parameter metadata.

name: str

theta0: float

vary: bool = True

bounds: tuple[float | None, float | None] = (None, None)

__post_init__() → None

class pyfebiopt.optimize.parameters.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 \(\phi\) (optimizer space) and \(\theta\).

Each physical parameter \(\theta_i\) is related to its optimization counterpart \(\phi_i\) by:

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

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

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

xi

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 Parameter instance or through the keyword arguments name/theta0/vary/bounds.

Returns:

The registered Parameter instance.

parameters() → list[Parameter]

Return a copy of the registered parameter specifications.

Returns:

List of Parameter definitions.

active_mask() → BoolArray

Return a boolean mask describing which parameters vary.

Returns:

Boolean array aligned with names.

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.

unpack_vec(v: collections.abc.Sequence[float]) → dict[str, float]

Convert a vector into a parameter dictionary.

Returns:

Mapping from parameter name to θ value.

property names: list[str]

Names of all registered parameters.

property theta0: dict[str, float]

Initial θ values keyed by name.

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

Return θ-space bounds keyed by parameter name.

property vary: dict[str, bool]

Flags indicating whether each parameter varies.

class pyfebiopt.optimize.parameters.Reparameterizer(space: ParameterSpace, enabled: bool)

Encapsulate \(\theta \leftrightarrow \phi\) transformations and bounds.

Store references and cache θ-space bounds.

property enabled: bool

Whether reparameterization is active.

property names: collections.abc.Sequence[str]

Parameter names.

initial_phi() → Array

Return starting φ vector respecting reparameterization.

phi_to_theta(phi_vec: Array) → Array

Convert φ vector to θ, clamping to bounds.

Returns:

θ vector after applying bounds.

bounds() → BoundsPayload

Return bounds appropriate for the current parameterisation.

theta_bounds_array() → tuple[Array, Array] | None

Return θ-space bounds as dense arrays.

phi_bounds() → tuple[Array, Array] | None

Transform θ-space bounds into φ-space bounds.

Returns:

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

phi_from_theta(theta_vec: Array) → Array

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

Returns:

φ vector corresponding to supplied θ.

dtheta_dphi(phi_vec: Array) → Array

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

Returns:

θ-space gradient for each φ component.

theta_from_phi(phi_vec: Array) → Array

Map φ values to θ-space.

Returns:

θ vector produced from φ.

clamp_theta(theta_vec: Array) → Array

Clamp θ values according to stored bounds.

Returns:

Bounded θ vector.

class pyfebiopt.optimize.parameters.ParameterMapper(space: ParameterSpace, use_reparam: bool)

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

Bridge the engine to parameter-space transformations.

property names: collections.abc.Sequence[str]

Parameter names in optimizer order.

property reparam_enabled: bool

Whether reparameterization is enabled.

initial_phi(phi0: collections.abc.Sequence[float] | None) → Array

Return initial φ vector, using overrides when provided.

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.

phi_to_theta(phi_vec: Array) → Array

Map φ vector to θ vector.

Returns:

θ vector corresponding to the provided φ values.

theta_dict(theta_vec: Array) → dict[str, float]

Convert θ vector to dict keyed by parameter name.

Returns:

Mapping of parameter names to θ values.

theta_from_phi(phi_vec: Array) → Array

Alias to phi_to_theta for clarity in callers.

Returns:

θ vector corresponding to φ.

clamp_theta(theta_vec: Array) → Array

Clamp θ vector to bounds.

Returns:

Bounded θ vector.