### Setup Environment and Import Libraries for Numba Acceleration

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/numba.ipynb

Installs necessary packages like matplotlib, numpy, numba, scipy, and iminuit, and imports modules required for statistical analysis, data generation, fitting, and plotting.

```Python
# !pip install matplotlib numpy numba scipy iminuit
%config InlineBackend.figure_formats = ['svg']
from iminuit import Minuit
import numpy as np
import numba as nb
import math
from scipy.stats import expon, norm
from matplotlib import pyplot as plt
from argparse import Namespace
```

--------------------------------

### Setup and Import Libraries for JAX and iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/automatic_differentiation.ipynb

This code block initializes the environment for using JAX with iminuit. It includes commands to install required packages, configure Matplotlib's inline backend, import essential libraries like JAX, iminuit, numba, and numpy, and sets JAX to use float64 precision. Finally, it prints the versions of JAX and numba to confirm the setup.

```python
# !pip install jax jaxlib matplotlib numpy iminuit numba-stats
%config InlineBackend.figure_formats = ['svg']
import jax
from jax import numpy as jnp  # replacement for normal numpy
from jax.scipy.special import erf  # replacement for scipy.special.erf
from iminuit import Minuit
import numba as nb
import numpy as np  # original numpy still needed, since jax does not cover full API

jax.config.update(
    "jax_enable_x64", True
)  # enable float64 precision, default is float32

print(f"JAX version {jax.__version__}")
print(f"numba version {nb.__version__}")
```

--------------------------------

### Setup Cython Extension and Import Minuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cython.ipynb

This snippet sets up the Jupyter notebook environment by loading the Cython extension and importing the Minuit class from the iminuit library, preparing for the use of Cython-compiled functions.

```python
%load_ext Cython
from iminuit import Minuit
```

--------------------------------

### Explore Multiple Minima by Varying Starting Points

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Demonstrates how different starting values for the minimization process can lead to different local minima for a cost function with multiple minima. It initializes `Minuit` with `x=-0.1` to find one minimum, then changes the starting value to `x=0.1` to find the other, illustrating the importance of initial guesses.

```python
# starting at -0.1 gives the left minimum
m = Minuit(cost_function_with_two_minima, x=-0.1)
m.migrad()
print("starting value -0.1, minimum at", m.values["x"])

# changing the starting value to 0.1 gives the right minimum
m.values["x"] = 0.1  # m.values[0] = 0.1 also works
m.migrad()
print("starting value +0.1, minimum at", m.values["x"])
```

--------------------------------

### Install iminuit with pip

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/install.rst

This command installs the latest stable version of iminuit from PyPI using pip. If a pre-compiled binary wheel is not available for your platform, a C++ compiler will be required for compilation during installation.

```bash
$ pip install iminuit
```

--------------------------------

### Verify iminuit Installation and Version in Python

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/contribute.rst

Python commands to interactively check the installed location of the iminuit library and retrieve its version number. This is useful for confirming a successful development setup.

```python
$ python
>>> import iminuit
>>> iminuit
# install location is printed
>>> iminuit.__version__
# version number is printed
```

--------------------------------

### Run iminuit Tests with Nox

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/contribute.rst

How to execute the iminuit test suite using Nox. Nox automatically sets up a dedicated virtual environment, installs all necessary dependencies, and then runs the project's tests.

```bash
nox -s test
```

--------------------------------

### Importing ROOT Framework

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/roofit.ipynb

This snippet shows how to import the ROOT framework, which is typically installed via a conda virtual environment from conda-forge.

```python
# ROOT is best installed via a conda virtual environment from conda-forge
import ROOT
```

--------------------------------

### Set Minuit Initial Parameters with Keywords

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Shows how to provide initial parameter values to the Minuit constructor using keyword arguments. These starting points are crucial for the local minimizer MIGRAD to converge efficiently, especially for functions with multiple minima.

```python
Minuit(least_squares, α=5, β=5) # pass starting values for α and β
```

--------------------------------

### Minuit Constructor Positional Parameter Initialization

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/changelog.rst

The `Minuit` constructor now allows setting starting values using positional arguments, simplifying initialization for the first few parameters.

```APIDOC
Old: Minuit(my_fcn, x=1, y=2)
New: Minuit(my_fcn, 1, 2)
```

--------------------------------

### Install iminuit from GitHub develop branch using pip

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/install.rst

This command allows users to install the latest unreleased version of iminuit directly from its GitHub develop branch using pip. This method requires a C++ compiler with C++14 support to compile the source code.

```bash
pip install iminuit@git+https://github.com/scikit-hep/iminuit@develop
```

--------------------------------

### Importing Libraries for Interactive Fits

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/interactive.ipynb

Initial setup for interactive fitting, importing necessary modules from iminuit, numba_stats, numpy, and matplotlib for statistical modeling and plotting.

```python
%config InlineBackend.figure_formats = ['svg']
from iminuit import cost
from iminuit import Minuit
from numba_stats import norm, t, bernstein, truncexpon
import numpy as np
from matplotlib import pyplot as plt
```

--------------------------------

