added initial wrapper for migrad (#568)

Author: spline2hg

.tools/envs/testenv-linux.yml

@@ -27,6 +27,7 @@ dependencies:
   - pyyaml  # dev, tests
   - jinja2  # dev, tests
   - annotated-types  # dev, tests
+  - iminuit  # dev, tests
   - pip:  # dev, tests, docs
       - DFO-LS>=1.5.3  # dev, tests
       - Py-BOBYQA  # dev, tests

.tools/envs/testenv-numpy.yml

@@ -25,6 +25,7 @@ dependencies:
   - pyyaml  # dev, tests
   - jinja2  # dev, tests
   - annotated-types  # dev, tests
+  - iminuit  # dev, tests
   - pip:  # dev, tests, docs
       - DFO-LS>=1.5.3  # dev, tests
       - Py-BOBYQA  # dev, tests

.tools/envs/testenv-others.yml

@@ -25,6 +25,7 @@ dependencies:
   - pyyaml  # dev, tests
   - jinja2  # dev, tests
   - annotated-types  # dev, tests
+  - iminuit  # dev, tests
   - pip:  # dev, tests, docs
       - DFO-LS>=1.5.3  # dev, tests
       - Py-BOBYQA  # dev, tests

.tools/envs/testenv-pandas.yml

@@ -25,6 +25,7 @@ dependencies:
   - pyyaml  # dev, tests
   - jinja2  # dev, tests
   - annotated-types  # dev, tests
+  - iminuit  # dev, tests
   - pip:  # dev, tests, docs
       - DFO-LS>=1.5.3  # dev, tests
       - Py-BOBYQA  # dev, tests

docs/source/algorithms.md

@@ -3936,6 +3936,54 @@ addition to optimagic when using an NLOPT algorithm. To install nlopt run
       10 * (number of parameters + 1).
 ```
 
+## Optimizers from iminuit
+
+optimagic supports the [IMINUIT MIGRAD Optimizer](https://iminuit.readthedocs.io/). To
+use MIGRAD, you need to have
+[the iminuit package](https://github.com/scikit-hep/iminuit) installed (pip install
+iminuit).
+
+```{eval-rst}
+.. dropdown::  iminuit_migrad
+
+    .. code-block::
+
+        "iminuit_migrad"
+
+    `MIGRAD <https://iminuit.readthedocs.io/en/stable/reference.html#iminuit.Minuit.migrad>`_ is 
+    the workhorse algorithm of the MINUIT optimization suite, which has been widely used in the 
+    high-energy physics community since 1975. The IMINUIT package is a Python interface to the 
+    Minuit2 C++ library developed by CERN.
+
+    Migrad uses a quasi-Newton method, updating the Hessian matrix iteratively
+    to guide the optimization. The algorithm adapts dynamically to challenging landscapes
+    using several key techniques:
+
+    - **Quasi-Newton updates**: The Hessian is updated iteratively rather than recalculated at 
+      each step, improving efficiency.
+    - **Steepest descent fallback**: When the Hessian update fails, Migrad falls back to steepest
+      descent with line search.
+    - **Box constraints handling**: Parameters with bounds are transformed internally to ensure 
+      they remain within allowed limits.
+    - **Heuristics for numerical stability**: Special cases such as flat gradients or singular 
+      Hessians are managed using pre-defined heuristics.
+    - **Stopping criteria based on Estimated Distance to Minimum (EDM)**: The optimization halts 
+      when the predicted improvement becomes sufficiently small.
+              
+    For details see :cite:`JAMES1975343`.
+
+    **Optimizer Parameters:**  
+
+    - **stopping.maxfun** (int): Maximum number of function evaluations. If reached, the optimization stops 
+      but this is not counted as successful convergence. Function evaluations used for numerical gradient 
+      calculations do not count toward this limit. Default is 1,000,000.
+
+    - **n_restarts** (int): Number of times to restart the optimizer if convergence is not reached.
+
+      - A value of 1 (the default) indicates that the optimizer will only run once, disabling the restart feature.  
+      - Values greater than 1 specify the maximum number of restart attempts.  
+```
+
 ## References
 
 ```{eval-rst}

docs/source/refs.bib

@@ -893,4 +893,17 @@ @book{Conn2009
 URL = {https://epubs.siam.org/doi/abs/10.1137/1.9780898718768},
 }
 
+@article{JAMES1975343,
+title = {Minuit - a system for function minimization and analysis of the parameter errors and correlations},
+journal = {Computer Physics Communications},
+volume = {10},
+number = {6},
+pages = {343-367},
+year = {1975},
+issn = {0010-4655},
+doi = {https://doi.org/10.1016/0010-4655(75)90039-9},
+url = {https://www.sciencedirect.com/science/article/pii/0010465575900399},
+author = {F. James and M. Roos}
+}
+
 @Comment{jabref-meta: databaseType:bibtex;}

environment.yml

@@ -37,6 +37,7 @@ dependencies:
   - jinja2  # dev, tests
   - furo  # dev, docs
   - annotated-types  # dev, tests
+  - iminuit  # dev, tests
   - pip:  # dev, tests, docs
       - DFO-LS>=1.5.3  # dev, tests
       - Py-BOBYQA  # dev, tests

pyproject.toml

@@ -16,6 +16,7 @@ dependencies = [
     "sqlalchemy>=1.3",
     "annotated-types",
     "typing-extensions",
+    "iminuit",
 ]
 dynamic = ["version"]
 keywords = [
@@ -378,5 +379,6 @@ module = [
     "optimagic._version",
     "annotated_types",
     "pdbp",
+    "iminuit",
   ]
 ignore_missing_imports = true

src/optimagic/algorithms.py

@@ -14,6 +14,7 @@
 from optimagic.optimization.algorithm import Algorithm
 from optimagic.optimizers.bhhh import BHHH
 from optimagic.optimizers.fides import Fides
+from optimagic.optimizers.iminuit_migrad import IminuitMigrad
 from optimagic.optimizers.ipopt import Ipopt
 from optimagic.optimizers.nag_optimizers import NagDFOLS, NagPyBOBYQA
 from optimagic.optimizers.neldermead import NelderMeadParallel
@@ -286,6 +287,7 @@ def Scalar(self) -> BoundedGradientBasedLocalNonlinearConstrainedScalarAlgorithm
 @dataclass(frozen=True)
 class BoundedGradientBasedLocalScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -840,6 +842,7 @@ def NonlinearConstrained(
 @dataclass(frozen=True)
 class BoundedGradientBasedLocalAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -889,6 +892,7 @@ def Scalar(self) -> GradientBasedLocalNonlinearConstrainedScalarAlgorithms:
 @dataclass(frozen=True)
 class GradientBasedLocalScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -956,6 +960,7 @@ def Scalar(self) -> BoundedGradientBasedNonlinearConstrainedScalarAlgorithms:
 @dataclass(frozen=True)
 class BoundedGradientBasedScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -1674,6 +1679,7 @@ def Scalar(self) -> BoundedLocalNonlinearConstrainedScalarAlgorithms:
 @dataclass(frozen=True)
 class BoundedLocalScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA
     nlopt_bobyqa: Type[NloptBOBYQA] = NloptBOBYQA
@@ -1943,6 +1949,7 @@ def Scalar(self) -> GlobalGradientBasedScalarAlgorithms:
 class GradientBasedLocalAlgorithms(AlgoSelection):
     bhhh: Type[BHHH] = BHHH
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -1985,6 +1992,7 @@ def Scalar(self) -> GradientBasedLocalScalarAlgorithms:
 @dataclass(frozen=True)
 class BoundedGradientBasedAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -2054,6 +2062,7 @@ def Scalar(self) -> GradientBasedNonlinearConstrainedScalarAlgorithms:
 @dataclass(frozen=True)
 class GradientBasedScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -2577,6 +2586,7 @@ def Scalar(self) -> GlobalParallelScalarAlgorithms:
 @dataclass(frozen=True)
 class BoundedLocalAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_dfols: Type[NagDFOLS] = NagDFOLS
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA
@@ -2659,6 +2669,7 @@ def Scalar(self) -> LocalNonlinearConstrainedScalarAlgorithms:
 @dataclass(frozen=True)
 class LocalScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA
     neldermead_parallel: Type[NelderMeadParallel] = NelderMeadParallel
@@ -2809,6 +2820,7 @@ def Scalar(self) -> BoundedNonlinearConstrainedScalarAlgorithms:
 @dataclass(frozen=True)
 class BoundedScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA
     nlopt_bobyqa: Type[NloptBOBYQA] = NloptBOBYQA
@@ -3063,6 +3075,7 @@ def Local(self) -> LeastSquaresLocalParallelAlgorithms:
 class GradientBasedAlgorithms(AlgoSelection):
     bhhh: Type[BHHH] = BHHH
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nlopt_ccsaq: Type[NloptCCSAQ] = NloptCCSAQ
     nlopt_lbfgsb: Type[NloptLBFGSB] = NloptLBFGSB
@@ -3246,6 +3259,7 @@ def Scalar(self) -> GlobalScalarAlgorithms:
 class LocalAlgorithms(AlgoSelection):
     bhhh: Type[BHHH] = BHHH
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_dfols: Type[NagDFOLS] = NagDFOLS
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA
@@ -3316,6 +3330,7 @@ def Scalar(self) -> LocalScalarAlgorithms:
 @dataclass(frozen=True)
 class BoundedAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_dfols: Type[NagDFOLS] = NagDFOLS
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA
@@ -3451,6 +3466,7 @@ def Scalar(self) -> NonlinearConstrainedScalarAlgorithms:
 @dataclass(frozen=True)
 class ScalarAlgorithms(AlgoSelection):
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA
     neldermead_parallel: Type[NelderMeadParallel] = NelderMeadParallel
@@ -3625,6 +3641,7 @@ def Scalar(self) -> ParallelScalarAlgorithms:
 class Algorithms(AlgoSelection):
     bhhh: Type[BHHH] = BHHH
     fides: Type[Fides] = Fides
+    iminuit_migrad: Type[IminuitMigrad] = IminuitMigrad
     ipopt: Type[Ipopt] = Ipopt
     nag_dfols: Type[NagDFOLS] = NagDFOLS
     nag_pybobyqa: Type[NagPyBOBYQA] = NagPyBOBYQA

src/optimagic/config.py

@@ -92,6 +92,14 @@
     IS_NUMBA_INSTALLED = True
 
 
+try:
+    import iminuit  # noqa: F401
+except ImportError:
+    IS_IMINUIT_INSTALLED = False
+else:
+    IS_IMINUIT_INSTALLED = True
+
+
 # ======================================================================================
 # Check if pandas version is newer or equal to version 2.1.0
 # ======================================================================================

src/optimagic/optimization/algo_options.py

@@ -122,6 +122,19 @@
 
 """
 
+N_RESTARTS = 1
+"""int: Number of times to restart the optimizer if convergence is not reached.
+    This parameter controls how many times the optimization process is restarted
+    in an attempt to achieve convergence.
+
+    - A value of 1 (the default) indicates that the optimizer will only run once,
+      disabling the restart feature.
+    - Values greater than 1 specify the maximum number of restart attempts.
+
+    Note: This is distinct from `STOPPING_MAXITER`, which limits the number of
+    iterations within a single optimizer run, not the number of restarts.
+"""
+
 
 def get_population_size(population_size, x, lower_bound=10):
     """Default population size for genetic algorithms."""