fitle 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
fitle/fitting.py ADDED
@@ -0,0 +1,402 @@
1
+ """fitting.py
2
+ ============
3
+ Model fitting using iminuit optimization.
4
+
5
+ Provides the ``fit()`` function for optimizing Model parameters and
6
+ the ``FitResult`` class for storing and visualizing fit results.
7
+
8
+ The fitting workflow:
9
+
10
+ 1. Build a model with ``Param`` objects
11
+ 2. Combine with a cost function: ``model | Cost.NLL(data)``
12
+ 3. Call ``fit(cost_model)`` to optimize
13
+ 4. Access results via the returned ``FitResult``
14
+
15
+ Example::
16
+
17
+ from fitle import Param, fit, Cost
18
+ from fitle.pdfs import gaussian
19
+
20
+ model = gaussian(Param("mu"), Param.positive("sigma"))
21
+ cost = model | Cost.NLL(data)
22
+ result = fit(cost)
23
+ print(result) # Shows fitted parameters with errors
24
+ """
25
+ from __future__ import annotations
26
+
27
+ import numpy as np
28
+ from numpy.typing import NDArray
29
+ import iminuit
30
+ import warnings
31
+ from .model import Model, const
32
+ from .param import Param, _Param
33
+ import matplotlib.pyplot as plt
34
+
35
+
36
+ class _FittingContext:
37
+ """Optimized context for repeated model evaluation during fitting.
38
+
39
+ Pre-computes and caches everything needed for fast evaluation,
40
+ eliminating per-iteration overhead from hash lookups, property
41
+ walks, and array allocations.
42
+ """
43
+
44
+ def __init__(self, model: Model, use_numba: bool = True):
45
+ """Initialize the fitting context.
46
+
47
+ Parameters
48
+ ----------
49
+ model : Model
50
+ The model to prepare for fitting. Must be compiled if use_numba=True.
51
+ use_numba : bool
52
+ Whether to use the compiled Numba function.
53
+ """
54
+ self.params = model.params # Cache once (now also cached in Model)
55
+ self.n_params = len(self.params)
56
+ self.theta = np.empty(self.n_params, dtype=np.float64) # Reusable buffer
57
+ self.use_numba = use_numba
58
+ self._model = model
59
+
60
+ # Get x data from model.memory if present (for cost models that preserve INPUT)
61
+ self._x_data = model.memory.get('_eval_x', None)
62
+
63
+ if use_numba:
64
+ # Pre-compute hash and get compiled function
65
+ model_hash = hash(model)
66
+ if model_hash not in Model._compiled_cache:
67
+ raise ValueError("Model must be compiled before creating _FittingContext")
68
+ self._compiled_fn = Model._compiled_cache[model_hash]
69
+
70
+ # Pre-compute index params
71
+ self._index_params = [p for p in model.free if p.kind == _Param.index]
72
+ self._has_indices = bool(self._index_params)
73
+ else:
74
+ self._compiled_fn = None
75
+ self._index_params = []
76
+ self._has_indices = False
77
+
78
+ def set_and_eval(self, *theta_values, index_map=None):
79
+ """Set params and evaluate in one call.
80
+
81
+ Parameters
82
+ ----------
83
+ *theta_values : float
84
+ Parameter values to set.
85
+ index_map : dict, optional
86
+ Mapping of INDEX params to values.
87
+
88
+ Returns
89
+ -------
90
+ result
91
+ The model evaluation result.
92
+ """
93
+ # Set parameter values and fill theta buffer
94
+ for i, v in enumerate(theta_values):
95
+ self.params[i].value = v
96
+ self.theta[i] = v
97
+
98
+ if self.use_numba:
99
+ index_list = None
100
+ if self._has_indices and index_map:
101
+ index_list = [index_map[p] for p in self._index_params]
102
+ # Pass x_data (from cost model memory) to compiled function
103
+ return self._compiled_fn(self._x_data, index_list, self.theta)
104
+ else:
105
+ return self._model.eval_py(self._x_data, index_map or {})
106
+
107
+
108
+ class FitResult:
109
+ """Container for fit results from ``fit()``.
110
+
111
+ Stores the fitted model, parameter values and errors, and provides
112
+ methods for visualization and analysis.
113
+
114
+ Attributes
115
+ ----------
116
+ model : Model
117
+ The cost model that was fitted.
118
+ minimizer : iminuit.Minuit
119
+ The underlying iminuit Minuit object.
120
+ fval : float
121
+ The minimum cost function value achieved.
122
+ success : bool
123
+ True if the fit converged successfully.
124
+ values : dict[str, float]
125
+ Fitted parameter values by name.
126
+ errors : dict[str, float]
127
+ Parameter uncertainties by name.
128
+ x : ndarray
129
+ The x-data (bin centers for binned fits).
130
+ y : ndarray | None
131
+ The y-data (counts for binned fits, None for unbinned).
132
+ predict : Model
133
+ The frozen model for predictions, scaled by bin widths.
134
+
135
+ Examples
136
+ --------
137
+ >>> result = fit(model | Cost.NLL(data))
138
+ >>> print(result) # Shows all parameters
139
+ >>> result.plot_data()
140
+ >>> result.plot_fit()
141
+ """
142
+
143
+ def __init__(self, model: Model, m: iminuit.Minuit):
144
+ """Initialize a FitResult from a model and Minuit object.
145
+
146
+ Parameters
147
+ ----------
148
+ model : Model
149
+ The cost model that was minimized.
150
+ m : iminuit.Minuit
151
+ The Minuit minimizer after optimization.
152
+ """
153
+ self.minimizer = m
154
+ self.model = model
155
+
156
+ if "cost" not in model.memory:
157
+ raise ValueError(
158
+ f"Model was not created with a Cost function.\n"
159
+ f" Use: model | Cost.NLL(data) or model | Cost.MSE(x, y)\n"
160
+ f" Got: {model}"
161
+ )
162
+ self.cost = model.memory['cost']
163
+
164
+ if self.cost.bin_widths is not None:
165
+ bw = self.cost.bin_widths()
166
+ self.bin_widths = bw if bw is not None else 1
167
+ self.bin_width = np.mean(self.bin_widths)
168
+ else:
169
+ self.bin_widths = 1
170
+ self.bin_width = 1
171
+
172
+ if "base" not in model.memory:
173
+ raise ValueError(
174
+ f"Model has no base expression stored.\n"
175
+ f" This usually means the Cost was not applied correctly."
176
+ )
177
+ self.predict = model.memory['base'].freeze() * const(self.bin_width)
178
+ self.x = self.cost.x()
179
+ self.y = self.cost.y() if self.cost.y is not None else None
180
+ self.fval = m.fval
181
+ self.success = m.valid
182
+ self._populate_params()
183
+
184
+ self.values = {}
185
+ self.errors = {}
186
+
187
+ i=0
188
+ seen = {}
189
+ for p in model.params:
190
+ base = p.name if p.name else f"x{i}"
191
+ if base in seen:
192
+ seen[base] += 1
193
+ name = f"{base}_{seen[base]}"
194
+ else:
195
+ seen[base] = 0
196
+ name = base
197
+
198
+ i += 1
199
+ self.values[name] = p.value
200
+ self.errors[name] = p.error
201
+
202
+
203
+ def _populate_params(self) -> None:
204
+ """Copy fitted values and errors from Minuit to Param objects.
205
+
206
+ Updates each Param's ``value`` and ``error`` attributes with
207
+ the results from the minimizer.
208
+ """
209
+ for p, v, e in zip(self.model.params, self.minimizer.values, self.minimizer.errors):
210
+ p.value = v
211
+ p.error = e
212
+
213
+ def __repr__(self):
214
+ i=0
215
+ ret = f"<FitResult fval={self.fval:.3f}, success={self.success}>\n"
216
+ for p in self.model.params:
217
+ name = p.name if p.name else f"x{i}"; i+=1
218
+ ret += f"{name}: {p.value:.4g} ± {p.error:.2g}\n"
219
+ return ret
220
+
221
+ def plot_data(self) -> None:
222
+ """Plot the observed data with error bars.
223
+
224
+ Displays data points as markers with Poisson error bars
225
+ (sqrt(y)). Only available for binned fits.
226
+
227
+ Raises
228
+ ------
229
+ ValueError
230
+ If this is an unbinned fit (no y-data).
231
+ """
232
+ if self.y is None:
233
+ raise ValueError("plot_data() not available for unbinned fits")
234
+ plt.errorbar(self.x, self.y, linestyle='', marker='.', color='black', yerr=np.sqrt(self.y))
235
+
236
+ def plot_fit(self) -> None:
237
+ """Plot the fitted model prediction.
238
+
239
+ Displays the model evaluated at the bin centers, scaled by
240
+ bin widths. Only available for binned fits.
241
+
242
+ Raises
243
+ ------
244
+ ValueError
245
+ If this is an unbinned fit (no y-data).
246
+ """
247
+ if self.y is None:
248
+ raise ValueError("plot_fit() not available for unbinned fits")
249
+ plt.plot(self.x, self.predict(self.x))
250
+
251
+ def dof(self) -> int:
252
+ """Calculate degrees of freedom.
253
+
254
+ Returns the number of data points minus the number of
255
+ fitted parameters. Only available for binned fits.
256
+
257
+ Returns
258
+ -------
259
+ int
260
+ Degrees of freedom (n_bins - n_parameters).
261
+
262
+ Raises
263
+ ------
264
+ ValueError
265
+ If this is an unbinned fit.
266
+ """
267
+ if self.y is None:
268
+ raise ValueError("dof() not available for unbinned fits")
269
+ # Count only free parameters (not fixed constants where min == max)
270
+ n_free = sum(1 for p in self.model.params if p.min != p.max)
271
+ return len(self.cost.x()) - n_free
272
+
273
+ def fit(
274
+ model: Model,
275
+ numba: bool = True,
276
+ grad: bool = True,
277
+ ncall: int = 9999999,
278
+ options: dict | None = None
279
+ ) -> FitResult:
280
+ """Fit a cost model by minimizing its parameters.
281
+
282
+ Uses iminuit's MIGRAD algorithm to find parameter values that
283
+ minimize the cost function.
284
+
285
+ Parameters
286
+ ----------
287
+ model : Model
288
+ A cost model created by piping a model to a Cost function,
289
+ e.g., ``gaussian() | Cost.NLL(data)``.
290
+ numba : bool, default True
291
+ If True, compile the model with Numba for faster evaluation.
292
+ Falls back to Python if compilation fails.
293
+ grad : bool, default True
294
+ If True, compute analytical gradients for the optimizer.
295
+ Falls back to numerical gradients if symbolic differentiation
296
+ fails.
297
+ ncall : int, default 9999999
298
+ Maximum number of function calls for MIGRAD.
299
+ options : dict, optional
300
+ Additional keyword arguments passed to ``iminuit.Minuit()``.
301
+
302
+ Returns
303
+ -------
304
+ FitResult
305
+ Object containing fitted parameters, errors, and plotting methods.
306
+
307
+ Raises
308
+ ------
309
+ TypeError
310
+ If ``model`` is not a callable Model instance.
311
+
312
+ Examples
313
+ --------
314
+ >>> model = gaussian(Param("mu"), Param.positive("sigma"))
315
+ >>> cost = model | Cost.NLL(data)
316
+ >>> result = fit(cost)
317
+ >>> print(result.values) # {'mu': 5.2, 'sigma': 1.1}
318
+ """
319
+ if options is None:
320
+ options = {}
321
+
322
+ if not isinstance(model, Model) or not callable(model):
323
+ raise TypeError(
324
+ f"Expected a Model instance, got {type(model).__name__}.\n"
325
+ f" Create a model using Param, Cost, and arithmetic operations."
326
+ )
327
+
328
+ # Try gradient construction
329
+ grad_model = None
330
+ if grad:
331
+ try:
332
+ grad_model = model.grad()
333
+ # Copy _eval_x from cost model to gradient for INPUT preservation
334
+ if '_eval_x' in model.memory:
335
+ grad_model.memory['_eval_x'] = model.memory['_eval_x']
336
+ except Exception as e:
337
+ warnings.warn(
338
+ f"Gradient computation failed, falling back to numerical gradients.\n"
339
+ f" Reason: {e}\n"
340
+ f" Model: {model}\n"
341
+ f" Tip: Use grad=False to suppress this warning.",
342
+ UserWarning,
343
+ stacklevel=2
344
+ )
345
+ grad = False
346
+
347
+ # Try compilation
348
+ if numba:
349
+ try:
350
+ model.compile()
351
+ if grad and grad_model is not None:
352
+ grad_model.compile()
353
+ except Exception as e:
354
+ warnings.warn(
355
+ f"Numba compilation failed, falling back to Python.\n"
356
+ f" Reason: {e}\n"
357
+ f" Model: {model}\n"
358
+ f" Tip: Use numba=False to suppress this warning.",
359
+ UserWarning,
360
+ stacklevel=2
361
+ )
362
+ numba = False
363
+
364
+ params = model.params
365
+ if not params:
366
+ raise ValueError("Model has no parameters to fit.")
367
+
368
+ # Create optimized fitting contexts for fast evaluation
369
+ ctx = _FittingContext(model, use_numba=numba)
370
+ grad_ctx = _FittingContext(grad_model, use_numba=numba) if grad and grad_model else None
371
+
372
+ def loss_fn(*theta):
373
+ try:
374
+ return ctx.set_and_eval(*theta)
375
+ except Exception as e:
376
+ param_info = ", ".join(f"{p.name}={v:.4g}" for p, v in zip(params, theta))
377
+ raise RuntimeError(
378
+ f"Model evaluation failed during fitting.\n"
379
+ f" Parameters: {param_info}\n"
380
+ f" Model: {model}\n"
381
+ f" Original error: {e}"
382
+ ) from e
383
+
384
+ def grad_fn(*theta):
385
+ try:
386
+ return grad_ctx.set_and_eval(*theta)
387
+ except Exception as e:
388
+ param_info = ", ".join(f"{p.name}={v:.4g}" for p, v in zip(params, theta))
389
+ raise RuntimeError(
390
+ f"Gradient evaluation failed during fitting.\n"
391
+ f" Parameters: {param_info}\n"
392
+ f" Original error: {e}"
393
+ ) from e
394
+
395
+ start = [p.start for p in params]
396
+ bounds = [(p.min, p.max) for p in params]
397
+
398
+ m = iminuit.Minuit(loss_fn, *start, grad=grad_fn if grad_ctx else None, **options)
399
+ m.limits = bounds
400
+ m.migrad(ncall)
401
+
402
+ return FitResult(model, m)