### Activate Interactive Fitting in Jupyter

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Call `m.interactive()` on a Minuit instance to enable an interactive fitting interface in Jupyter notebooks. This feature allows users to adjust parameter values with sliders and run fits, aiding in finding good starting values and debugging issues like strong correlations or incorrect model setup. It requires optional extra packages to be installed.

```python
m.interactive()
```

--------------------------------

### Use iminuit.minimize for SciPy-like Interface

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This snippet introduces `iminuit.minimize`, an alternative interface that mimics `scipy.optimize.minimize`. It allows users familiar with `scipy` to use `iminuit` with a similar functional approach, provided `scipy` is installed.

```python
from iminuit import minimize  # has same interface as scipy.optimize.minimize

minimize(least_squares_np, (5, 5))
```

--------------------------------

### Set Minuit Initial Parameters Positionally

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Demonstrates an alternative method for passing initial parameter values to the Minuit constructor using positional arguments. This provides flexibility in how starting points are defined for the minimization process, especially when parameter order is known.

```python
Minuit(least_squares, 5, 5) # another way of passing starting values for α and β
```

--------------------------------

### Handle Minuit Initialization Errors

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Illustrates how Minuit raises a RuntimeError if required parameters are missing or mistyped during initialization. The examples show catching these errors using a try-except block and printing the traceback for debugging purposes.

```python
try:
    Minuit(least_squares)
except RuntimeError:
    import traceback

    traceback.print_exc()
```

```python
try:
    Minuit(least_squares, a=0, b=0)
except RuntimeError:
    import traceback

    traceback.print_exc()
```

--------------------------------

### Sync Git Branches for Release Preparation

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/release.md

This command synchronizes local 'main' and 'develop' branches with their respective remote counterparts on GitHub, ensuring the local repository is up-to-date before starting the release process.

```Shell
for x in main develop; git checkout $x; git pull
```

--------------------------------

### Initialize Minuit Fitter with Starting Parameters

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/numba.ipynb

Defines a factory function `m_init` that creates and configures an iminuit Minuit instance. It sets initial parameter values, assigns names, defines limits for certain parameters, and specifies the error definition for likelihood minimization.

```Python
# ideal starting values for iminuit
start = np.array((truth.n_sig, n_bkg, truth.sig[0], truth.sig[1], truth.bkg[1]))


# iminuit instance factory, will be called a lot in the benchmarks blow
def m_init(fcn):
    m = Minuit(fcn, start, name=("ns", "nb", "mu", "sigma", "lambd"))
    m.limits = ((0, None), (0, None), None, (0, None), (0, None))
    m.errordef = Minuit.LIKELIHOOD
    return m
```

--------------------------------

### Detect Parameter Names with iminuit.describe

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This snippet demonstrates the `iminuit.describe` function, which helps in checking how `iminuit` detects parameter names for a given function or functor. It shows examples for a regular function and a class with a `__call__` method.

```python
from iminuit import describe


def foo(x, y, z):
    pass


assert describe(foo) == ["x", "y", "z"]


class Foo:
    def __call__(self, a, b):
        pass


assert describe(Foo()) == ["a", "b"]
```

--------------------------------

### Configure Compiler Options and Install Target in CMake

Source: https://github.com/scikit-hep/iminuit/blob/develop/CMakeLists.txt

This CMake snippet sets specific compile and link options for the `_core` target based on the detected compiler (MSVC, GNU, or Clang). It enforces C++14 standard for MSVC and enables various strict warnings and error-on-warning flags for GNU and Clang. Finally, it installs the `_core` target to the `iminuit` destination.

```CMake
if(MSVC)
  target_compile_options(_core PRIVATE /std:c++14 /Y-)
elseif(CMAKE_CXX_COMPILER_ID STREQUAL "GNU")
  # lots of warnings from gcc, including odr violations
  target_compile_options(
    _core
    PRIVATE -Wall
            -Wextra
            -Werror
            -Werror=odr
            -Werror=lto-type-mismatch
            -Werror=strict-aliasing
            -pedantic
            -fstrict-aliasing)
  target_link_options(_core PRIVATE -Werror -Wodr -Wlto-type-mismatch)
else()
  # lots of warnings from clang
  target_compile_options(_core PRIVATE -Wall -Wextra -pedantic -Werror
                                       -Werror=odr -fstrict-aliasing)
  target_link_options(_core PRIVATE -Werror -Wodr)
endif()

install(TARGETS _core DESTINATION iminuit)
```

--------------------------------

### Displaying Covariance Matrix (repr) with iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Illustrates how to get a more detailed representation of the covariance matrix computed by Hesse using the `repr()` function on the `m.covariance` attribute of a Minuit object.

```python
print(
    repr(m.covariance)
)  # covariance matrix computed by Hesse (using repr(m.covariance))
```

--------------------------------

### Install iminuit with conda

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/install.rst

This command installs iminuit using the conda package manager from the conda-forge channel. Conda packages are semi-automatically maintained and typically support the latest Python versions across various platforms.

```bash
$ conda install -c conda-forge iminuit
```

--------------------------------

### Pure Python Gaussian Fitting with iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/roofit.ipynb

This example demonstrates how to perform an equivalent Gaussian fit entirely in pure Python, without relying on RooFit. It uses `scipy.stats.truncnorm` for the model and `iminuit.cost.UnbinnedNLL` for the cost function, generating data with NumPy.

