From 2c1a8b4f8035994b5fa089ef05783ecd9e3424ca Mon Sep 17 00:00:00 2001
From: spline2hg <181270613+spline2hg@users.noreply.github.com>
Date: Tue, 8 Jul 2025 19:15:54 +0000
Subject: [PATCH 1/2] expose converter for InternalOptimizationProblem

---
 .../internal_optimization_problem.py          | 44 +++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/src/optimagic/optimization/internal_optimization_problem.py b/src/optimagic/optimization/internal_optimization_problem.py
index 08db47209..8c4fbb76f 100644
--- a/src/optimagic/optimization/internal_optimization_problem.py
+++ b/src/optimagic/optimization/internal_optimization_problem.py
@@ -274,6 +274,50 @@ 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:
+
+                >>> # User provides parameters in external format (e.g., nested dict)
+                >>> user_params = {"a": 1.0, "b": {"c": 2.0, "d": 3.0}}
+                >>>
+                >>> # Algorithm needs these in a flat internal array format
+                >>> # Assume 'problem' is an object with this converter property
+                >>> 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

From ce39ad84dc441fe046bf29106aeae9b7abb5f627 Mon Sep 17 00:00:00 2001
From: spline2hg <181270613+spline2hg@users.noreply.github.com>
Date: Thu, 10 Jul 2025 19:09:40 +0000
Subject: [PATCH 2/2] fix converter docstring

---
 .../optimization/internal_optimization_problem.py | 15 +++++++++++----
 1 file changed, 11 insertions(+), 4 deletions(-)

diff --git a/src/optimagic/optimization/internal_optimization_problem.py b/src/optimagic/optimization/internal_optimization_problem.py
index 8c4fbb76f..3d630c7bf 100644
--- a/src/optimagic/optimization/internal_optimization_problem.py
+++ b/src/optimagic/optimization/internal_optimization_problem.py
@@ -306,11 +306,18 @@ def converter(self) -> Converter:
             Here's how an optimization algorithm might use the converter internally
             to prepare parameters for the optimizer:
 
-                >>> # User provides parameters in external format (e.g., nested dict)
-                >>> user_params = {"a": 1.0, "b": {"c": 2.0, "d": 3.0}}
+                >>> from optimagic.optimization.internal_optimization_problem import (
+                ...     SphereExampleInternalOptimizationProblem
+                ... )
+                >>> import numpy as np
                 >>>
-                >>> # Algorithm needs these in a flat internal array format
-                >>> # Assume 'problem' is an object with this converter property
+                >>> # 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.])