Add a built-in Levenberg-Marquardt minimizer selectable like Migrad and Fumili

Bring the dependency-free Levenberg-Marquardt solver from dev/custom-fit in
as Minimizer::LevenbergMarquardt next to Minuit2's Migrad (default) and
Fumili, selected through the FitModel constructor, SetMinimizer() or the
Python `minimizer` argument and property.

- FitModel becomes plain data (limits, fixed flags, start values, minimizer
  settings) with index and limit validation. Minuit2 user parameters are
  built per pixel in src/FitMinuit2.cpp, the only translation unit that
  includes Minuit2 headers.
- fit_3d fits through a per-thread PixelFitter so the LM path allocates
  nothing per pixel, and no minimizer allocates a per-pixel result array.
- Fixed parameters and parameters ending on a limit report an error of 0
  with every minimizer; user start values are applied before the validity
  check and clamped into the limits.
- Minuit2's Fumili cannot converge once a two-sided limit is active, so
  such pixels are refitted with Migrad. The Minuit2 minimizers keep a wide
  two-sided range for one-sided limits because Minuit2's one-sided
  transform converges markedly slower.
- The [fit] tests run every scenario through all three minimizers and
  check that they agree; the benchmark gains LM and data-cube cases.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

python/src/fit.hpp

@@ -26,7 +26,31 @@ template <typename Model> void bind_fit_model(py::module &m, const char *name) {
                       aare::Minimizer>(),
              py::arg("strategy") = 0, py::arg("max_calls") = 100,
              py::arg("tolerance") = 0.5, py::arg("compute_errors") = false,
-             py::arg("minimizer") = aare::Minimizer::Migrad)
+             py::arg("minimizer") = aare::Minimizer::Migrad,
+             R"doc(
+            Fit configuration for this model.
+
+            Parameters
+            ----------
+            strategy : int
+                Minuit2 strategy (0 = fast, 1 = Minuit2's default). Ignored
+                by ``Minimizer.LevenbergMarquardt``.
+            max_calls : int
+                Work budget per pixel: Minuit2 function calls, or model
+                evaluations for ``Minimizer.LevenbergMarquardt``. 0 selects
+                Minuit's default budget.
+            tolerance : float
+                EDM tolerance in Minuit's convention. Migrad and
+                LevenbergMarquardt stop below ``0.002 * tolerance``, Fumili
+                below ``1e-4 * tolerance``.
+            compute_errors : bool
+                Also return parameter errors: from Hesse with Migrad, from
+                the linearised covariance with Fumili and LevenbergMarquardt.
+                Fixed parameters and parameters ending on a limit report 0.
+            minimizer : Minimizer
+                ``Minimizer.Migrad`` (default), ``Minimizer.Fumili`` or
+                ``Minimizer.LevenbergMarquardt``.
+            )doc")
         .def("SetParLimits",
              py::overload_cast<unsigned int, double, double>(&FM::SetParLimits),
              py::arg("idx"), py::arg("lo"), py::arg("hi"))
@@ -92,7 +116,8 @@ template <typename Model> void bind_fit_model(py::module &m, const char *name) {
             Fit this model to 1D or 3D data using Minuit2.
 
             The minimizer is selected by the ``minimizer`` property
-            (``Minimizer.Migrad`` by default, or ``Minimizer.Fumili``).
+            (``Minimizer.Migrad`` by default, ``Minimizer.Fumili`` or
+            ``Minimizer.LevenbergMarquardt``).
 
             Parameters
             ----------
@@ -232,22 +257,67 @@ fit_dispatch(const aare::FitModel<Model> &model,
     }
 }
 