```python
from scipy.stats import truncnorm
from iminuit.cost import UnbinnedNLL
import numpy as np

xrange = (-10.0, 10.0)

rng = np.random.default_rng(1)
x = rng.normal(1, 3, size=10000)
x = x[(xrange[0] < x) & (x < xrange[1])]


def model(x, mu, sigma):
    zrange = np.subtract(xrange, mu) / sigma
    return truncnorm.pdf(x, *zrange, mu, sigma)


# better use numba_stats.truncnorm, which is simpler to use and faster
#
# from numba_stats import truncnorm
#
# def model(x, mu, sigma):
#     return truncnorm.pdf(x, *xrange, mu, sigma)

nll = UnbinnedNLL(x, model)
m = Minuit(nll, 1, 3)
m.migrad()
```

--------------------------------

### Set Two-Sided and Lower Limits for Parameters

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Demonstrates how to apply two-sided and lower limits to multiple parameters simultaneously using a sequence. This example sets the first parameter's lower limit to 0 and the second parameter's range from 0 to 10, then inspects the parameters.

```python
m.limits = [(0, None), (0, 10)]
m.params
```

--------------------------------

### Initialize CMake Project and Check Build Environment

Source: https://github.com/scikit-hep/iminuit/blob/develop/CMakeLists.txt

Sets the minimum required CMake version and defines the project name and languages. It includes a warning if the build is not initiated through Python (e.g., via `pip install`), indicating that certain variables might not be correctly set for a typical Python-wrapped C++ project.

```CMake
cmake_minimum_required(VERSION 3.15...3.26)

project(iminuit LANGUAGES CXX)

if(NOT DEFINED SKBUILD)
  message(
    WARNING
      "You should call this through Python so that all variables are set; pip install -v ."
  )
endif()
```

--------------------------------

### Fitting Two Parametric Components Using iminuit.cost.Template

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/template_model_mix.ipynb

This example demonstrates using `iminuit.cost.Template` to fit two entirely parametric components (Gaussian signal and exponential background). While not the recommended approach for this scenario, it shows the flexibility of the `Template` class in handling multiple parametric models.

```Python
# signal model: scaled cdf of a normal distribution
def signal(xe, n, mu, sigma):
    return n * norm.cdf(xe, mu, sigma)


# background model: scaled cdf a an exponential distribution
def background(xe, n, mu):
    return n * truncexpon.cdf(xe, xe[0], xe[-1], 0, mu)


# fit
c = Template(n, xe, (signal, background))
m = Minuit(c, x0_n=500, x0_mu=0.5, x0_sigma=0.05, x1_n=100, x1_mu=1)
m.limits["x0_n", "x1_n", "x0_sigma", "x1_mu"] = (0, None)
m.limits["x0_mu"] = (0, 1)
m.migrad()
```

--------------------------------

### Get Detailed Representation of Minuit Parameters

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Explains how to get a detailed, programmatic representation of individual Param objects returned by Minuit.params. Iterating through the parameters and calling repr() on each provides access to all attributes of the parameter data object for in-depth inspection.

```python
for p in m.params:
    print(repr(p), "\n")
```

--------------------------------

### Generating Sample Data for Binned Fit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/gof.ipynb

This code defines a `generate` function to create synthetic data samples, simulating a mixture of normal and exponential distributions. It then generates an example dataset with 1000 entries and visualizes its distribution using a histogram, preparing the data for the binned NLL fitting process.

```python
def generate(n, seed):
    rng = np.random.default_rng(seed)
    s = rng.normal(1, 0.1, size=rng.poisson(n))
    b = rng.exponential(size=rng.poisson(n))
    x = np.append(s, b)
    return x[(x > 0) & (x < 2)]

x = generate(1000, 1)
plt.hist(x, bins=20, range=(0, 2));
```

--------------------------------

### Initialize Minuit with Explicit Parameter Names

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cython.ipynb

This example shows how to explicitly provide parameter names to Minuit using the `name` keyword argument. This is useful if Cython does not automatically generate a proper function signature or if you wish to override the detected names, ensuring Minuit correctly identifies the parameters during minimization.

```python
m = Minuit(cython_func, 1, 1, 1, name=("a", "b", "c"))
m.migrad()
```

--------------------------------

### Execute Extended Unbinned NLL Fit with Minuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/scipy_and_constraints.ipynb

This snippet demonstrates setting up and running an extended unbinned negative log-likelihood fit using `iminuit`. It initializes the `Minuit` object with the cost function and initial parameters, sets limits for background parameters, fixes signal mean and sigma, and then performs the minimization using `migrad`. The example highlights a scenario where the signal amplitude might become negative.

```python
rng = np.random.default_rng(2)
x = rng.uniform(0, 1, size=35)

cost = ExtendedUnbinnedNLL(x, model)
n = len(x)
m = Minuit(cost, b0=n, b1=n, b2=n, sig=0, mu=0.5, sigma=0.05)
m.print_level = 0
m.limits["b0", "b1", "b2"] = (0, None)
m.fixed["mu", "sigma"] = True
m.migrad()
```

--------------------------------

### Compare Execution Times of Minuit Configurations

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/automatic_differentiation.ipynb

