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/__init__.py +9 -0
- fitle/compiler.py +681 -0
- fitle/cost.py +358 -0
- fitle/fitting.py +402 -0
- fitle/model.py +1372 -0
- fitle/param.py +542 -0
- fitle/pdfs.py +207 -0
- fitle-0.1.0.dist-info/METADATA +628 -0
- fitle-0.1.0.dist-info/RECORD +12 -0
- fitle-0.1.0.dist-info/WHEEL +5 -0
- fitle-0.1.0.dist-info/licenses/LICENSE +21 -0
- fitle-0.1.0.dist-info/top_level.txt +1 -0
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)
|