fitle 0.1.0__tar.gz
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-0.1.0/LICENSE +21 -0
- fitle-0.1.0/PKG-INFO +628 -0
- fitle-0.1.0/README.md +609 -0
- fitle-0.1.0/pyproject.toml +29 -0
- fitle-0.1.0/setup.cfg +4 -0
- fitle-0.1.0/src/fitle/__init__.py +9 -0
- fitle-0.1.0/src/fitle/compiler.py +681 -0
- fitle-0.1.0/src/fitle/cost.py +358 -0
- fitle-0.1.0/src/fitle/fitting.py +402 -0
- fitle-0.1.0/src/fitle/model.py +1372 -0
- fitle-0.1.0/src/fitle/param.py +542 -0
- fitle-0.1.0/src/fitle/pdfs.py +207 -0
- fitle-0.1.0/src/fitle.egg-info/PKG-INFO +628 -0
- fitle-0.1.0/src/fitle.egg-info/SOURCES.txt +22 -0
- fitle-0.1.0/src/fitle.egg-info/dependency_links.txt +1 -0
- fitle-0.1.0/src/fitle.egg-info/requires.txt +8 -0
- fitle-0.1.0/src/fitle.egg-info/top_level.txt +1 -0
- fitle-0.1.0/tests/test_cost.py +290 -0
- fitle-0.1.0/tests/test_fitting.py +411 -0
- fitle-0.1.0/tests/test_model.py +886 -0
- fitle-0.1.0/tests/test_numpy_integration.py +340 -0
- fitle-0.1.0/tests/test_param.py +236 -0
- fitle-0.1.0/tests/test_param_builder.py +437 -0
- fitle-0.1.0/tests/test_pdfs.py +322 -0
fitle-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2025 Trey Warner
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
fitle-0.1.0/PKG-INFO
ADDED
|
@@ -0,0 +1,628 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: fitle
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: A tiny, fast library for building statistical models, compiling them to Numba, and fitting with iminuit.
|
|
5
|
+
Author-email: Trey Warner <warnertrey07@gmail.com>
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: homepage, https://github.com/treywarner72/fitle/
|
|
8
|
+
Requires-Python: >=3.8
|
|
9
|
+
Description-Content-Type: text/markdown
|
|
10
|
+
License-File: LICENSE
|
|
11
|
+
Requires-Dist: numpy
|
|
12
|
+
Requires-Dist: numba
|
|
13
|
+
Requires-Dist: iminuit
|
|
14
|
+
Requires-Dist: scipy
|
|
15
|
+
Provides-Extra: dev
|
|
16
|
+
Requires-Dist: pytest; extra == "dev"
|
|
17
|
+
Requires-Dist: matplotlib; extra == "dev"
|
|
18
|
+
Dynamic: license-file
|
|
19
|
+
|
|
20
|
+
# fitle
|
|
21
|
+
|
|
22
|
+
A fast library for building statistical models, compiling them to efficient [Numba] code, and fitting to data with [iminuit].
|
|
23
|
+
|
|
24
|
+
> - Compose models from pieces (`Param`, arithmetic, `numpy` ops).
|
|
25
|
+
> - Tie it to data with cost functions (MSE, (un)binned NLL, chi-squared).
|
|
26
|
+
> - Fit with `iminuit`.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## Install
|
|
31
|
+
|
|
32
|
+
```bash
|
|
33
|
+
pip install -e .
|
|
34
|
+
# or
|
|
35
|
+
pip3 install git+https://github.com/treywarner72/fitle.git
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Dependencies
|
|
39
|
+
|
|
40
|
+
- Python 3.10+
|
|
41
|
+
- `numpy`
|
|
42
|
+
- `numba`
|
|
43
|
+
- `iminuit`
|
|
44
|
+
|
|
45
|
+
---
|
|
46
|
+
|
|
47
|
+
## Quick Start
|
|
48
|
+
|
|
49
|
+
```python
|
|
50
|
+
import numpy as np
|
|
51
|
+
from fitle import Param, gaussian, fit, Cost
|
|
52
|
+
|
|
53
|
+
# Generate sample data
|
|
54
|
+
data = np.random.normal(1850, 10, 1000)
|
|
55
|
+
|
|
56
|
+
# Define parameters (auto-named from variable assignment)
|
|
57
|
+
mu = ~Param # unbounded param, auto-named 'mu'
|
|
58
|
+
sigma = +Param # positive param (>0), auto-named 'sigma'
|
|
59
|
+
|
|
60
|
+
# Build a Gaussian PDF model
|
|
61
|
+
model = gaussian(mu, sigma)
|
|
62
|
+
|
|
63
|
+
# Fit using unbinned negative log-likelihood
|
|
64
|
+
result = fit(model | Cost.NLL(data))
|
|
65
|
+
print(result)
|
|
66
|
+
# <FitResult fval=3713.952, success=True>
|
|
67
|
+
# mu: 1850 +/- 0.44
|
|
68
|
+
# sigma: 9.925 +/- 0.31
|
|
69
|
+
|
|
70
|
+
# Evaluate the fitted model
|
|
71
|
+
model([1851, 1852, 1853, 1854])
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
---
|
|
75
|
+
|
|
76
|
+
## Building Blocks
|
|
77
|
+
|
|
78
|
+
### Parameters
|
|
79
|
+
|
|
80
|
+
```python
|
|
81
|
+
from fitle import Param, INPUT, index, INDEX
|
|
82
|
+
|
|
83
|
+
# Shorthand with unary operators (auto-named from variable)
|
|
84
|
+
a = ~Param # unbounded, auto-named 'a'
|
|
85
|
+
sigma = +Param # positive (>0), auto-named 'sigma'
|
|
86
|
+
neg = -Param # negative (<0), auto-named 'neg'
|
|
87
|
+
|
|
88
|
+
# Tuple unpacking works too
|
|
89
|
+
mu, sigma = ~Param, +Param # auto-named 'mu' and 'sigma'
|
|
90
|
+
|
|
91
|
+
# Explicit creation (with chaining)
|
|
92
|
+
b = Param('name') # explicit name
|
|
93
|
+
c = Param(5.0) # with starting value
|
|
94
|
+
d = Param('name')(0, 10)(5.0) # name, bounds, start (chainable)
|
|
95
|
+
|
|
96
|
+
# Constrained param builders
|
|
97
|
+
tau = Param.positive('tau') # >0, start=1
|
|
98
|
+
f = Param.unit('frac') # [0,1], start=0.5
|
|
99
|
+
|
|
100
|
+
# The independent variable (INPUT)
|
|
101
|
+
linear = a * INPUT + b
|
|
102
|
+
|
|
103
|
+
# Integer index for reductions
|
|
104
|
+
i = index(10) # range(0, 10)
|
|
105
|
+
j = index(5, 20) # range(5, 20)
|
|
106
|
+
k = index(0, 100, 2) # range(0, 100, 2)
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
### Models & Composition
|
|
110
|
+
|
|
111
|
+
```python
|
|
112
|
+
from fitle import gaussian, exponential, Param, INPUT
|
|
113
|
+
|
|
114
|
+
# Pre-built PDFs with auto-named params
|
|
115
|
+
mu1, s1 = ~Param, +Param
|
|
116
|
+
g1 = gaussian(mu1, s1)
|
|
117
|
+
|
|
118
|
+
mu2, s2 = ~Param, +Param
|
|
119
|
+
g2 = gaussian(mu2, s2)
|
|
120
|
+
|
|
121
|
+
tau = +Param
|
|
122
|
+
exp_tail = exponential(tau)
|
|
123
|
+
|
|
124
|
+
# Composite model with normalization parameters
|
|
125
|
+
n1, n2, n_bg = +Param, +Param, +Param
|
|
126
|
+
composite = n1 * g1 + n2 * g2 + n_bg * exp_tail
|
|
127
|
+
|
|
128
|
+
# Arithmetic with INPUT
|
|
129
|
+
a, b, c = ~Param, ~Param, ~Param
|
|
130
|
+
polynomial = a * INPUT**2 + b * INPUT + c
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
---
|
|
134
|
+
|
|
135
|
+
## Cost Functions
|
|
136
|
+
|
|
137
|
+
Cost functions transform a model into a scalar loss for optimization.
|
|
138
|
+
|
|
139
|
+
```python
|
|
140
|
+
from fitle import Cost
|
|
141
|
+
|
|
142
|
+
# Mean Squared Error for regression
|
|
143
|
+
loss = model | Cost.MSE(x_data, y_data)
|
|
144
|
+
|
|
145
|
+
# Unbinned Negative Log-Likelihood (for PDFs)
|
|
146
|
+
loss = model | Cost.NLL(data)
|
|
147
|
+
loss = model | Cost.unbinnedNLL(data) # same as above
|
|
148
|
+
|
|
149
|
+
# Binned Chi-squared
|
|
150
|
+
loss = model | Cost.chi2(data=sample, bins=100, range=(0, 10))
|
|
151
|
+
loss = model | Cost.chi2(x=centers, y=counts, bin_widths=widths)
|
|
152
|
+
|
|
153
|
+
# Binned Negative Log-Likelihood
|
|
154
|
+
loss = model | Cost.binnedNLL(data=sample, bins=100, range=(0, 10))
|
|
155
|
+
loss = model | Cost.binnedNLL(x=centers, y=counts, bin_widths=widths)
|
|
156
|
+
```
|
|
157
|
+
|
|
158
|
+
All cost functions return a `Model` that evaluates to a scalar.
|
|
159
|
+
|
|
160
|
+
---
|
|
161
|
+
|
|
162
|
+
## Fitting
|
|
163
|
+
|
|
164
|
+
```python
|
|
165
|
+
from fitle import fit
|
|
166
|
+
|
|
167
|
+
result = fit(loss)
|
|
168
|
+
|
|
169
|
+
print(result.fval) # minimum cost value
|
|
170
|
+
print(result.success) # True if converged
|
|
171
|
+
print(result.values) # {'param_name': value, ...}
|
|
172
|
+
print(result.errors) # {'param_name': error, ...}
|
|
173
|
+
|
|
174
|
+
# Access the frozen prediction model
|
|
175
|
+
y_pred = result.predict(x_new)
|
|
176
|
+
|
|
177
|
+
# Plot for binned fits
|
|
178
|
+
result.plot_data() # data with error bars
|
|
179
|
+
result.plot_fit() # fitted curve
|
|
180
|
+
```
|
|
181
|
+
|
|
182
|
+
### Fit Options
|
|
183
|
+
|
|
184
|
+
```python
|
|
185
|
+
# Disable Numba compilation (use pure Python)
|
|
186
|
+
result = fit(loss, numba=False)
|
|
187
|
+
|
|
188
|
+
# Disable analytical gradients (use numerical)
|
|
189
|
+
result = fit(loss, grad=False)
|
|
190
|
+
|
|
191
|
+
# Pass options to iminuit
|
|
192
|
+
result = fit(loss, options={'print_level': 2})
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## Reductions & Indexing
|
|
198
|
+
|
|
199
|
+
Reductions sum expressions over an integer index.
|
|
200
|
+
|
|
201
|
+
```python
|
|
202
|
+
from fitle import index, indecise, const, Reduction, gaussian, INPUT
|
|
203
|
+
|
|
204
|
+
# Create an index over range(N)
|
|
205
|
+
i = index(10)
|
|
206
|
+
|
|
207
|
+
# indecise picks element at index from an array
|
|
208
|
+
weights = indecise(const([0.1, 0.2, 0.3, ...]), i)
|
|
209
|
+
centers = indecise(const([1.0, 2.0, 3.0, ...]), i)
|
|
210
|
+
|
|
211
|
+
# Build expression and reduce
|
|
212
|
+
term = weights * gaussian(centers, sigma)
|
|
213
|
+
total = Reduction(term, i) # sum over i
|
|
214
|
+
```
|
|
215
|
+
|
|
216
|
+
### Example: Discrete Convolution
|
|
217
|
+
|
|
218
|
+
```python
|
|
219
|
+
def convolve_hist(centers, counts, mu, sigma):
|
|
220
|
+
i = index(len(counts))
|
|
221
|
+
w = indecise(const(counts), i)
|
|
222
|
+
c = indecise(const(centers), i)
|
|
223
|
+
g = gaussian(c, sigma)
|
|
224
|
+
return Reduction(w * g, i)
|
|
225
|
+
|
|
226
|
+
mu, sigma = ~Param, +Param
|
|
227
|
+
model = convolve_hist(hist_centers, hist_counts, mu, sigma)
|
|
228
|
+
```
|
|
229
|
+
|
|
230
|
+
---
|
|
231
|
+
|
|
232
|
+
## Compilation
|
|
233
|
+
|
|
234
|
+
Models are automatically compiled when fitting. You can also compile manually:
|
|
235
|
+
|
|
236
|
+
```python
|
|
237
|
+
model.compile() # JIT compile with Numba
|
|
238
|
+
print(model.code) # inspect generated source
|
|
239
|
+
print(model.compiled) # True if compiled
|
|
240
|
+
|
|
241
|
+
# Cache management
|
|
242
|
+
Model.cache_info() # {'size': N, 'limit': 128}
|
|
243
|
+
Model.clear_cache() # free memory
|
|
244
|
+
```
|
|
245
|
+
|
|
246
|
+
---
|
|
247
|
+
|
|
248
|
+
## Plotting
|
|
249
|
+
|
|
250
|
+
```python
|
|
251
|
+
import matplotlib.pyplot as plt
|
|
252
|
+
import numpy as np
|
|
253
|
+
|
|
254
|
+
# Composite model
|
|
255
|
+
model = signal_1 + signal_2 + background
|
|
256
|
+
result = fit(model | Cost.NLL(data))
|
|
257
|
+
|
|
258
|
+
# Plot components separately (they share fitted parameters)
|
|
259
|
+
x = np.linspace(0, 100, 200)
|
|
260
|
+
plt.plot(x, model(x), label='Total')
|
|
261
|
+
plt.plot(x, signal_1(x), label='Signal 1')
|
|
262
|
+
plt.plot(x, signal_2(x), label='Signal 2')
|
|
263
|
+
plt.plot(x, background(x), label='Background')
|
|
264
|
+
plt.legend()
|
|
265
|
+
```
|
|
266
|
+
|
|
267
|
+
---
|
|
268
|
+
|
|
269
|
+
## Tips
|
|
270
|
+
|
|
271
|
+
- **Substitution** with `%`:
|
|
272
|
+
```python
|
|
273
|
+
model % x_array # substitute INPUT with data
|
|
274
|
+
model % {INPUT: x_array} # explicit form
|
|
275
|
+
model % {param: 5.0} # fix a parameter to a value
|
|
276
|
+
model % {param: other_model} # replace with another model
|
|
277
|
+
```
|
|
278
|
+
|
|
279
|
+
- **Chi-squared with zero bins**: Use `zero_method='absolute'` to handle bins with zero counts.
|
|
280
|
+
|
|
281
|
+
- **Gradients**: If symbolic differentiation fails, fit automatically falls back to numerical gradients.
|
|
282
|
+
|
|
283
|
+
- **Freezing**: Use `model.freeze()` to replace all parameters with their current values.
|
|
284
|
+
|
|
285
|
+
---
|
|
286
|
+
|
|
287
|
+
## Full API Reference
|
|
288
|
+
|
|
289
|
+
### Module: `fitle.param`
|
|
290
|
+
|
|
291
|
+
#### `Param` (Builder)
|
|
292
|
+
|
|
293
|
+
The `Param` builder creates `_Param` instances for model building.
|
|
294
|
+
|
|
295
|
+
**Shorthand syntax (auto-named from variable):**
|
|
296
|
+
```python
|
|
297
|
+
a = ~Param # unbounded param, named 'a'
|
|
298
|
+
sigma = +Param # positive param (>0), named 'sigma'
|
|
299
|
+
neg = -Param # negative param (<0), named 'neg'
|
|
300
|
+
mu, sigma = ~Param, +Param # tuple unpacking works
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
**Explicit creation:**
|
|
304
|
+
```python
|
|
305
|
+
Param() # unbounded, auto-named
|
|
306
|
+
Param('name') # explicit name
|
|
307
|
+
Param(5.0) # start value, auto-named
|
|
308
|
+
Param(0, 10) # bounds [0,10], auto-named
|
|
309
|
+
Param('x')(0, 10)(5.0) # chained: name, bounds, start
|
|
310
|
+
```
|
|
311
|
+
|
|
312
|
+
**Constrained builders:**
|
|
313
|
+
- `Param.positive(name=None)` - Positive parameter (min=1e-6, start=1)
|
|
314
|
+
- `Param.negative(name=None)` - Negative parameter (max=-1e-6, start=-1)
|
|
315
|
+
- `Param.unit(name=None)` - Unit interval [0,1] (start=0.5)
|
|
316
|
+
|
|
317
|
+
#### `_Param` (Instance)
|
|
318
|
+
|
|
319
|
+
The actual parameter object (created by `Param` builder).
|
|
320
|
+
|
|
321
|
+
**Attributes:**
|
|
322
|
+
- `kind` - Parameter role: `THETA` (optimizable), `INPUT` (data), or `INDEX` (loop variable)
|
|
323
|
+
- `name` - String identifier (may be auto-detected)
|
|
324
|
+
- `min`, `max` - Bounds for optimization (THETA only)
|
|
325
|
+
- `start` - Initial value for optimization
|
|
326
|
+
- `value` - Current value (updated during fitting)
|
|
327
|
+
- `error` - Uncertainty estimate (set after fitting)
|
|
328
|
+
- `range` - Loop range (INDEX only)
|
|
329
|
+
|
|
330
|
+
**Methods:**
|
|
331
|
+
- `__call__(arg0, arg1=None)` - Chainable setter: string sets name, number sets start, two numbers set bounds
|
|
332
|
+
|
|
333
|
+
#### `INPUT`
|
|
334
|
+
|
|
335
|
+
Singleton `Param` representing the independent variable (x-data).
|
|
336
|
+
|
|
337
|
+
#### `index(*args) -> Param`
|
|
338
|
+
|
|
339
|
+
Create an INDEX parameter with `range(*args)`.
|
|
340
|
+
|
|
341
|
+
```python
|
|
342
|
+
i = index(10) # range(0, 10)
|
|
343
|
+
j = index(5, 20) # range(5, 20)
|
|
344
|
+
k = index(0, 10, 2) # range(0, 10, 2)
|
|
345
|
+
```
|
|
346
|
+
|
|
347
|
+
#### `INDEX`
|
|
348
|
+
|
|
349
|
+
Default INDEX parameter (unbound range).
|
|
350
|
+
|
|
351
|
+
---
|
|
352
|
+
|
|
353
|
+
### Module: `fitle.model`
|
|
354
|
+
|
|
355
|
+
#### `class Model`
|
|
356
|
+
|
|
357
|
+
Represents a symbolic expression tree.
|
|
358
|
+
|
|
359
|
+
```python
|
|
360
|
+
Model(fn, args)
|
|
361
|
+
```
|
|
362
|
+
|
|
363
|
+
**Attributes:**
|
|
364
|
+
- `fn` - The function this node applies
|
|
365
|
+
- `args` - List of arguments (may include Param, Model, constants)
|
|
366
|
+
- `params` - List of all THETA parameters in the tree
|
|
367
|
+
- `free` - List of INPUT and INDEX parameters
|
|
368
|
+
- `compiled` - True if a compiled version exists in cache
|
|
369
|
+
- `code` - Generated source code (after compilation)
|
|
370
|
+
- `memory` - Dict for metadata (used by Cost)
|
|
371
|
+
- `components` - List of sub-models (split at `identity()` boundaries)
|
|
372
|
+
|
|
373
|
+
**Methods:**
|
|
374
|
+
|
|
375
|
+
| Method | Description |
|
|
376
|
+
|--------|-------------|
|
|
377
|
+
| `__call__(x=None)` | Evaluate the model or perform substitution |
|
|
378
|
+
| `__mod__(subs)` | Substitute parameters/INPUT with new values |
|
|
379
|
+
| `__getitem__(index)` | Evaluate or substitute at given index |
|
|
380
|
+
| `copy()` | Deep copy with independent THETA params |
|
|
381
|
+
| `copy_with_args(args)` | Shallow copy with new arguments |
|
|
382
|
+
| `freeze()` | Replace all params with current values |
|
|
383
|
+
| `grad(wrt=None)` | Symbolic gradient w.r.t. parameters |
|
|
384
|
+
| `simplify()` | Apply algebraic simplifications |
|
|
385
|
+
| `shape()` | Infer output shape |
|
|
386
|
+
| `compile()` | JIT compile with Numba |
|
|
387
|
+
| `eval(x, index_map, numba=False)` | Low-level evaluation |
|
|
388
|
+
| `eval_py(x, index_map)` | Pure Python evaluation |
|
|
389
|
+
|
|
390
|
+
**Arithmetic:** Models support `+`, `-`, `*`, `/`, `**`, unary `-`, and comparisons (`<`, `<=`, `>`, `>=`, `!=`).
|
|
391
|
+
|
|
392
|
+
**Class Methods:**
|
|
393
|
+
- `Model.clear_cache()` - Clear the compilation cache
|
|
394
|
+
- `Model.cache_info()` - Return cache size and limit
|
|
395
|
+
|
|
396
|
+
#### `class Reduction(Model)`
|
|
397
|
+
|
|
398
|
+
Reduce an expression over an INDEX parameter.
|
|
399
|
+
|
|
400
|
+
```python
|
|
401
|
+
Reduction(model, index_param, op=operator.add)
|
|
402
|
+
```
|
|
403
|
+
|
|
404
|
+
Currently only `operator.add` is supported for compilation.
|
|
405
|
+
|
|
406
|
+
#### `const(val) -> Model`
|
|
407
|
+
|
|
408
|
+
Wrap a constant value as a Model node.
|
|
409
|
+
|
|
410
|
+
```python
|
|
411
|
+
c = const(5.0)
|
|
412
|
+
arr = const(np.array([1, 2, 3]))
|
|
413
|
+
```
|
|
414
|
+
|
|
415
|
+
#### `indecise(obj, index=INDEX) -> Model`
|
|
416
|
+
|
|
417
|
+
Create a Model that indexes into an array.
|
|
418
|
+
|
|
419
|
+
```python
|
|
420
|
+
weights = indecise(const([0.1, 0.2, 0.3]), i)
|
|
421
|
+
# Evaluates to obj[int(index)]
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
#### `identity(val) -> Model`
|
|
425
|
+
|
|
426
|
+
Wrap a value in an identity node (useful for component boundaries).
|
|
427
|
+
|
|
428
|
+
#### `vector(*models) -> Model`
|
|
429
|
+
|
|
430
|
+
Stack multiple models into an array output.
|
|
431
|
+
|
|
432
|
+
```python
|
|
433
|
+
gradients = vector(model.grad(p1), model.grad(p2))
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
---
|
|
437
|
+
|
|
438
|
+
### Module: `fitle.cost`
|
|
439
|
+
|
|
440
|
+
#### `class Cost`
|
|
441
|
+
|
|
442
|
+
Factory for cost functions.
|
|
443
|
+
|
|
444
|
+
**Class Methods:**
|
|
445
|
+
|
|
446
|
+
| Method | Description |
|
|
447
|
+
|--------|-------------|
|
|
448
|
+
| `Cost.MSE(x, y)` | Mean Squared Error: `sum((y - model(x))^2)` |
|
|
449
|
+
| `Cost.NLL(x)` | Unbinned Negative Log-Likelihood: `sum(-log(model(x)))` |
|
|
450
|
+
| `Cost.unbinnedNLL(x)` | Alias for `NLL` |
|
|
451
|
+
| `Cost.chi2(...)` | Chi-squared for binned data |
|
|
452
|
+
| `Cost.binnedNLL(...)` | Binned Negative Log-Likelihood |
|
|
453
|
+
|
|
454
|
+
**Chi-squared / Binned NLL signatures:**
|
|
455
|
+
|
|
456
|
+
```python
|
|
457
|
+
# From raw data
|
|
458
|
+
Cost.chi2(data=array, bins=int, range=(min, max))
|
|
459
|
+
Cost.chi2(data=array, bins=edges_array)
|
|
460
|
+
|
|
461
|
+
# From histogram
|
|
462
|
+
Cost.chi2(x=centers, y=counts, bin_widths=widths)
|
|
463
|
+
|
|
464
|
+
# Chi2 options
|
|
465
|
+
Cost.chi2(..., zero_method='error') # raise on zero counts (default)
|
|
466
|
+
Cost.chi2(..., zero_method='absolute') # use absolute residuals for zeros
|
|
467
|
+
```
|
|
468
|
+
|
|
469
|
+
**Usage:** Pipe a model into a cost with `|`:
|
|
470
|
+
|
|
471
|
+
```python
|
|
472
|
+
loss = model | Cost.NLL(data)
|
|
473
|
+
```
|
|
474
|
+
|
|
475
|
+
---
|
|
476
|
+
|
|
477
|
+
### Module: `fitle.fitting`
|
|
478
|
+
|
|
479
|
+
#### `fit(model, numba=True, grad=True, ncall=9999999, options=None) -> FitResult`
|
|
480
|
+
|
|
481
|
+
Minimize a cost model using iminuit's MIGRAD.
|
|
482
|
+
|
|
483
|
+
**Parameters:**
|
|
484
|
+
- `model` - Cost model (created with `model | Cost.xxx(...)`)
|
|
485
|
+
- `numba` - Use Numba compilation (default: True)
|
|
486
|
+
- `grad` - Use analytical gradients (default: True)
|
|
487
|
+
- `ncall` - Maximum function calls
|
|
488
|
+
- `options` - Additional kwargs for `iminuit.Minuit`
|
|
489
|
+
|
|
490
|
+
#### `class FitResult`
|
|
491
|
+
|
|
492
|
+
Container for fit results.
|
|
493
|
+
|
|
494
|
+
**Attributes:**
|
|
495
|
+
|
|
496
|
+
| Attribute | Type | Description |
|
|
497
|
+
|-----------|------|-------------|
|
|
498
|
+
| `model` | `Model` | The cost model that was fitted |
|
|
499
|
+
| `fval` | `float` | Minimum cost value |
|
|
500
|
+
| `success` | `bool` | True if fit converged |
|
|
501
|
+
| `values` | `dict[str, float]` | Fitted parameter values |
|
|
502
|
+
| `errors` | `dict[str, float]` | Parameter uncertainties |
|
|
503
|
+
| `predict` | `Model` | Frozen base model for predictions |
|
|
504
|
+
| `x` | `ndarray` | Input data (bin centers) |
|
|
505
|
+
| `y` | `ndarray | None` | Output data (counts), None for unbinned |
|
|
506
|
+
| `minimizer` | `Minuit` | Underlying iminuit object |
|
|
507
|
+
|
|
508
|
+
**Methods:**
|
|
509
|
+
|
|
510
|
+
| Method | Description |
|
|
511
|
+
|--------|-------------|
|
|
512
|
+
| `plot_data()` | Plot data with Poisson error bars (binned only) |
|
|
513
|
+
| `plot_fit()` | Plot fitted model curve (binned only) |
|
|
514
|
+
| `dof()` | Degrees of freedom: n_bins - n_params (binned only) |
|
|
515
|
+
|
|
516
|
+
---
|
|
517
|
+
|
|
518
|
+
### Module: `fitle.pdfs`
|
|
519
|
+
|
|
520
|
+
Pre-built probability density functions.
|
|
521
|
+
|
|
522
|
+
#### `gaussian(mu=None, sigma=None) -> Model`
|
|
523
|
+
|
|
524
|
+
Normalized Gaussian PDF.
|
|
525
|
+
|
|
526
|
+
```python
|
|
527
|
+
# Default parameters (auto-created)
|
|
528
|
+
g = gaussian()
|
|
529
|
+
|
|
530
|
+
# Custom parameters with shorthand
|
|
531
|
+
mu, sigma = ~Param, +Param
|
|
532
|
+
g = gaussian(mu, sigma)
|
|
533
|
+
|
|
534
|
+
# Explicit with chaining
|
|
535
|
+
g = gaussian(Param('mean')(5.0), Param.positive('width')(1.0))
|
|
536
|
+
```
|
|
537
|
+
|
|
538
|
+
#### `exponential(tau=None) -> Model`
|
|
539
|
+
|
|
540
|
+
Normalized exponential PDF: `(1/tau) * exp(-x/tau)`.
|
|
541
|
+
|
|
542
|
+
```python
|
|
543
|
+
e = exponential()
|
|
544
|
+
|
|
545
|
+
# With shorthand
|
|
546
|
+
tau = +Param
|
|
547
|
+
e = exponential(tau)
|
|
548
|
+
```
|
|
549
|
+
|
|
550
|
+
#### `crystalball(alpha, n, mu, sigma) -> Model`
|
|
551
|
+
|
|
552
|
+
Crystal Ball function (Gaussian core + power-law tail).
|
|
553
|
+
|
|
554
|
+
**Parameters:**
|
|
555
|
+
- `alpha` - Transition point in sigma units (typical: 0.5-5)
|
|
556
|
+
- `n` - Tail power (typical: 1.5-10, must be >1)
|
|
557
|
+
- `mu` - Mean
|
|
558
|
+
- `sigma` - Width
|
|
559
|
+
|
|
560
|
+
#### `convolve(d_x, c, mass_mother, mu, sigma, idx=None) -> Model`
|
|
561
|
+
|
|
562
|
+
Discrete convolution of Gaussians with weights.
|
|
563
|
+
|
|
564
|
+
**Parameters:**
|
|
565
|
+
- `d_x` - Center positions for each component
|
|
566
|
+
- `c` - Weights for each component
|
|
567
|
+
- `mass_mother` - Reference mass for shift
|
|
568
|
+
- `mu` - Mean offset parameter
|
|
569
|
+
- `sigma` - Common width for all components
|
|
570
|
+
- `idx` - Optional INDEX parameter
|
|
571
|
+
|
|
572
|
+
---
|
|
573
|
+
|
|
574
|
+
### NumPy Integration
|
|
575
|
+
|
|
576
|
+
NumPy functions work directly with Model and Param objects via `__array_ufunc__` and `__array_function__` protocols:
|
|
577
|
+
|
|
578
|
+
```python
|
|
579
|
+
import numpy as np
|
|
580
|
+
from fitle import INPUT as x, Param
|
|
581
|
+
|
|
582
|
+
# NumPy functions create Model nodes automatically
|
|
583
|
+
model = np.exp(-x**2 / 2)
|
|
584
|
+
model = np.where(x > 0, x, -x)
|
|
585
|
+
model = np.sum(weights * values)
|
|
586
|
+
|
|
587
|
+
# Works with Params too
|
|
588
|
+
mu, sigma = ~Param, +Param
|
|
589
|
+
gaussian = np.exp(-0.5 * ((x - mu) / sigma)**2)
|
|
590
|
+
```
|
|
591
|
+
|
|
592
|
+
**Note:** Keyword arguments (e.g., `np.mean(x, where=...)`) are not supported for compilation. Use positional arguments or equivalent expressions.
|
|
593
|
+
|
|
594
|
+
---
|
|
595
|
+
|
|
596
|
+
### Module: `fitle.compiler`
|
|
597
|
+
|
|
598
|
+
#### `class Compiler`
|
|
599
|
+
|
|
600
|
+
Compiles Model trees to Numba JIT functions.
|
|
601
|
+
|
|
602
|
+
```python
|
|
603
|
+
c = Compiler(model)
|
|
604
|
+
fn = c.compile() # Returns @njit function
|
|
605
|
+
print(c.code) # Generated source code
|
|
606
|
+
```
|
|
607
|
+
|
|
608
|
+
The compilation process:
|
|
609
|
+
1. **DAG Construction** - Build IR with common subexpression detection
|
|
610
|
+
2. **Node Partitioning** - Separate global vs loop-local expressions
|
|
611
|
+
3. **Temporary Allocation** - Assign names to multi-use expressions
|
|
612
|
+
4. **Source Emission** - Generate Python code for `@njit`
|
|
613
|
+
|
|
614
|
+
---
|
|
615
|
+
|
|
616
|
+
## License
|
|
617
|
+
|
|
618
|
+
MIT
|
|
619
|
+
|
|
620
|
+
---
|
|
621
|
+
|
|
622
|
+
## Acknowledgements
|
|
623
|
+
|
|
624
|
+
Built on [NumPy], [Numba], and [iminuit].
|
|
625
|
+
|
|
626
|
+
[NumPy]: https://numpy.org/
|
|
627
|
+
[Numba]: https://numba.pydata.org/
|
|
628
|
+
[iminuit]: https://iminuit.readthedocs.io/
|