This code block uses `timeit` to measure and compare the execution times of the different `Minuit` minimization setups (with and without JIT, with and without gradient). It stores the results in a dictionary for later visualization.

```python
from timeit import timeit

times = {
    "no JIT, no grad": "m1",
    "no JIT, grad": "m2",
    "jax JIT, no grad": "m3",
    "jax JIT, grad": "m4",
    "numba JIT, no grad": "m5"
}
for k, v in times.items():
    t = timeit(
        f"{v}.values = start_values; {v}.migrad()",
        f"from __main__ import {v}, start_values",
        number=1,
    )
    times[k] = t
```

--------------------------------

### Helper Function to Configure and Run Minuit Minimization

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/automatic_differentiation.ipynb

This function sets up and runs the `Minuit` minimizer with predefined start values and limits. It takes a cost function and an optional gradient function, configures `errordef` and `strategy`, and then calls `migrad`.

```python
start_values = (1.5 * np.sum(n), 1.0, 2.0)
limits = ((0, None), (None, None), (0, None))


def make_and_run_minuit(fcn, grad=None):
    m = Minuit(fcn, start_values, grad=grad, name=("amp", "mu", "sigma"))
    m.errordef = Minuit.LIKELIHOOD
    m.limits = limits
    m.strategy = 0  # do not explicitly compute hessian after minimisation
    m.migrad()
    return m
```

--------------------------------

### Define a Cost Function with Multiple Minima

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Defines a sample cost function `x^4 - x^2 + 1` that exhibits two local minima. This code also plots the function to visually demonstrate its shape and the presence of multiple minima, which is relevant for understanding the impact of starting points.

```python
def cost_function_with_two_minima(x):
    return x**4 - x**2 + 1


x = np.linspace(-1.5, 1.5)
plt.plot(x, cost_function_with_two_minima(x));
```

--------------------------------

### Initialize Minuit with Keyword Parameters

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Demonstrates how to create a Minuit instance by passing the function to be minimized and initial parameter values using keyword arguments. Minuit automatically introspects parameter names from the function for convenient initialization.

```python
m = Minuit(least_squares, α=0, β=0)
```

--------------------------------

### Build iminuit Documentation with Nox

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/contribute.rst

Instructions to build the iminuit project's documentation using Nox. This command compiles the documentation, and the resulting HTML files can then be opened in a web browser for review.

```bash
nox -s doc
<your-web-browser> build/html/index.html
```

--------------------------------

### Initialize iminuit Environment and Import Core Modules

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This snippet sets up the basic environment for using `iminuit` in a Jupyter notebook, including importing `matplotlib`, `numpy`, and the essential `Minuit` and `LeastSquares` classes from `iminuit`. It also prints the `iminuit` version for verification.

```python
# basic setup of the notebook
%config InlineBackend.figure_formats = ['svg']
from matplotlib import pyplot as plt
import numpy as np

# everything in iminuit is done through the Minuit object, so we import it
from iminuit import Minuit

# we also need a cost function to fit and import the LeastSquares function
from iminuit.cost import LeastSquares

# display iminuit version
import iminuit

print("iminuit version:", iminuit.__version__)
```

--------------------------------

### Removed Minuit.from_array_func Method

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/changelog.rst

The static method `Minuit.from_array_func` has been removed. Users should now initialize `Minuit` directly with a NumPy function and a starting array.

```APIDOC
Old: Minuit.from_array_func(some_numpy_function, starting_array)
New: Minuit(some_numpy_function, starting_array)
```

--------------------------------

### Iterate Over Parameter Names and Values (Python)

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Shows how to iterate through both the parameter names and their corresponding optimized values simultaneously. This is useful for displaying all fit results in a formatted way.

```python
for key, value in zip(m.parameters, m.values):
    print(f"{key} = {value}")
```

--------------------------------

### Removed Features and Attributes in iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/changelog.rst

This section details features and attributes that have been removed from the iminuit library, along with their suggested replacements where applicable, to guide users in updating their code.

```APIDOC
Minuit.np_merrors: Removed. Use Minuit.merrors or Minuit.params instead.
Minuit.use_array_call: Removed. Minuit.fcn and Minuit.grad always require parameter values in sequence form (e.g., minuit.fcn((1, 2))).
util.FMin: Dict-like interface removed (methods like keys(), items() are gone).
util.MError: Dict-like interface removed.
util.Param: Dict-like interface removed.
ngrad_total: Removed. Replaced by ngrad.
nfcn_total: Removed. Replaced by nfcn.
up: Removed. Replaced by errordef.
util.InitialParamWarning: Removed.
util.MigradResult: Removed.
util.arguments_from_inspect: Removed from public interface.
```

--------------------------------

### Importing Libraries for Template and Parametric Model Fitting

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/template_model_mix.ipynb

This snippet imports necessary libraries for statistical modeling and plotting. It includes `Minuit` for minimization, `Template` and `ExtendedBinnedNLL` for cost functions, `numba_stats` for statistical distributions, `numpy` for numerical operations, and `matplotlib` for visualization.

```Python
%config InlineBackend.figure_formats = ['svg']
from iminuit import Minuit
from iminuit.cost import Template, ExtendedBinnedNLL
from numba_stats import norm, truncexpon
import numpy as np
from matplotlib import pyplot as plt
```

