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 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/