Expose converter

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