--------------------------------

### Interactive BinnedNLL Fit with Masked Data

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/interactive.ipynb

Extends the `BinnedNLL` example by applying a mask to exclude certain data points from the fit. This demonstrates how to focus the fit on specific regions of the data for interactive analysis.

```python
c = cost.BinnedNLL(n, xe, model)

cx = 0.5 * (xe[1:] + xe[:-1])
c.mask = np.abs(cx - 0.5) > 0.3

m = Minuit(c, *truth)
m.limits["sigma", "slope"] = (0, None)
m.limits["mu", "f", "nuinv"] = (0, 1)

m.interactive()
```

--------------------------------

### Interactive Template Fit with Masked Data

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/interactive.ipynb

Extends the `Template` example by applying a mask to exclude certain data points from the fit. This demonstrates how to focus the template fit on specific regions of the data for interactive analysis.

```python
c = cost.Template(n, xe, (b, s))
cx = 0.5 * (xe[1:] + xe[:-1])
c.mask = np.abs(cx - 0.5) > 0.2

m = Minuit(c, 1000, 100, name=("b", "s"))
m.limits = (0, None)

m.interactive()
```

--------------------------------

### Perform SIMPLEX Minimization with iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Demonstrates how to apply the gradient-free SIMPLEX minimization method using iminuit. This method is robust but slower, often used as a preliminary step before more precise methods like MIGRAD. It's recommended to follow SIMPLEX with MIGRAD or adjust tolerance for better accuracy.

```python
Minuit(cost_function_with_two_minima, x=10).simplex()
```

--------------------------------

### Retrieving and Plotting Raw 1D Likelihood Scan Data

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Demonstrates how to get the raw x and y values of a 1D likelihood scan using `Minuit.profile()`. The minimum value is not subtracted from the y-values in this raw output, allowing for custom plotting.

```python
# or draw it yourself, the minimum value is not subtracted here
x, y = m.profile("α")
plt.plot(x, y);
```

--------------------------------

### Accessing Fitted Parameters List

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Retrieves a tuple-like container of `Param` objects, providing direct access to all fitted parameters and their associated information such as name, value, and error. This is the primary way to get the fit results for individual parameters.

```python
m.params
```

--------------------------------

### Converting RooDataSet to NumPy for iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/roofit.ipynb

To achieve identical fitting results as the RooFit example, this snippet shows how to convert the `RooDataSet` object into a NumPy array using the `to_numpy` method. The converted data is then used with `iminuit.cost.UnbinnedNLL` for fitting.

```python
x = data.to_numpy()["x"]

nll = UnbinnedNLL(x, model)
m = Minuit(nll, 1, 3)
m.migrad()
```

--------------------------------

### Run Minimization with Minuit.migrad()

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This snippet demonstrates the basic usage of `Minuit.migrad()`, which executes the MIGRAD algorithm to find the function minimum. The method returns the Minuit instance, allowing for method chaining and pretty printing of the minimization state.

```python
m = Minuit(least_squares, α=5, β=5)
m.migrad()
```

--------------------------------

### Accessing the Parameter Covariance Matrix (Python)

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This example shows how to retrieve the covariance matrix of the fitted parameters using `m.covariance`. The returned object is a subclass of `numpy.ndarray`, allowing standard NumPy operations while also providing Minuit-specific features.

```python
m.covariance
```

--------------------------------

### Execute Least-Squares Minimization and Error Calculation with iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This snippet demonstrates the core `iminuit` workflow. It initializes a `LeastSquares` cost function with the generated data and the `line` model, creates a `Minuit` object with initial parameter guesses, and then runs `migrad()` to find the minimum and `hesse()` to compute parameter uncertainties.

```python
least_squares = LeastSquares(data_x, data_y, data_yerr, line)

m = Minuit(least_squares, α=0, β=0)  # starting values for α and β

m.migrad()  # finds minimum of least_squares function
m.hesse()  # accurately computes uncertainties
```

--------------------------------

### BibTeX Citation for iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/README.rst

A generic BibTeX entry to cite the iminuit project, which automatically points to the latest release on Zenodo.

```BibTeX
@article{iminuit,
  author={Hans Dembinski and Piti Ongmongkolkul et al.},
  title={scikit-hep/iminuit},
  DOI={10.5281/zenodo.3949207},
  publisher={Zenodo},
  year={2020},
  month={Dec},
  url={https://doi.org/10.5281/zenodo.3949207}
}
```

--------------------------------

### Initializing Minuit, Performing Fit, and Visualizing Results

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/simultaneous_fits.ipynb

Initializes the `Minuit` optimizer with the combined likelihood function and provides initial guesses for the parameters. It then plots the raw data and the initial model (dashed lines) for both datasets. After performing the minimization using `m.migrad()`, it plots the final fitted model (solid lines) on top of the data, demonstrating the outcome of the shared parameter fit.

