{"id":5256,"library":"iminuit","title":"iminuit","description":"iminuit is a Jupyter-friendly Python frontend for the MINUIT2 C++ library, maintained by CERN's ROOT team. It is designed to optimize statistical cost functions for maximum-likelihood and least-squares fits, providing best-fit parameters and error estimates from likelihood profile analysis. The library is currently at version 2.32.0 and undergoes regular updates with detailed changelogs.","status":"active","version":"2.32.0","language":"en","source_language":"en","source_url":"https://github.com/scikit-hep/iminuit","tags":["scientific computing","optimization","fitting","statistics","physics","MINUIT","data analysis"],"install":[{"cmd":"pip install iminuit","lang":"bash","label":"Install iminuit"}],"dependencies":[{"reason":"Core dependency for numerical operations.","package":"numpy","optional":false},{"reason":"Enables partial JIT-compilation of cost functions for performance.","package":"numba","optional":true},{"reason":"Required for visualization of fitted models and interactive fitting with ipywidgets.","package":"matplotlib","optional":true},{"reason":"Enables interactive fitting in Jupyter notebooks (requires matplotlib).","package":"ipywidgets","optional":true},{"reason":"Used for computing Minos intervals for arbitrary confidence levels and alternative minimizers.","package":"scipy","optional":true},{"reason":"Renders names of model parameters in simple LaTeX as Unicode.","package":"unicodeitplus","optional":true}],"imports":[{"note":"The primary interface class is Minuit, typically imported directly.","wrong":"import iminuit; minuit_obj = iminuit.Minuit(...)","symbol":"Minuit","correct":"from iminuit import Minuit"},{"note":"Built-in cost functions reside in the `iminuit.cost` submodule.","wrong":"from iminuit import UnbinnedNLL","symbol":"UnbinnedNLL","correct":"from iminuit.cost import UnbinnedNLL"},{"note":"Another common built-in cost function.","symbol":"LeastSquares","correct":"from iminuit.cost import LeastSquares"}],"quickstart":{"code":"import numpy as np\nfrom iminuit import Minuit\nfrom iminuit.cost import LeastSquares\nfrom matplotlib import pyplot as plt\n\n# 1. Generate some dummy data\nnp.random.seed(1)\nx = np.linspace(0, 10, 50)\ny_true = 2.5 * x + 1.2\ny_err = 1.0 + x * 0.1\ny_data = np.random.normal(y_true, y_err)\n\n# 2. Define the model function\ndef model(x, a, b):\n    return a * x + b\n\n# 3. Create a cost function using iminuit.cost.LeastSquares\n#    errordef=1 for least-squares fits\nleast_squares = LeastSquares(x, y_data, y_err, model)\n\n# 4. Initialize Minuit with the cost function and initial parameter guesses\n#    Parameter names are auto-detected from the model function signature\nm = Minuit(least_squares, a=0, b=0)\n\n# 5. Run the minimization (MIGRAD algorithm)\nm.migrad()\n\n# 6. Run HESSE to compute accurate errors\nm.hesse()\n\n# 7. Print fit results and plot\nprint(m)\nplt.errorbar(x, y_data, y_err, fmt='o', label='Data')\nplt.plot(x, model(x, *m.values), label='Fit')\nplt.xlabel('x')\nplt.ylabel('y')\nplt.legend()\nplt.show()","lang":"python","description":"This quickstart demonstrates a basic least-squares fit. It defines a model, creates a `LeastSquares` cost function, initializes `Minuit` with initial parameter guesses, runs `migrad()` for minimization, and then `hesse()` for error estimation. The results are printed and visualized."},"warnings":[{"fix":"Review the iminuit changelog for detailed migration guides and updated API usage. For legacy code, pin to 'iminuit<2'.","message":"Version 2.x introduced significant breaking interface changes compared to 1.x. Older scripts are not directly compatible.","severity":"breaking","affected_versions":"1.x -> 2.x"},{"fix":"Ensure `errordef` is explicitly set or handled by the chosen `iminuit.cost` class. For `LeastSquares` use `errordef=1`, for `UnbinnedNLL` use `errordef=0.5`.","message":"The `errordef` parameter must be correctly set: `1.0` for least-squares (chi-squared) cost functions and `0.5` for negative log-likelihood functions. Incorrect `errordef` will lead to wrong error estimates.","severity":"gotcha","affected_versions":"All 2.x versions"},{"fix":"Provide reasonable starting values for parameters, ideally close to the expected minimum. Use multiple starting points if the function is complex with many local minima.","message":"The Minuit `migrad` algorithm is a local minimizer. Providing poor initial parameter guesses can lead to convergence to local minima instead of the global minimum, or slow convergence.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Inspect `m.fmin` attributes (e.g., `edm`, `is_valid`) and `m.params` status. If `Accurate` is False for Hesse errors, call `m.hesse()` explicitly. Ensure cost functions are smooth and differentiable.","message":"Always check the fit status (e.g., `m.valid`, `m.fmin.is_valid`) after calling `m.migrad()` or `m.hesse()`. `iminuit` can fail to converge or estimate errors accurately due to numerical issues, discontinuous cost functions, or reaching call limits.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Transform variables to make limits independent, or use an external minimizer (like SciPy) for location finding, then use iminuit for error estimation with box constraints around the found minimum.","message":"Minuit (and thus iminuit) only supports independent box constraints on parameters (e.g., `a > 0`, `b < 5`). Complex, dependent parameter limits (e.g., `x^2 + y^2 < 1`) are not directly supported and require manual transformations or external minimizers.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-13T00:00:00.000Z","next_check":"2026-07-12T00:00:00.000Z"}