+// Resolve the model type behind a Python object and run the fit.
+py::object dispatch_any_model(
+    py::object model_obj,
+    py::array_t<double, py::array::c_style | py::array::forcecast> x,
+    py::array_t<double, py::array::c_style | py::array::forcecast> y,
+    py::object y_err_obj, int n_threads) {
+    using namespace aare::model;
+
+#define AARE_DISPATCH_MODEL(Model)                                             \
+    if (py::isinstance<aare::FitModel<Model>>(model_obj)) {                    \
+        const auto &mdl = model_obj.cast<const aare::FitModel<Model> &>();     \
+        return fit_dispatch<Model>(mdl, x, y, y_err_obj, n_threads);           \
+    }
+
+    AARE_DISPATCH_MODEL(Pol1)
+    AARE_DISPATCH_MODEL(Pol2)
+    AARE_DISPATCH_MODEL(Gaussian)
+    AARE_DISPATCH_MODEL(GaussianErfcPlateau)
+    AARE_DISPATCH_MODEL(GaussianChargeSharing)
+    AARE_DISPATCH_MODEL(GaussianChargeSharingKb)
+    AARE_DISPATCH_MODEL(RisingScurve)
+    AARE_DISPATCH_MODEL(FallingScurve)
+
+#undef AARE_DISPATCH_MODEL
+
+    throw std::runtime_error(
+        "Unknown model type. Expected Pol1, Pol2, Gaussian, "
+        "GaussianErfcPlateau, GaussianChargeSharing, GaussianChargeSharingKb, "
+        "RisingScurve or FallingScurve.");
+}
+
 void define_fit_bindings(py::module &m) {
     // The enum must exist before it is used as a constructor default below.
     py::enum_<aare::Minimizer>(m, "Minimizer", R"doc(
-        Minuit2 minimizer used by the fit models.
+        Minimizer used by the fit models.
 
-        ``Migrad`` is the default variable-metric minimizer. With
+        ``Migrad`` (default) is Minuit2's variable-metric minimizer. With
         ``compute_errors`` its parameter errors come from Hesse.
 
-        ``Fumili`` is a Gauss-Newton style minimizer that takes the gradient
-        and a linearised Hessian from the analytic derivatives of the model.
-        It usually needs far fewer function evaluations than Migrad. With
-        ``compute_errors`` its parameter errors come from the covariance of
-        the linearised Hessian, without an extra Hesse step.
+        ``Fumili`` is Minuit2's Gauss-Newton minimizer with a trust region.
+        It takes the gradient and a linearised Hessian from the analytic
+        derivatives of the model and usually needs far fewer function
+        evaluations than Migrad. Its parameter errors come from the
+        covariance of the linearised Hessian, without an extra Hesse step.
+        Minuit2's Fumili cannot converge once a two-sided limit becomes
+        active; a pixel without a valid Fumili minimum is refitted with
+        Migrad.
+
+        ``LevenbergMarquardt`` is the built-in damped Gauss-Newton solver. It
+        uses the analytic Jacobian, reflects steps at parameter limits and
+        reuses its buffers between pixels, so data cubes are fitted without
+        per-pixel allocations. Its parameter errors are
+        ``sqrt(diag((J^T J)^-1))``; ``max_calls`` counts model evaluations
+        and ``strategy`` is ignored.
+
+        With every minimizer, fixed parameters and parameters that end on a
+        limit report an error of 0 and a failed fit returns zeros.
         )doc")
         .value("Migrad", aare::Minimizer::Migrad)
-        .value("Fumili", aare::Minimizer::Fumili);
+        .value("Fumili", aare::Minimizer::Fumili)
+        .value("LevenbergMarquardt", aare::Minimizer::LevenbergMarquardt);
 
     // ── Bind model classes ──────────────────────────────────────────
     bind_fit_model<aare::model::Gaussian>(m, "Gaussian");
@@ -267,88 +337,19 @@ void define_fit_bindings(py::module &m) {
            py::array_t<double, py::array::c_style | py::array::forcecast> x,
            py::array_t<double, py::array::c_style | py::array::forcecast> y,
            py::object y_err_obj, int n_threads) -> py::object {
-            using namespace aare::model;
-
-            // ── Polynomial of degree 1 ───────
-            if (py::isinstance<aare::FitModel<Pol1>>(model_obj)) {
-                const auto &mdl =
-                    model_obj.cast<const aare::FitModel<Pol1> &>();
-                return fit_dispatch<Pol1>(mdl, x, y, y_err_obj, n_threads);
-            }
-
-            // ── Polynomial of degree 2 ───────
-            if (py::isinstance<aare::FitModel<Pol2>>(model_obj)) {
-                const auto &mdl =
-                    model_obj.cast<const aare::FitModel<Pol2> &>();
-                return fit_dispatch<Pol2>(mdl, x, y, y_err_obj, n_threads);
-            }
-
-            // ── Gaussian ───────
-            if (py::isinstance<aare::FitModel<Gaussian>>(model_obj)) {
-                const auto &mdl =
-                    model_obj.cast<const aare::FitModel<Gaussian> &>();
-                return fit_dispatch<Gaussian>(mdl, x, y, y_err_obj, n_threads);
-            }
-
-            // ── GaussianErfcPlateau ───────
-            if (py::isinstance<aare::FitModel<GaussianErfcPlateau>>(
-                    model_obj)) {
-                const auto &mdl =
-                    model_obj
-                        .cast<const aare::FitModel<GaussianErfcPlateau> &>();
-                return fit_dispatch<GaussianErfcPlateau>(mdl, x, y, y_err_obj,
-                                                         n_threads);
-            }
-
-            // ── GaussianChargeSharing ───────
-            if (py::isinstance<aare::FitModel<GaussianChargeSharing>>(
-                    model_obj)) {
-                const auto &mdl =
-                    model_obj
-                        .cast<const aare::FitModel<GaussianChargeSharing> &>();
-                return fit_dispatch<GaussianChargeSharing>(mdl, x, y, y_err_obj,
-                                                           n_threads);
-            }
-
-            // ── GaussianChargeSharingKb ───────
-            if (py::isinstance<aare::FitModel<GaussianChargeSharingKb>>(
-                    model_obj)) {
-                const auto &mdl = model_obj.cast<
-                    const aare::FitModel<GaussianChargeSharingKb> &>();
-                return fit_dispatch<GaussianChargeSharingKb>(
-                    mdl, x, y, y_err_obj, n_threads);
-            }
-
-            // ── Rising Scurve ───────
-            if (py::isinstance<aare::FitModel<RisingScurve>>(model_obj)) {
-                const auto &mdl =
-                    model_obj.cast<const aare::FitModel<RisingScurve> &>();
-                return fit_dispatch<RisingScurve>(mdl, x, y, y_err_obj,
-                                                  n_threads);
-            }
-
-            // ── Falling Scurve ───────
-            if (py::isinstance<aare::FitModel<FallingScurve>>(model_obj)) {
-                const auto &mdl =
-                    model_obj.cast<const aare::FitModel<FallingScurve> &>();
-                return fit_dispatch<FallingScurve>(mdl, x, y, y_err_obj,
-                                                   n_threads);
-            }
-
-            throw std::runtime_error(
-                "Unknown model type. Expected Pol1, Pol2, Gaussian, "
-                "RisingScurve or FallingScurve.");
+            return dispatch_any_model(model_obj, x, y, y_err_obj, n_threads);
         },
         R"(
-        Fit a model to 1D or 3D data using Minuit2.
+        Fit a model to 1D or 3D data with the minimizer selected by the
+        model's ``minimizer`` property.
  
         Parameters
         ----------
-        model : Pol1, Pol2, Gaussian, RisingScurve, or FallingScurve
-            Configured model object.  User-set limits, fixed parameters,
-            and start values take precedence over automatic estimates.
-            The model's ``minimizer`` property selects Migrad (default)
-            or Fumili.
+        model : object
+            Configured model object: Pol1, Pol2, Gaussian, GaussianErfcPlateau,
+            GaussianChargeSharing, GaussianChargeSharingKb, RisingScurve or
+            FallingScurve.  User-set limits, fixed parameters, and start values
+            take precedence over automatic estimates.
         x : array_like, shape (n_scan,)
             Scan points (e.g. energy or threshold values).
         y : array_like, shape (n_scan,) or (rows, cols, n_scan)
@@ -360,15 +361,12 @@ void define_fit_bindings(py::module &m) {
  
         Returns
         -------
-        For 1D input:
-            numpy array of shape (2*npar+1,) if compute_errors else (npar+1,).
-            Layout: [params..., (errors...,) chi2].
- 
-        For 3D input:
-            dict with keys:
-              "par"     : (rows, cols, npar) fitted parameters.
-              "par_err" : (rows, cols, npar) parameter errors (if compute_errors).
-              "chi2"    : (rows, cols)       chi-squared per pixel.
+        dict
+            ``par`` holds the fitted parameters, shape (npar,) for 1D input or
+            (rows, cols, npar) for 3D input.  ``chi2`` holds the chi-squared,
+            shape (1,) or (rows, cols).  ``par_err`` holds the parameter
+            errors when ``compute_errors`` is enabled; fixed parameters and
+            parameters on a limit report 0.  A failed fit returns zeros.
         )",
         py::arg("model"), py::arg("x"), py::arg("y"),
         py::arg("y_err") = py::none(), py::arg("n_threads") = 4);