```python
m = Minuit(lh, μ_1=1, μ_2=2, σ=1)

fig, ax = plt.subplots(1, 2, figsize=(9, 4))

hists = [np.histogram(lhi.data, bins=50) for lhi in lh]

# draw data and model with initial parameters
for lhi, (w, xe), axi in zip(lh, hists, ax):
    cx = (xe[1:] + xe[:-1]) / 2
    axi.errorbar(cx, w, np.sqrt(w), fmt="ok", capsize=0, zorder=0)
    plot(lhi, xe, m, axi, ls="--")

m.migrad()

# draw model with fitted parameters
for lhi, (w, xe), axi in zip(lh, hists, ax):
    plot(lhi, xe, m, axi)
    axi.legend()
```

--------------------------------

### Perform Interactive Binned NLL Fit with iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/_static/interactive_demo.ipynb

This Python snippet demonstrates how to set up and perform an interactive binned negative log-likelihood (NLL) fit. It defines a model based on a sum of two normal cumulative distribution functions, generates synthetic binned data, and then uses `iminuit.cost.ExtendedBinnedNLL` to create a cost function. Finally, it initializes `Minuit` with this cost and calls `m.interactive()` to launch the interactive fitting interface.

```python
import numpy as np
from scipy.stats import norm
from iminuit import Minuit, cost

truth = 100.0, 200.0, 0.3, 0.1, 0.7, 0.2

def scaled_cdf(xe, n1, n2, mu1, sigma1, mu2, sigma2):
    return n1 * norm.cdf(xe, mu1, sigma1) + n2 * norm.cdf(xe, mu2, sigma2)


xe = np.linspace(0, 1)
m = np.diff(scaled_cdf(xe, *truth))
n = np.random.default_rng(1).poisson(m)  # generate random histogram

c = cost.ExtendedBinnedNLL(n, xe, scaled_cdf)
m = Minuit(c, *truth)

m.interactive()
```

--------------------------------

### Apply Masking to LeastSquares Cost Function

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/interactive.ipynb

This example shows how to apply a mask to the LeastSquares cost function. By setting the 'mask' attribute, specific data points can be excluded from the fitting process, allowing for more robust analysis by ignoring outliers or irrelevant regions.

```python
c = cost.LeastSquares(x, y, ye, model)
c.mask = (x > 0.6) | (x < 0.2)

m = Minuit(c, *truth)
m.interactive()
```

--------------------------------

### Initialize Minuit with Sequence Parameters

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Shows how to initialize Minuit when the model function accepts parameters as a NumPy array. Initial values must be passed as a single sequence (e.g., tuple, list, or NumPy array), and iminuit automatically names parameters 'x0' to 'xN' based on the sequence length.

```python
least_squares_np = LeastSquares(data_x, data_y, data_yerr, line_np)

Minuit(least_squares_np, (5, 5)) # pass starting values as a sequence
```

--------------------------------

### Handle Variable Arguments with iminuit.describe

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This snippet illustrates that `iminuit.describe` cannot detect parameter names for functions accepting a variable number of arguments (`*args`). In such cases, `describe` returns an empty list, indicating the need for manual parameter naming.

```python
def func_varargs(*args):  # function with variable number of arguments
    return np.sum((np.array(args) - 1) ** 2)


assert describe(func_varargs) == []
```

--------------------------------

### Fit Signal Parameters After Mask Removal (Python)

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cost_functions.ipynb

This snippet continues the staged fitting process by removing the temporary mask, releasing all parameters, and then fixing the background amplitude. It adjusts the signal amplitude starting value and re-runs `migrad` to fit only the signal parameters.

```python
c.mask = None  # remove mask
m.fixed = False  # release all parameters
m.fixed["b"] = True  # fix background amplitude
m.values["s"] = 100  # do not start at the limit
m.migrad()
```

--------------------------------

### Initialize Minuit with Cython Function

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cython.ipynb

This Python snippet demonstrates how to initialize the Minuit optimizer with the previously defined and compiled Cython function. It passes initial parameter values (1, 1, 1) and then calls `migrad()` to perform the minimization, treating the Cython function as a native Python callable.

```python
m = Minuit(cython_func, 1, 1, 1)
m.migrad()
```

--------------------------------

### Minuit.profile and Minuit.draw_profile Method Changes

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/changelog.rst

The `profile` and `draw_profile` methods have updated the keyword for binning and their arguments are now keyword-only.

```APIDOC
Methods: Minuit.profile, Minuit.draw_profile
  - Keyword Change:
    Old: bins
    New: size
  - Argument Type: Keyword arguments are now keyword-only.
```

--------------------------------

### Multivariate Unbinned Fit with Log-PDF and Gradient in iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cost_functions.ipynb

This example extends the multivariate unbinned fit by incorporating an explicit gradient for the log-probability density function. It defines a gradient function for the multivariate log-PDF and passes it to `cost.UnbinnedNLL` along with `log=True`, enabling `Minuit` to utilize the gradient during minimization.

```python
def grad(xy, *par):
    return jacobi(lambda p: logpdf(xy, *p), par)[0].T

c = cost.UnbinnedNLL((xdata, ydata), logpdf, log=True, grad=grad)
m = Minuit(c, mu=1, sigma=2, tau=2)
m.limits["sigma", "tau"] = (0, None)
m.migrad()
```

--------------------------------

### Fitting Gaussian Directly with RooFit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/roofit.ipynb

