0
# Core Minimization
1

2
The Minuit class provides the primary interface for function minimization and parameter estimation using the MINUIT2 C++ library. It supports multiple minimization algorithms, parameter management, and comprehensive error analysis.
3

4
## Capabilities
5

6
### Minuit Class
7

8
Function minimizer and error computer with comprehensive parameter management and algorithm selection.
9

10
```python { .api }
11
class Minuit:
12
    """Function minimizer and error computer."""
13
    
14
    # Class constants for errordef values
15
    LEAST_SQUARES: float = 1.0    # For least-squares cost functions
16
    LIKELIHOOD: float = 0.5       # For log-likelihood cost functions
17
    
18
    def __init__(self, fcn, *args, grad=None, name=None, **kwds):
19
        """
20
        Initialize Minuit minimizer.
21
        
22
        Args:
23
            fcn: Cost function to minimize  
24
            *args: Initial parameter values (positional)
25
            grad: Gradient function (optional, bool, or callable)
26
            name: Parameter names (optional)
27
            **kwds: Initial parameter values (keyword)
28
        """
29
```
30

31
### Parameter Access Properties
32

33
Access and modify parameter values, errors, limits, and fixed status through array-like views.
34

35
```python { .api }
36
# Parameter information (read-only)
37
@property
38
def parameters(self) -> Tuple[str, ...]:
39
    """Get tuple of parameter names."""
40

41
@property  
42
def pos2var(self) -> Tuple[str, ...]:
43
    """Map variable index to name."""
44
    
45
@property
46
def var2pos(self) -> Dict[str, int]:
47
    """Map variable name to index."""
48

49
@property
50
def npar(self) -> int:
51
    """Get number of parameters."""
52

53
@property
54
def nfit(self) -> int:
55
    """Get number of fitted parameters (fixed parameters not counted)."""
56

57
# Parameter values and errors (read/write)
58
@property
59
def values(self):
60
    """Access parameter values via an array-like view."""
61

62
@property  
63
def errors(self):
64
    """Access parameter parabolic errors via an array-like view."""
65
    
66
@property
67
def fixed(self):
68
    """Access whether parameters are fixed via an array-like view."""
69
    
70
@property
71
def limits(self):
72
    """Access parameter limits via a array-like view."""
73
```
74

75
### Minimization Algorithms
76

77
Multiple algorithms for finding function minima with different performance characteristics.
78

79
```python { .api }
80
def migrad(self, ncall=None, iterate=5, use_simplex=True):
81
    """
82
    Run Migrad minimization algorithm.
83
    
84
    Args:
85
        ncall: Maximum function calls (optional)
86
        iterate: Number of iterations if convergence fails
87
        use_simplex: Whether to use Simplex if Migrad fails
88
        
89
    Returns:
90
        Self for method chaining
91
    """
92

93
def simplex(self, ncall=None):
94
    """
95
    Run Simplex minimization algorithm.
96
    
97
    Args:
98
        ncall: Maximum function calls (optional)
99
        
100
    Returns:
101
        Self for method chaining
102
    """
103

104
def scan(self, ncall=None):
105
    """
106
    Brute-force minimization by scanning parameter space.
107
    
108
    Args:
109
        ncall: Maximum function calls (optional)
110
        
111
    Returns:
112
        Self for method chaining
113
    """
114

115
def scipy(self, method=None, ncall=None, hess=None, hessp=None, 
116
          constraints=None, options=None):
117
    """
118
    Minimize with SciPy algorithms.
119
    
120
    Args:
121
        method: SciPy method name or callable
122
        ncall: Maximum function calls (optional)
123
        hess: Hessian function (optional)
124
        hessp: Hessian-vector product (optional)
125
        constraints: Constraint specifications (optional)
126
        options: Algorithm-specific options (optional)
127
        
128
    Returns:
129
        Self for method chaining
130
    """
131
```
132

133
### Error Analysis
134

135
Asymptotic and profile-based uncertainty estimation methods for parameter errors.
136

137
```python { .api }
138
def hesse(self, ncall=None):
139
    """
140
    Run Hesse algorithm to compute asymptotic errors.
141
    
142
    Args:
143
        ncall: Maximum function calls (optional)
144
        
145
    Returns:
146
        Self for method chaining
147
    """
148

149
def minos(self, *parameters, cl=None, ncall=None):
150
    """
151
    Run Minos algorithm to compute confidence intervals.
152
    
153
    Args:
154
        *parameters: Parameter names/indices for Minos analysis
155
        cl: Confidence level (optional, uses errordef if None)
156
        ncall: Maximum function calls (optional)
157
        
158
    Returns:
159
        Self for method chaining
160
    """
161
```
162

163
### Function and Gradient Access
164

165
Access to the cost function and its gradient for advanced usage.
166

167
```python { .api }
168
@property
169
def fcn(self):
170
    """Get cost function (usually a least-squares or likelihood function)."""
171

172
@property
173
def grad(self):
174
    """Get gradient function of the cost function."""
175
```
176

177
### Minimization Settings
178