python/tests/test_Fit.py

@@ -1,13 +1,41 @@
 # SPDX-License-Identifier: MPL-2.0
 import numpy as np
+import pytest
+
 import aare
 
+MINIMIZERS = [
+    aare.Minimizer.Migrad,
+    aare.Minimizer.Fumili,
+    aare.Minimizer.LevenbergMarquardt,
+]
 
 
-def test_gaussian_model_evaluates_and_fits_data():
+def gaussian(x, A, mu, sigma):
+    return A * np.exp(-0.5 * ((x - mu) / sigma) ** 2)
+
+
+def uses_minuit2(minimizer):
+    return minimizer != aare.Minimizer.LevenbergMarquardt
+
+
+@pytest.fixture(params=MINIMIZERS, ids=lambda m: m.name)
+def minimizer(request):
+    return request.param
+
+
+@pytest.fixture
+def gaussian_data():
+    x = np.linspace(-6.0, 6.0, 61)
+    y = gaussian(x, 120.0, 0.8, 1.3)
+    y_err = np.ones_like(y)
+    return x, y, y_err
+
+
+def test_gaussian_model_evaluates_and_fits_data(minimizer):
     x = np.linspace(-5.0, 5.0, 51)
     expected = np.array([20.0, 0.5, 1.2])
-    model = aare.Gaussian()
+    model = aare.Gaussian(minimizer=minimizer)
 
     y = model(x, expected)
     result = model.fit(x, y)