This snippet shows the direct method of fitting the Gaussian PDF to the generated data using RooFit's built-in `fitTo` method, providing a comparison point for the iminuit fit.

```python
gauss.fitTo(data);
```

--------------------------------

### Understanding Minuit.hesse, Minuit.minos, and Minuit.errordef in iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/faq.rst

Explains the purpose and interpretation of key Minuit methods and attributes like `hesse` (Hessian matrix calculation), `minos` (MINOS error calculation), and `errordef` (definition of the error for likelihood functions), referencing the MINUIT2 user's guide for detailed explanations.

```APIDOC
Minuit.hesse:
  Calculates the Hessian matrix, which provides the second derivatives of the likelihood function at the minimum. Used to determine parameter uncertainties.
Minuit.minos:
  Computes asymmetric errors for parameters, especially useful when the likelihood function is not parabolic or parameters are near boundaries.
Minuit.errordef:
  Defines the change in the negative log-likelihood function that corresponds to a one-sigma error. For a chi-squared fit, this is typically 1.0; for a negative log-likelihood, it's 0.5.
```

--------------------------------

### Illustrate Initial LeastSquares Usage and Parameter Introspection Failure

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/generic_least_squares.ipynb

This example defines a simple line model and generates synthetic data. It then attempts to use the `LeastSquares` class with `Minuit`, demonstrating a `RuntimeError` because iminuit cannot automatically determine the model's parameters from the generic `__call__` signature.

```python
def line(x, a: float, b: Annotated[float, 0:]):
    return a + b * x


rng = np.random.default_rng(1)
x_data = np.arange(1, 6, dtype=float)
y_err = np.ones_like(x_data)
y_data = line(x_data, 1, 2) + rng.normal(0, y_err)

lsq = LeastSquares(line, x_data, y_data, y_err)

# this fails
try:
    m = Minuit(lsq, a=0, b=0)
    m.errordef = Minuit.LEAST_SQUARES
except RuntimeError:
    import traceback

    traceback.print_exc()
```

--------------------------------

### Plotting Contours with Experimental Algorithm

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Illustrates the use of the `experimental=True` parameter in `Minuit.mncontour()` to generate a smoother contour, albeit potentially taking more time to compute.

```python
# with experimental algorithm
pts = m.mncontour("α", "β", cl=0.68, size=50, experimental=True)
x4, y4 = np.transpose(pts)
plt.plot(x4, y4, "-", label="size=50 experimental");
```

--------------------------------

### Retrieving and Plotting 1D Likelihood Profile Data

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Shows how to obtain the raw data points for a 1D likelihood profile using `Minuit.mnprofile()` and then plot them manually using Matplotlib.

```python
# or use this to plot the result of the scan yourself
a, fa, ok = m.mnprofile("α")
plt.plot(a, fa);
```

--------------------------------

### Multivariate Extended Unbinned Fit with Log-Density in iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cost_functions.ipynb

This example demonstrates performing an extended unbinned maximum-likelihood fit for multivariate data using a log-density function. The `logdensity` function returns the total integral and the log of the density. `cost.ExtendedUnbinnedNLL` is configured with `log=True` to handle the log-likelihood, and `Minuit` performs the minimization.

```python
def logdensity(xy, n, mu, sigma, tau):
    x, y = xy
    return n, np.log(n) + norm.logpdf(x, mu, sigma) + expon.logpdf(y, 0, tau)

c = cost.ExtendedUnbinnedNLL((xdata, ydata), logdensity, log=True)
m = Minuit(c, n=1, mu=1, sigma=2, tau=2)
m.limits["n", "sigma", "tau"] = (0, None)
m.migrad()
```

--------------------------------

### Set Initial Step Sizes with iminuit.Minuit.errors Property

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

This snippet demonstrates how to set initial step sizes for parameters in `iminuit` using the `Minuit.errors` property. It shows assigning a sequence of values to `m.errors` to set different step sizes for multiple parameters.

```python
m = Minuit(least_squares, α=5, β=5)
m.errors = (0.1, 0.2)  # assigning sequences works
m.params
```

--------------------------------

### Unbinned Maximum-Likelihood Fit with Explicit Gradient in iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cost_functions.ipynb

This example shows how to provide an explicit gradient to the `UnbinnedNLL` cost function in `iminuit` for potentially improved minimization performance. It defines a gradient function using `jacobi` (for demonstration) and then passes it to the cost function, followed by `Minuit` minimization with parameter limits.

```python
def grad(x, *par):
    return jacobi(lambda par: pdf(x, *par), par)[0].T

c = cost.UnbinnedNLL(xmix, pdf, grad=grad)

m = Minuit(c, z=0.4, mu=1, sigma=0.2, tau=1)
m.limits["z"] = (0, 1)
m.limits["mu"] = (0, 2)
m.limits["sigma", "tau"] = (0, None)
m.migrad()
```

--------------------------------

### Importing Libraries and Configuring Matplotlib

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/correlated_data.ipynb

Initializes the environment by importing necessary libraries like `iminuit`, `numpy`, and `matplotlib.pyplot`, and configures Matplotlib for SVG output.

```python
%config InlineBackend.figure_formats = ['svg']
from iminuit import Minuit
import numpy as np
import matplotlib.pyplot as plt
```