179
Control minimization strategy, precision, tolerance, and output behavior.
180

181
```python { .api }
182
@property
183
def errordef(self) -> float:
184
    """Access FCN increment above minimum that corresponds to one standard deviation."""
185

186
@errordef.setter  
187
def errordef(self, value: float):
188
    """Set errordef value."""
189

190
@property
191
def precision(self) -> Optional[float]:
192
    """Access estimated precision of the cost function."""
193

194
@precision.setter
195
def precision(self, value: Optional[float]):
196
    """Set precision value."""
197

198
@property
199
def tol(self) -> float:
200
    """Access tolerance for convergence with the EDM criterion."""
201

202
@tol.setter
203
def tol(self, value: float):
204
    """Set tolerance value."""
205

206
@property
207
def strategy(self):
208
    """Access current minimization strategy."""
209

210
@strategy.setter
211
def strategy(self, value):
212
    """Set minimization strategy (0: fast, 1: balanced, 2: accurate)."""
213

214
@property
215
def print_level(self) -> int:
216
    """Access current print level."""
217

218
@print_level.setter
219
def print_level(self, value: int):
220
    """Set print level (0: quiet, 1: normal, 2: verbose)."""
221

222
@property
223
def throw_nan(self) -> bool:
224
    """Access whether to raise runtime error if function evaluates to NaN."""
225

226
@throw_nan.setter
227
def throw_nan(self, value: bool):
228
    """Set NaN handling behavior."""
229
```
230

231
### Fit Results
232

233
Access to minimization results, covariance information, and parameter status.
234

235
```python { .api }
236
@property
237
def fmin(self):
238
    """Get function minimum data object."""
239

240
@property
241
def fval(self) -> Optional[float]:
242
    """Get function value at minimum."""
243

244
@property
245
def valid(self) -> bool:
246
    """Return True if the function minimum is valid."""
247

248
@property
249
def accurate(self) -> bool:
250
    """Return True if the covariance matrix is accurate."""
251

252
@property
253
def covariance(self):
254
    """Return covariance matrix."""
255

256
@property
257
def params(self):
258
    """Get list of current parameter data objects."""
259

260
@property
261
def init_params(self):
262
    """Get list of current parameter data objects set to the initial fit state."""
263

264
@property
265
def merrors(self):
266
    """Return a dict-like with Minos data objects."""
267

268
@property
269
def ndof(self) -> int:
270
    """Get number of degrees of freedom if cost function supports this."""
271

272
@property
273
def nfcn(self) -> int:
274
    """Get total number of function calls."""
275

276
@property
277
def ngrad(self) -> int:
278
    """Get total number of gradient calls."""
279
```
280

281
### Parameter Management
282

283
Methods for fixing parameters and resetting minimization state.
284

285
```python { .api }
286
def fixto(self, key, value):
287
    """
288
    Fix parameter and set it to value.
289
    
290
    Args:
291
        key: Parameter name or index
292
        value: Value to fix parameter to
293
        
294
    Returns:
295
        Self for method chaining
296
    """
297

298
def reset(self):
299
    """
300
    Reset minimization state to initial state.
301
    
302
    Returns:
303
        Self for method chaining
304
    """
305
```
306

307
## Usage Examples
308

309
### Basic Minimization
310

311
```python
312
from iminuit import Minuit
313

314
# Simple quadratic function
315
def cost(x, y):
316
    return (x - 1)**2 + (y - 2)**2
317

318
# Initialize and minimize  
319
m = Minuit(cost, x=0, y=0)
320
m.migrad()
321

322
print(f"Minimum at: x={m.values['x']:.3f}, y={m.values['y']:.3f}")
323
print(f"Function value: {m.fval:.6f}")
324
```
325

326
### Parameter Management
327

328
```python 
329
# Set parameter limits
330
m.limits['x'] = (0, 10)
331
m.limits['y'] = (-5, 5)
332

333
# Fix a parameter
334
m.fixed['x'] = True
335

336
# Or fix to specific value
337
m.fixto('y', 2.5)
338

339
# Check parameter status
340
print(f"Fixed parameters: {[p for p in m.parameters if m.fixed[p]]}")
341
```
342

343
### Error Analysis
344

345
```python
346
# Compute asymptotic errors
347
m.hesse()
348
print(f"Asymptotic errors: {dict(m.errors)}")
349

350
# Compute profile-based errors for specific parameters
351
m.minos('x', 'y')
352
print(f"Minos errors: {dict(m.merrors)}")
353

354
# Access correlation matrix
355
if m.covariance is not None:
356
    corr = m.covariance.correlation()
357
    print(f"Correlation matrix:\n{corr}")
358
```
359

360
### Advanced Settings
361

362
```python
363
# Set minimization strategy (0=fast, 1=default, 2=accurate)
364
m.strategy = 2
365

366
# Set tolerance for convergence
367
m.tol = 0.001
368

369
# Enable verbose output
370
m.print_level = 1
371

372
# Set errordef for chi-square fitting
373
m.errordef = Minuit.LEAST_SQUARES
374
```