@@ -15,39 +43,185 @@ def test_gaussian_model_evaluates_and_fits_data():
     np.testing.assert_allclose(result["par"], expected, atol=2e-3)
 
 
-def test_minimizer_can_be_selected_and_fumili_fits_data():
-    x = np.linspace(-5.0, 5.0, 51)
-    expected = np.array([20.0, 0.5, 1.2])
-
+def test_minimizer_can_be_selected():
     assert aare.Gaussian().minimizer == aare.Minimizer.Migrad
+    assert set(aare.Minimizer.__members__) == {"Migrad", "Fumili", "LevenbergMarquardt"}
 
-    model = aare.Gaussian(minimizer=aare.Minimizer.Fumili)
-    assert model.minimizer == aare.Minimizer.Fumili
+    for minimizer in MINIMIZERS:
+        assert aare.Gaussian(minimizer=minimizer).minimizer == minimizer
 
-    y = model(x, expected)
-    result = model.fit(x, y)
-    np.testing.assert_allclose(result["par"], expected, atol=2e-3)
-
-    model.minimizer = aare.Minimizer.Migrad
-    assert model.minimizer == aare.Minimizer.Migrad
+    model = aare.Gaussian()
+    model.minimizer = aare.Minimizer.LevenbergMarquardt
+    assert model.minimizer == aare.Minimizer.LevenbergMarquardt
 
 
-def test_fumili_and_migrad_agree_on_3d_data_with_errors():
+def test_fit_returns_errors_and_chi2(gaussian_data, minimizer):
+    x, y, y_err = gaussian_data
+    model = aare.Gaussian(compute_errors=True, minimizer=minimizer)
+    result = model.fit(x, y, y_err)
+
+    assert set(result) == {"par", "par_err", "chi2"}
+    assert result["par"].shape == (3,)
+    assert result["par_err"].shape == (3,)
+    assert result["chi2"].shape == (1,)
+    np.testing.assert_allclose(result["par"], [120.0, 0.8, 1.3], rtol=1e-4)
+    np.testing.assert_allclose(
+        result["par_err"], [0.361, 0.00451, 0.00451], rtol=2e-2
+    )
+    assert result["chi2"][0] == pytest.approx(0.0, abs=1e-3)
+
+    without_errors = aare.fit(aare.Gaussian(minimizer=minimizer), x, y)
+    assert set(without_errors) == {"par", "chi2"}
+
+
+def test_pol1_weighted_errors_match_analytic_formula(minimizer):
+    x = np.arange(20, dtype=float)
+    y = 2.0 + 0.5 * x
+    y_err = 1.0 + 0.1 * x
+    w = 1.0 / y_err**2
+    S, Sx, Sxx = w.sum(), (w * x).sum(), (w * x * x).sum()
+    delta = S * Sxx - Sx * Sx
+
+    result = aare.Pol1(compute_errors=True, minimizer=minimizer).fit(x, y, y_err)
+
+    np.testing.assert_allclose(result["par"], [2.0, 0.5], rtol=1e-6)
+    np.testing.assert_allclose(
+        result["par_err"],
+        [np.sqrt(Sxx / delta), np.sqrt(S / delta)],
+        rtol=1e-6,
+    )
+
+
+def test_fixed_parameter_reports_zero_error(gaussian_data, minimizer):
+    x, y, y_err = gaussian_data
+    model = aare.Gaussian(compute_errors=True, minimizer=minimizer)
+    model.FixParameter("sigma", 1.5)
+    result = model.fit(x, y, y_err)
+
+    assert result["par"][2] == 1.5
+    assert result["par_err"][2] == 0.0
+    assert result["par"][0] == pytest.approx(111.15, rel=1e-3)
+    assert result["chi2"][0] == pytest.approx(1684.25, rel=1e-3)
+
+    model.ReleaseParameter("sigma")
+    result = model.fit(x, y, y_err)
+    assert result["par"][2] == pytest.approx(1.3, rel=1e-4)
+
+
+def test_active_limit_ends_on_the_limit(gaussian_data, minimizer):
+    x, y, y_err = gaussian_data
+    model = aare.Gaussian(compute_errors=True, minimizer=minimizer)
+    model.SetParLimits("mu", -5.0, 0.5)
+    result = model.fit(x, y, y_err)
+
+    margin = 1e-6 if uses_minuit2(minimizer) else 1e-9
+    assert result["par"][1] == pytest.approx(0.5, abs=margin)
+    assert result["par_err"][1] == 0.0
+    assert result["par"][0] == pytest.approx(116.88, rel=1e-3)
+    assert result["chi2"][0] == pytest.approx(4301.95, rel=1e-3)
+
+    inactive = aare.Gaussian(minimizer=minimizer)
+    inactive.SetParLimits(1, -5.0, 5.0)
+    np.testing.assert_allclose(
+        inactive.fit(x, y)["par"], [120.0, 0.8, 1.3], rtol=1e-4
+    )
+
+
+def test_user_start_value(gaussian_data, minimizer):
+    x, y, _ = gaussian_data
+    model = aare.Gaussian(minimizer=minimizer)
+    model.SetParameter("mu", 0.0)
+    np.testing.assert_allclose(model.fit(x, y)["par"], [120.0, 0.8, 1.3], rtol=1e-4)
+
+
+def test_max_calls_failure_returns_zeros(gaussian_data, minimizer):
+    x, y, y_err = gaussian_data
+    model = aare.Gaussian(max_calls=3, compute_errors=True, minimizer=minimizer)
+    # start far from the minimum so that no minimizer converges in 3 calls
+    model.SetParameter("mu", -3.0)
+    model.SetParameter("sigma", 3.0)
+    result = model.fit(x, y, y_err)
+    assert np.all(result["par"] == 0.0)
+    assert np.all(result["par_err"] == 0.0)
+    assert np.all(result["chi2"] == 0.0)
+
+
+def test_strategy_is_ignored_by_levenberg_marquardt(gaussian_data):
+    x, y, _ = gaussian_data
+    lm = aare.Minimizer.LevenbergMarquardt
+    a = aare.Gaussian(strategy=0, minimizer=lm).fit(x, y)
+    b = aare.Gaussian(strategy=1, minimizer=lm).fit(x, y)
+    np.testing.assert_array_equal(a["par"], b["par"])
+
+
+def test_invalid_parameter_access_raises():
+    model = aare.Gaussian()
+    assert model.par_names == ["A", "mu", "sigma"]
+    assert model.n_par == 3
+    with pytest.raises(RuntimeError):
+        model.SetParameter("nope", 1.0)
+    with pytest.raises(IndexError):
+        model.SetParameter(3, 1.0)
+    with pytest.raises(RuntimeError):
+        model.SetParLimits("mu", 1.0, 1.0)
+
+
+@pytest.mark.parametrize("cls", [aare.RisingScurve, aare.FallingScurve])
+def test_scurve_fit(cls, minimizer):
+    truth = np.array([10.0, 0.1, 50.0, 3.0, 1000.0, 2.0])
+    x = np.linspace(0.0, 100.0, 100)
+    model = cls(max_calls=500, compute_errors=True, minimizer=minimizer)
+    y = model(x, truth)
+    result = model.fit(x, y, np.ones_like(y))
+
+    np.testing.assert_allclose(result["par"], truth, rtol=1e-3)
+    assert np.all(result["par_err"] > 0.0)
+
+
+@pytest.mark.parametrize("with_errors", [False, True])
+def test_fit_3d_matches_fit_1d(with_errors, minimizer):
+    x = np.linspace(-6.0, 6.0, 61)
+    rows, cols = 4, 3
+    y = np.empty((rows, cols, x.size))
+    for r in range(rows):
+        for c in range(cols):
+            y[r, c] = gaussian(x, 80.0 + 10.0 * r, -0.6 + 0.3 * c, 0.9 + 0.1 * r)
+    y_err = np.ones_like(y) if with_errors else None
+
+    model = aare.Gaussian(compute_errors=with_errors, minimizer=minimizer)
+    cube = model.fit(x, y, y_err, n_threads=3)
+
+    assert cube["par"].shape == (rows, cols, 3)
+    assert cube["chi2"].shape == (rows, cols)
+    for r in range(rows):
+        for c in range(cols):
+            single = model.fit(x, y[r, c], None if y_err is None else y_err[r, c])
+            np.testing.assert_allclose(cube["par"][r, c], single["par"], rtol=1e-10)
+            assert cube["chi2"][r, c] == pytest.approx(single["chi2"][0], abs=1e-10)
+            if with_errors:
+                np.testing.assert_allclose(
+                    cube["par_err"][r, c], single["par_err"], rtol=1e-10
+                )
+    np.testing.assert_allclose(cube["par"][3, 2], [110.0, 0.0, 1.2], rtol=1e-4, atol=1e-6)
+
+
+def test_all_minimizers_agree_on_3d_data_with_errors():
     x = np.linspace(-5.0, 5.0, 51)
     expected = np.array([20.0, 0.5, 1.2])
     single = aare.Gaussian()(x, expected)
     y = np.tile(single, (2, 3, 1))
     y_err = np.ones_like(y)
 