--------------------------------

### Perform a Binned Fit using an Approximate CDF in iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cost_functions.ipynb

This example shows how to perform a binned fit when the exact CDF is computationally expensive. It approximates the CDF by summing 'bin-width times PDF evaluated at center', which can introduce a bias. The `pdf` function is defined, followed by the `approximate_cdf` function, which is then passed to `cost.BinnedNLL`.

```python
def pdf(x, z, mu, sigma, tau):
    return z * truncnorm.pdf(x, *xr, mu, sigma) + (1 - z) * truncexpon.pdf(
        x, *xr, 0, tau
    )

def approximate_cdf(xe, z, mu, sigma, tau):
    dx = np.diff(xe)
    cx = xe[:-1] + 0.5 * dx
    p = pdf(cx, z, mu, sigma, tau)
    return np.append([0], np.cumsum(p * dx))

c = cost.BinnedNLL(n, xe, approximate_cdf)
m = Minuit(c, z=0.4, mu=0, sigma=0.2, tau=2)
m.limits["z"] = (0, 1)
m.limits["sigma", "tau"] = (0.01, None)
m.migrad()
```

--------------------------------

### Release All Parameters Simultaneously

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Illustrates how to release all fixed parameters at once by setting the `fixed` property to `False`. This allows subsequent `migrad` calls to optimize all parameters without any constraints.

```python
m.fixed = False
m.migrad()
```

--------------------------------

### Accessing Covariance Matrix Elements by Parameter Name (Python)

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Leveraging the enhanced capabilities of the covariance matrix object, this example shows how to access specific elements using parameter names, such as `m.covariance["α", "β"]`. This provides a more intuitive way to retrieve individual covariance values.

```python
m.covariance["α", "β"]
```

--------------------------------

### Importing Libraries for Binned NLL Analysis

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/gof.ipynb

This snippet imports all necessary Python libraries for performing binned negative log-likelihood (NLL) fits and goodness-of-fit analysis. It includes `iminuit` for minimization, `numpy` for numerical operations, `numba_stats` for statistical distributions, `matplotlib` for plotting, `joblib` for parallel processing, and `scipy.stats` for chi-squared distribution functions.

```python
%config InlineBackend.figure_formats = ['svg']
from iminuit import Minuit
from iminuit.cost import BinnedNLL, ExtendedBinnedNLL
import numpy as np
from numba_stats import norm, expon
import matplotlib.pyplot as plt
import joblib
from scipy.stats import chi2
```

--------------------------------

### Slice Parameter Values (Python)

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Demonstrates using Python's slicing syntax on the 'm.values' property to access a subset of the parameter values. This allows for convenient retrieval of multiple parameters based on their position.

```python
print(m.values[:1])
```

--------------------------------

### Clone iminuit Repository Recursively

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/contribute.rst

Instructions to clone the iminuit project repository from GitHub, including the `--recursive` flag to ensure all submodules are also cloned, and then navigating into the project directory.

```bash
git clone --recursive https://github.com/scikit-hep/iminuit.git
cd iminuit
```

--------------------------------

### Perform Unbinned Maximum Likelihood Fit in Python with iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/README.rst

This example demonstrates how to perform an unbinned maximum likelihood fit using `iminuit`. It defines a simple Gaussian PDF, creates an `UnbinnedNLL` cost function from sample data, and then uses `Minuit` to find the optimal parameters (`migrad`) and compute their uncertainties (`hesse`). The `sigma` parameter is constrained to be positive.

```python
import numpy as np
from iminuit import Minuit
from iminuit.cost import UnbinnedNLL
from scipy.stats import norm

x = norm.rvs(size=1000, random_state=1)

def pdf(x, mu, sigma):
    return norm.pdf(x, mu, sigma)

# Negative unbinned log-likelihood, you can write your own
cost = UnbinnedNLL(x, pdf)

m = Minuit(cost, mu=0, sigma=1)
m.limits["sigma"] = (0, np.inf)
m.migrad()  # find minimum
m.hesse()   # compute uncertainties
```

--------------------------------

### Execute MIGRAD Minimization Directly with iminuit

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/basic.ipynb

Shows how to perform direct minimization using the MIGRAD method in iminuit. This is a common and generally efficient minimization approach, often used as a standalone method or after a preliminary SIMPLEX run.

```python
Minuit(cost_function_with_two_minima, x=10).migrad()
```

--------------------------------

### Importing Core Libraries for iminuit and Data Analysis

Source: https://github.com/scikit-hep/iminuit/blob/develop/doc/notebooks/cost_functions.ipynb

This Python snippet imports essential libraries required for performing fits with `iminuit`. It includes `iminuit` for optimization, `numba_stats` for accelerated statistical functions, `numpy` for numerical operations, `matplotlib.pyplot` for data visualization, and `jacobi` for precise numerical derivatives, setting up the environment for subsequent data generation and fitting tasks.

```python
%config InlineBackend.figure_formats = ['svg']
from iminuit import cost, Minuit

# faster than scipy.stats functions
from numba_stats import truncnorm, truncexpon, norm, expon
import numpy as np
from matplotlib import pyplot as plt

# accurate numerical derivatives
from jacobi import jacobi
```