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 ADDED
@@ -0,0 +1,9 @@
1
+ from .param import *
2
+ from .model import *
3
+ from .fitting import *
4
+ from .cost import *
5
+ from .pdfs import *
6
+ from .compiler import *
7
+
8
+ __all__ = ["Param", "index", "INPUT", "INDEX", "Model", "identity", "model_sum", "vector", "formula", "Reduction", "const", "fit", "FitResult", "Cost", "gaussian", "exponential", "crystalball", "convolve", "Compiler"]
9
+ __version__ = "0.1.0"
fitle/compiler.py ADDED
@@ -0,0 +1,681 @@
1
+ """compiler.py
2
+ =============
3
+ Numba JIT compilation for Model expression trees.
4
+
5
+ This module converts Model DAGs (directed acyclic graphs) into
6
+ Numba-compiled functions for high-performance numerical evaluation.
7
+
8
+ The compilation process has four stages:
9
+
10
+ 1. **DAG Construction** (``_build_dag``): Walk the Model tree and build
11
+ an intermediate representation (IR) of nodes, detecting common
12
+ subexpressions to avoid redundant computation.
13
+
14
+ 2. **Node Partitioning** (``_partition_nodes``): Separate IR nodes into
15
+ "global" nodes (no loop dependencies) and "loop" buckets (nodes that
16
+ depend on specific INDEX parameters).
17
+
18
+ 3. **Temporary Allocation** (``_allocate_temps``): Assign temporary variable
19
+ names to nodes that are used multiple times, enabling code reuse.
20
+
21
+ 4. **Source Emission** (``_emit_source``): Generate Python source code
22
+ that can be compiled by Numba's ``@njit`` decorator.
23
+
24
+ The compiled function signature is::
25
+
26
+ compiled(x, indices, theta) -> result
27
+
28
+ Where:
29
+ - ``x``: Input data array (or None)
30
+ - ``indices``: List of current index values for INDEX params
31
+ - ``theta``: Array of parameter values in tree-walk order
32
+ """
33
+ from __future__ import annotations
34
+
35
+ import types, textwrap, operator, re, itertools
36
+ import numpy as np
37
+ from numba import njit
38
+ from collections import defaultdict, deque
39
+ from .model import Model, Reduction
40
+ from .param import Param, _Param, INPUT
41
+
42
+ # --------------------------- Internal IR primitives ---------------------------
43
+
44
+ class _IRNode:
45
+ """A single expression node in the intermediate representation.
46
+
47
+ Attributes
48
+ ----------
49
+ expr : str
50
+ RHS Python string that can be pasted into generated code.
51
+ deps : frozenset[_Param]
52
+ Set of INDEX parameters this node depends on.
53
+ users : int
54
+ Number of times other IR nodes reference this node.
55
+ name : str | None
56
+ Temporary variable name assigned during scheduling (None = inline).
57
+ is_red : tuple[str, str] | None
58
+ None for plain expressions, or (acc_name, op) for reductions.
59
+ is_leaf : bool
60
+ True if this is a leaf node (param, constant).
61
+ is_acc : bool
62
+ True if this is an accumulator node for a reduction.
63
+ model : Model | None
64
+ Reference to the original Model (for shape inference).
65
+ """
66
+ __slots__ = ("expr", "deps", "users", "name", "is_red", "is_leaf", "is_acc", "model")
67
+ def __init__(self, expr, deps):
68
+ self.expr = expr
69
+ self.deps = deps # frozenset({index_param, …})
70
+ self.users = 0
71
+ self.name = None
72
+ self.is_red = False
73
+ self.is_leaf = False
74
+ self.is_acc = False
75
+ self.model = None
76
+
77
+
78
+ class _LoopIR:
79
+ """Container for IR nodes that share exactly one INDEX parameter.
80
+
81
+ Groups all expressions that depend on a specific loop variable,
82
+ enabling generation of a single ``for`` loop in the output code.
83
+
84
+ Attributes
85
+ ----------
86
+ idx : Param
87
+ The INDEX parameter this loop iterates over.
88
+ body : list[_IRNode]
89
+ IR nodes executed inside the loop.
90
+ accums : list[tuple]
91
+ Accumulator specifications ``(lhs, node, op)``.
92
+ """
93
+ def __init__(self, index_param: _Param):
94
+ self.idx = index_param
95
+ self.body = [] # list[_IRNode] – executed in loop
96
+ self.accums = [] # list[(lhs, node, op)]
97
+ # each acc gets initialised to 0.0 before the loop
98
+
99
+
100
+ # --------------------------- Compiler class ---------------------------
101
+
102
+ class Compiler:
103
+ """Compiles Model expression trees to Numba JIT functions.
104
+
105
+ Converts a Model DAG into optimized Python source code that is
106
+ then compiled by Numba for fast numerical evaluation.
107
+
108
+ Parameters
109
+ ----------
110
+ root : Model
111
+ The root Model to compile.
112
+
113
+ Attributes
114
+ ----------
115
+ root : Model
116
+ The Model being compiled.
117
+ code : str
118
+ Generated Python source code (available after ``compile()``).
119
+
120
+ Examples
121
+ --------
122
+ >>> c = Compiler(model)
123
+ >>> compiled_fn = c.compile() # Returns numba.njit callable
124
+ >>> print(c.code) # Inspect generated source
125
+ """
126
+ # --------------------------------------------------------------------- #
127
+ def __init__(self, root: Model):
128
+ self.root = root
129
+ self._node_map = {} # Model instance -> _IRNode
130
+ self._loops = {} # _Param.index -> _LoopIR
131
+ self._globals = [] # list[_IRNode] – deps == ∅
132
+ self._idx_vars = {}
133
+ self._final = None # _IRNode that yields return value
134
+ self._hoisted_consts: dict = {}
135
+ self._hoisted_fns : dict = {}
136
+ self._fn_to_name : dict = {} # id(fn) -> name for O(1) lookup
137
+ self._param_to_idx = {p: i for i, p in enumerate(root.params)}
138
+ self._alias_pattern = None # compiled regex for alias substitution
139
+ self._alias_map_id = None # id of last alias_map for cache invalidation
140
+
141
+ # ------------------------------------------------------------------ #
142
+ # PUBLIC ENTRY
143
+ # ------------------------------------------------------------------ #
144
+ def compile(self):
145
+ """Compile the Model and return a Numba JIT function.
146
+
147
+ Executes the four compilation stages: DAG construction, node
148
+ partitioning, temporary allocation, and source emission.
149
+
150
+ Returns
151
+ -------
152
+ callable
153
+ A Numba ``@njit`` compiled function with signature
154
+ ``compiled(x, indices, theta) -> result``.
155
+
156
+ Raises
157
+ ------
158
+ TypeError
159
+ If the model contains numpy functions called with keyword
160
+ arguments, which Numba cannot compile.
161
+ """
162
+ self._check_no_kwargs(self.root)
163
+ self._build_dag(self.root)
164
+ self._partition_nodes()
165
+ self._allocate_temps()
166
+ source, ns = self._emit_source()
167
+ self.code = source
168
+ exec(source, ns)
169
+ return njit(ns["compiled"])
170
+
171
+ def _check_no_kwargs(self, model) -> None:
172
+ """Check that no functions in the tree use kwargs.
173
+
174
+ Raises TypeError if any function was created with keyword arguments
175
+ from numpy's dispatch protocol, since Numba cannot compile these.
176
+ """
177
+ if not isinstance(model, Model):
178
+ return
179
+
180
+ fn = model.fn
181
+ if getattr(fn, '_has_kwargs', False):
182
+ kwargs_str = ', '.join(getattr(fn, '_kwargs_info', ()))
183
+ raise TypeError(
184
+ f"Cannot compile model: numpy function '{fn.__name__}' was called "
185
+ f"with keyword arguments ({kwargs_str}).\n"
186
+ f" Numba does not support keyword arguments in compiled functions.\n"
187
+ f" Either:\n"
188
+ f" - Use positional arguments instead\n"
189
+ f" - Use an equivalent expression (e.g., np.where instead of where=)\n"
190
+ f" - Skip compilation and use Python evaluation"
191
+ )
192
+
193
+ for arg in model.args:
194
+ if isinstance(arg, Model):
195
+ self._check_no_kwargs(arg)
196
+
197
+ def _idx_var(self, idx_param: _Param) -> str:
198
+ """Return the unique loop-variable name for an INDEX Param.
199
+
200
+ Parameters
201
+ ----------
202
+ idx_param : Param
203
+ An INDEX parameter.
204
+
205
+ Returns
206
+ -------
207
+ str
208
+ A unique variable name like ``_i_12345678``.
209
+ """
210
+ return self._idx_vars.setdefault(idx_param,
211
+ f"_i_{id(idx_param)}")
212
+
213
+ def _try_reuse_compiled(self, model: Model):
214
+ """Try to reuse a pre-compiled sub-model.
215
+
216
+ If the model is already in the compiled cache, generate a call
217
+ to the pre-compiled function instead of inlining its expression.
218
+ This can significantly reduce LLVM compilation time.
219
+
220
+ Parameters
221
+ ----------
222
+ model : Model
223
+ A sub-model to potentially reuse.
224
+
225
+ Returns
226
+ -------
227
+ _IRNode | None
228
+ An IR node representing the call to the pre-compiled function,
229
+ or None if the model cannot be reused.
230
+ """
231
+ # Check if model is in compiled cache
232
+ try:
233
+ model_hash = hash(model)
234
+ except Exception:
235
+ return None
236
+
237
+ if model_hash not in Model._compiled_cache:
238
+ return None
239
+
240
+ # Get sub-model's params and check they're all in parent's params
241
+ sub_params = model.params
242
+ if not sub_params:
243
+ # No params - just evaluate and hoist as constant
244
+ return None
245
+
246
+ # Check all sub-model params exist in parent
247
+ for p in sub_params:
248
+ if p not in self._param_to_idx:
249
+ return None # Sub-model has params not in parent
250
+
251
+ # Check if sub-model has INDEX dependencies (complex case, skip for now)
252
+ if any(p.kind == _Param.index for p in model.free):
253
+ return None # Skip models with INDEX for now
254
+
255
+ # Build theta indexing expression
256
+ indices = [self._param_to_idx[p] for p in sub_params]
257
+
258
+ # Check if indices are contiguous (can use slice)
259
+ if indices == list(range(indices[0], indices[0] + len(indices))):
260
+ theta_expr = f"theta[{indices[0]}:{indices[-1]+1}]"
261
+ else:
262
+ # Need explicit array construction
263
+ theta_expr = f"np.array([{', '.join(f'theta[{i}]' for i in indices)}])"
264
+
265
+ # Hoist the compiled function
266
+ compiled_fn = Model._compiled_cache[model_hash]
267
+ fn_name = f"_compiled_{id(model)}"
268
+ self._hoisted_fns[fn_name] = compiled_fn
269
+
270
+ # Generate the call expression
271
+ expr = f"{fn_name}(x, None, {theta_expr})"
272
+
273
+ node = _IRNode(expr, frozenset()) # No INDEX deps
274
+ node.model = model
275
+ node.is_leaf = False
276
+ return self._cache(model, node)
277
+
278
+ # ------------------------------------------------------------------ #
279
+ # 1. DAG construction (common-sub-expression detection)
280
+ # ------------------------------------------------------------------ #
281
+ def _build_dag(self, model) -> _IRNode:
282
+ """Build the IR DAG by walking the Model tree.
283
+
284
+ Performs depth-first traversal, creating IR nodes and detecting
285
+ common subexpressions. Each unique Model gets a single IR node,
286
+ with ``users`` tracking reference counts.
287
+
288
+ Parameters
289
+ ----------
290
+ model : Model | Param | Any
291
+ The expression node to process.
292
+
293
+ Returns
294
+ -------
295
+ _IRNode
296
+ The IR node representing this expression.
297
+ """
298
+ if model in self._node_map:
299
+ node = self._node_map[model]
300
+ return node
301
+
302
+ # ----- LEAF CASES ------------------------------------------------
303
+ if isinstance(model, _Param):
304
+ if model.kind == _Param.theta:
305
+ idx = self._param_to_idx.get(model, -1)
306
+ node = _IRNode(f"theta[{idx}]", frozenset())
307
+ elif model is INPUT:
308
+ node = _IRNode("x", frozenset())
309
+ elif model.kind == _Param.index:
310
+ # Leaf that will be replaced by the loop variable.
311
+ var = self._idx_var(model)
312
+ node = _IRNode(var, frozenset({model})) # depends on its own index
313
+ node.is_leaf = True
314
+ return self._cache(model, node)
315
+ node.is_leaf = True
316
+ return self._cache(model, node)
317
+
318
+ if not isinstance(model, Model):
319
+ # constants / numpy arrays → hoist as const_<id>
320
+ if isinstance(model, np.ndarray):
321
+ cname = f"const_{id(model)}"
322
+ node = _IRNode(cname, frozenset())
323
+ self._hoisted_consts[cname] = model
324
+ else:
325
+ node = _IRNode(repr(model), frozenset())
326
+ node.is_leaf = True
327
+ return self._cache(model, node)
328
+
329
+ # ----- REUSE PRE-COMPILED SUB-MODEL ------------------------------
330
+ # Check if this sub-model is already compiled and can be reused
331
+ if isinstance(model, Model) and model is not self.root:
332
+ reuse_node = self._try_reuse_compiled(model)
333
+ if reuse_node is not None:
334
+ return reuse_node
335
+
336
+ # ----- REDUCTION -------------------------------------------------
337
+ if isinstance(model, Reduction):
338
+ if model.op is not operator.add:
339
+ raise ValueError("Only operator.add supported in Reduction")
340
+ sub_node = self._build_dag(model.model)
341
+ sub_node.users += 1 # reduction body uses it once per iter
342
+ idx = model.index
343
+ acc_name = f"_acc_{id(model)}"
344
+ red_node = _IRNode(sub_node.expr, frozenset({idx}))
345
+ red_node.is_red = (acc_name, "+")
346
+ red_node.model = model
347
+ # Accumulator itself is a zero-dep node (value after the loop)
348
+ acc_node = _IRNode(acc_name, frozenset())
349
+ acc_node.is_acc = True
350
+ return self._cache(model, acc_node, extra=[red_node])
351
+
352
+ # ----- GENERIC MODEL NODE ---------------------------------------
353
+ fn = model.fn
354
+
355
+ # recursively compile children first
356
+ args = [self._build_dag(a) for a in model.args]
357
+ # every time we reference a child, bump its user-count
358
+ for child in args:
359
+ child.users += 1
360
+
361
+ deps = frozenset().union(*(a.deps for a in args))
362
+ # build RHS string
363
+ fn_name = getattr(fn, "__name__", None)
364
+
365
+ # Handle const() specially - hoist the value directly
366
+ if fn_name == "const" and len(args) == 0:
367
+ val = fn() # Evaluate to get the constant value
368
+ if isinstance(val, np.ndarray):
369
+ cname = f"_arr_{id(val)}"
370
+ self._hoisted_consts[cname] = val
371
+ expr = cname
372
+ else:
373
+ expr = repr(val)
374
+ node = _IRNode(expr, frozenset())
375
+ node.is_leaf = True
376
+ return self._cache(model, node)
377
+
378
+ if fn_name in {"add","radd","sub","rsub","mul","rmul",
379
+ "div","rdiv","truediv",
380
+ "pow","rpow"} and len(args) == 2:
381
+ a, b = args
382
+ if fn_name.startswith("r"): # right-assoc helpers
383
+ a, b = b, a
384
+ op = {"add":"+","sub":"-","mul":"*","div":"/","truediv":"/",
385
+ "pow":"**"}[fn_name.replace("r","")]
386
+ expr = f"({a.expr} {op} {b.expr})"
387
+ elif fn_name == "neg" and len(args) == 1:
388
+ expr = f"-({args[0].expr})"
389
+ elif fn in {np.exp, np.sqrt, np.sum, np.dot} or fn_name in {
390
+ 'exp', 'sqrt', 'sum', 'dot', 'log', 'log10', 'log2',
391
+ 'sin', 'cos', 'tan', 'arcsin', 'arccos', 'arctan',
392
+ 'sinh', 'cosh', 'tanh', 'abs', 'absolute',
393
+ 'maximum', 'minimum', 'where', 'multiply', 'divide', 'add', 'subtract',
394
+ 'power', 'greater', 'less', 'greater_equal', 'less_equal', 'equal', 'not_equal',
395
+ 'gt', 'lt', 'ge', 'le', 'eq', 'ne', # comparison operator names
396
+ }:
397
+ # Map short names to numpy function names
398
+ np_name = {'gt': 'greater', 'lt': 'less', 'ge': 'greater_equal',
399
+ 'le': 'less_equal', 'eq': 'equal', 'ne': 'not_equal'}.get(fn_name, fn_name)
400
+ expr = f"np.{np_name}(" + ", ".join(a.expr for a in args) + ")"
401
+ elif fn_name == "_indecise" and len(args) == 2:
402
+ # _indecise(arr, idx) → arr[int(idx)] - direct array indexing
403
+ arr, idx = args
404
+ expr = f"({arr.expr})[int({idx.expr})]"
405
+ else:
406
+ # fallback: hoist callable into a helper
407
+ helper = self._hoist_fn(fn)
408
+ expr = f"{helper}(" + ", ".join(a.expr for a in args) + ")"
409
+
410
+ node = _IRNode(expr, deps)
411
+ node.model = model
412
+ node.is_leaf = False
413
+ return self._cache(model, node)
414
+
415
+ # ------------------------------------------------------------------ #
416
+ def _cache(self, model, node: _IRNode, extra=None):
417
+ """Insert node into map, bump users of children."""
418
+ self._node_map[model] = node
419
+ if extra: # reductions produce extra IR nodes
420
+ for e in extra:
421
+ self._globals.append(e) # added as globals for now
422
+ return node
423
+
424
+
425
+ # ------------------------------------------------------------------ #
426
+ # 2. Partition nodes into global vs loop buckets
427
+ # ------------------------------------------------------------------ #
428
+ def _partition_nodes(self) -> None:
429
+ """Partition IR nodes into global and loop-local buckets.
430
+
431
+ Nodes with no INDEX dependencies go to ``_globals``. Nodes that
432
+ depend on exactly one INDEX go to that loop's ``_LoopIR`` bucket.
433
+
434
+ Raises
435
+ ------
436
+ NotImplementedError
437
+ If a node depends on multiple INDEX parameters (nested loops).
438
+ """
439
+ # start fresh in case compile() is called twice
440
+ prev_globals = list(self._globals) # ← keep reduction bodies
441
+ self._globals = []
442
+ self._loops.clear()
443
+
444
+ # Collect *all* nodes (the DAG proper + reduction-body extras)
445
+ all_nodes = set(self._node_map.values()).union(prev_globals)
446
+
447
+ for node in all_nodes:
448
+ if not node.deps:
449
+ self._globals.append(node)
450
+ else:
451
+ if len(node.deps) > 1:
452
+ raise NotImplementedError("nested index loops not yet supported")
453
+ idx = next(iter(node.deps))
454
+ bucket = self._loops.setdefault(idx, _LoopIR(idx))
455
+ bucket.body.append(node)
456
+
457
+ # remember the IR node that represents the whole model
458
+ self._final = self._node_map[self.root]
459
+
460
+
461
+ # ------------------------------------------------------------------ #
462
+ # 3. Allocate temporaries (multi-use nodes get names)
463
+ # ------------------------------------------------------------------ #
464
+ def _allocate_temps(self) -> None:
465
+ """Assign temporary variable names to multi-use nodes.
466
+
467
+ Nodes referenced more than once get a ``_tN`` name to avoid
468
+ redundant computation. Leaf nodes and accumulator holders
469
+ are skipped.
470
+ """
471
+ t_counter = 0
472
+ all_nodes = itertools.chain(self._globals, *(b.body for b in self._loops.values()))
473
+ for node in all_nodes:
474
+ if (node.users >= 2 and
475
+ not getattr(node, "is_leaf", False) and
476
+ not getattr(node, "is_acc", False)) or node.is_red:
477
+ node.name = f"_t{t_counter}"
478
+ t_counter += 1
479
+
480
+
481
+ def _alias_rhs(self, rhs, alias_map):
482
+ """Replace any known sub-expression with its temp name.
483
+
484
+ Uses compiled regex for O(m) single-pass replacement instead of
485
+ O(m * p) sequential .replace() calls.
486
+ """
487
+ if not alias_map:
488
+ return rhs
489
+ # Compile pattern once and cache it
490
+ if self._alias_pattern is None or self._alias_map_id != id(alias_map):
491
+ # Sort by length (longest first) to match longer patterns first
492
+ sorted_aliases = sorted(alias_map.keys(), key=len, reverse=True)
493
+ pattern = '|'.join(re.escape(a) for a in sorted_aliases)
494
+ self._alias_pattern = re.compile(pattern)
495
+ self._alias_map_id = id(alias_map)
496
+ self._alias_map_ref = alias_map
497
+ return self._alias_pattern.sub(lambda m: alias_map[m.group(0)], rhs)
498
+
499
+ def _init_for_shape(self, obj, alias: dict) -> str:
500
+ """
501
+ Return the source-code string for an accumulator initialiser
502
+ corresponding to `shape_obj`, where
503
+ shape_obj == () -> "0.0"
504
+ shape_obj is tuple -> f"np.zeros({shape_obj})"
505
+ otherwise (Model) -> f"np.zeros_like({expr})"
506
+ """
507
+ shape_obj = obj.shape()
508
+ if shape_obj == ():
509
+ return "0.0"
510
+ if isinstance(shape_obj, tuple):
511
+ return f"np.zeros({shape_obj})"
512
+ # shape_obj is a Model (symbolic). Use its aliased expression
513
+ if shape_obj is INPUT:
514
+ return f"np.zeros_like(x, dtype=np.float64)"
515
+ raise ValueError(f"Cannot determine shape for {obj}")
516
+
517
+ # ------------------------------------------------------------------ #
518
+ # 4. Emit python source string
519
+ # ------------------------------------------------------------------ #
520
+ def _emit_source(self) -> tuple[str, dict]:
521
+ """Generate Python source code for the compiled function.
522
+
523
+ Produces a function definition string and a namespace dict
524
+ containing hoisted constants and helper functions.
525
+
526
+ Returns
527
+ -------
528
+ tuple[str, dict]
529
+ (source_code, namespace) ready for ``exec()`` and ``@njit``.
530
+ """
531
+ lines = ["def compiled(x, indices, theta):"]
532
+ ns = {"np": np}
533
+ ns.update(self._hoisted_fns)
534
+ ns.update(self._hoisted_consts)
535
+
536
+ # ---- globals ---------------------------------------------------
537
+ alias = {}
538
+ post_loop = [] # IR nodes that use any _acc_*
539
+ acc_names = {acc for b in self._loops.values()
540
+ for n in b.body if n.is_red
541
+ for acc, _ in (n.is_red,)}
542
+
543
+ for node in self._globals:
544
+ if getattr(node, "is_acc", False):
545
+ continue # accumulator holder
546
+ if any(a in node.expr for a in acc_names):
547
+ post_loop.append(node) # delay until after loop(s)
548
+ continue
549
+ if node.name:
550
+ rhs = self._alias_rhs(node.expr, alias)
551
+ lines.append(f" {node.name} = {rhs}")
552
+ alias[node.expr] = node.name
553
+
554
+ # ---- loops -----------------------------------------------------
555
+ for loop in self._loops.values():
556
+ idx = self._idx_var(loop.idx)
557
+ r = loop.idx.range
558
+ lines.append(f" # --- reduction over {idx} ---")
559
+
560
+ # initialisers
561
+ for n in loop.body:
562
+ if n.is_red:
563
+ acc, _ = n.is_red
564
+ # pick any rhs that gives the correct output shape
565
+ shape_obj = n.model # tuple, (), or Model
566
+ init = self._init_for_shape(shape_obj, alias)
567
+ lines.append(f" {acc} = {init}")
568
+
569
+ # -------- main loop ----------------------------------------
570
+ lines.append(f" for {idx} in range({r.start}, {r.stop}, {r.step}):")
571
+ for n in loop.body:
572
+ rhs = self._alias_rhs(n.expr, alias)
573
+ if n.name:
574
+ lines.append(f" {n.name} = {rhs}")
575
+ alias[n.expr] = n.name
576
+ src = n.name
577
+ else:
578
+ src = rhs
579
+ if n.is_red:
580
+ acc, op = n.is_red
581
+ lines.append(f" {acc} {op}= {src}")
582
+ lines.append("")
583
+
584
+ # ---- post-loop -------------------------------------------------
585
+ for node in post_loop:
586
+ rhs = self._alias_rhs(node.expr, alias)
587
+ if node.name:
588
+ lines.append(f" {node.name} = {rhs}")
589
+ alias[node.expr] = node.name
590
+
591
+ # ---- return ----------------------------------------------------
592
+ ret_expr = self._final.name or self._alias_rhs(self._final.expr, alias)
593
+ lines.append(f" return {ret_expr}")
594
+ lines.append("")
595
+ return "\n".join(lines), ns
596
+
597
+ # ------------------------------------------------------------------ #
598
+ # Helpers: hoist callables & numpy arrays
599
+ # ------------------------------------------------------------------ #
600
+ def _hoist_fn(self, fn) -> str:
601
+ """Hoist a callable into the generated namespace.
602
+
603
+ Wraps the function with ``@njit`` and stores it in the namespace
604
+ under a unique name for use in generated code.
605
+
606
+ Parameters
607
+ ----------
608
+ fn : callable
609
+ The function to hoist.
610
+
611
+ Returns
612
+ -------
613
+ str
614
+ The namespace key (e.g., ``_fn_0``) to reference this function.
615
+ """
616
+ # O(1) lookup using reverse index
617
+ fn_id = id(fn)
618
+ if fn_id in self._fn_to_name:
619
+ return self._fn_to_name[fn_id]
620
+ name = f"_fn_{len(self._hoisted_fns)}"
621
+ self._hoisted_fns[name] = njit(fn)
622
+ self._fn_to_name[fn_id] = name
623
+ return name
624
+
625
+ def _compile(self, eager: bool = True) -> Model:
626
+ """Compile this Model for fast evaluation using Numba.
627
+
628
+ Checks the global cache for an existing compiled function with
629
+ the same structure. If not found, compiles and caches the result.
630
+ Uses LRU eviction when the cache is full.
631
+
632
+ Parameters
633
+ ----------
634
+ eager : bool, default True
635
+ If True, trigger LLVM compilation immediately by calling the
636
+ function once. This makes the first real call fast but adds
637
+ upfront cost. Set to False for lazy JIT behavior.
638
+
639
+ Returns
640
+ -------
641
+ Model
642
+ Returns self (for method chaining).
643
+
644
+ Notes
645
+ -----
646
+ After compilation, ``model.code`` contains the generated source
647
+ and ``model.compiled`` returns True.
648
+ """
649
+ current_hash = hash(self) # Hash depends on symbolic structure
650
+ if current_hash not in Model._compiled_cache:
651
+ # Evict oldest entry if cache is full (LRU)
652
+ while len(Model._compiled_cache) >= Model._cache_limit:
653
+ Model._compiled_cache.popitem(last=False)
654
+ c = Compiler(self)
655
+ compiled_fn = c.compile()
656
+ Model._compiled_cache[current_hash] = compiled_fn
657
+ self.code = c.code
658
+
659
+ # Trigger LLVM compilation by calling once with dummy values
660
+ if eager:
661
+ params = self.params
662
+ theta = np.array([p.value for p in params]) if params else None
663
+
664
+ # Check if model needs INPUT
665
+ free = self.free
666
+ needs_input = any(p.kind == _Param.input for p in free)
667
+ x = np.array([0.0]) if needs_input else None
668
+
669
+ # Check for INDEX params
670
+ index_params = [p for p in free if p.kind == _Param.index]
671
+ indices = [0] * len(index_params) if index_params else None
672
+
673
+ try:
674
+ compiled_fn(x, indices, theta)
675
+ except Exception:
676
+ pass # Ignore errors during warmup (e.g., domain errors)
677
+
678
+ return self
679
+
680
+
681
+ Model.compile = _compile