-    migrad = aare.Gaussian(compute_errors=True)
-    fumili = aare.Gaussian(compute_errors=True, minimizer=aare.Minimizer.Fumili)
-
-    with_migrad = migrad.fit(x, y, y_err, n_threads=2)
-    with_fumili = fumili.fit(x, y, y_err, n_threads=2)
-
-    assert with_fumili["par"].shape == (2, 3, 3)
-    assert with_fumili["par_err"].shape == (2, 3, 3)
-    for result in (with_migrad, with_fumili):
+    results = {
+        minimizer: aare.Gaussian(compute_errors=True, minimizer=minimizer).fit(
+            x, y, y_err, n_threads=2
+        )
+        for minimizer in MINIMIZERS
+    }
+    reference = results[aare.Minimizer.Migrad]
+    for minimizer, result in results.items():
+        assert result["par"].shape == (2, 3, 3)
+        assert result["par_err"].shape == (2, 3, 3)
         np.testing.assert_allclose(result["par"], np.broadcast_to(expected, (2, 3, 3)), atol=2e-3)
         np.testing.assert_allclose(result["chi2"], 0.0, atol=1e-3)
-    np.testing.assert_allclose(with_fumili["par_err"], with_migrad["par_err"], rtol=2e-2)
+        np.testing.assert_allclose(result["par_err"], reference["par_err"], rtol=2e-2)