diff --git a/src/optimagic/optimization/internal_optimization_problem.py b/src/optimagic/optimization/internal_optimization_problem.py index 08db47209..3d630c7bf 100644 --- a/src/optimagic/optimization/internal_optimization_problem.py +++ b/src/optimagic/optimization/internal_optimization_problem.py @@ -274,6 +274,57 @@ def bounds(self) -> InternalBounds: """Bounds of the optimization problem.""" return self._bounds + @property + def converter(self) -> Converter: + """Converter between external and internal parameter representation. + + The converter transforms parameters between their user-provided + representation (the external representation) and the flat numpy array used + by the optimizer (the internal representation). + + This transformation includes: + - Flattening and unflattening of pytree structures. + - Applying parameter constraints via reparametrizations. + - Scaling and unscaling of parameter values. + + The Converter object provides the following main attributes: + + - ``params_to_internal``: Callable that converts a pytree of external + parameters to a flat numpy array of internal parameters. + - ``params_from_internal``: Callable that converts a flat numpy array of + internal parameters to a pytree of external parameters. + - ``derivative_to_internal``: Callable that converts the derivative + from the external parameter space to the internal space. + - ``has_transforming_constraints``: Boolean that is True if the conversion + involves constraints that are handled by reparametrization. + + Examples: + The converter is particularly useful for algorithms that require initial + values in the internal (flat) parameter space, while allowing the user + to specify these values in the more convenient external (pytree) format. + + Here's how an optimization algorithm might use the converter internally + to prepare parameters for the optimizer: + + >>> from optimagic.optimization.internal_optimization_problem import ( + ... SphereExampleInternalOptimizationProblem + ... ) + >>> import numpy as np + >>> + >>> # Optimization problem instance. + >>> problem = SphereExampleInternalOptimizationProblem() + >>> + >>> # User provided parameters in external format. + >>> user_params = np.array([1.0, 2.0, 3.0]) + >>> + >>> # Convert to internal format for optimization algorithms. + >>> internal_params = problem.converter.params_to_internal(user_params) + >>> internal_params + array([1., 2., 3.]) + + """ + return self._converter + @property def linear_constraints(self) -> list[dict[str, Any]] | None: # TODO: write a docstring as soon as we actually use this