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/model.py ADDED
@@ -0,0 +1,1372 @@
1
+ """model.py
2
+ =========
3
+ Representation of models in the library, also the main user interface
4
+ ----------------------------------------------------------
5
+
6
+ Define a model building on built in types or by using arithmetic with Params. For instance:
7
+
8
+ linear_model = Param('a') * Param.INPUT + Param('b')
9
+ gaussian_model = gaussian(Param('mu')(5,10)) # a gaussian model with a mu between 5 and 10 and a default sigma
10
+
11
+ We can also add models together:
12
+
13
+ composite_model = Param('n_gaussian') * gaussian_model + linear_model
14
+
15
+ To run a model, all you need to do is run __call__:
16
+
17
+ composite_model(0) or composite_model(ndarray)
18
+
19
+ You can also compile it with composite_model.compile(), after which any model with the same shape of operations will use a numba-compiled version
20
+
21
+
22
+ """
23
+ from __future__ import annotations
24
+
25
+ import numpy as np
26
+ from numba import njit, types
27
+ from numba.typed import Dict
28
+ import typing
29
+ from .param import Param, _Param, INPUT, INDEX, ParamKind
30
+ from collections.abc import Iterable, Callable
31
+ from collections import defaultdict, OrderedDict
32
+ import operator
33
+ import functools
34
+ from typing import Any
35
+ from numpy.typing import NDArray
36
+ import copy as _copy
37
+
38
+
39
+ __all__ = [
40
+ "Model",
41
+ "_indecise",
42
+ "identity",
43
+ "model_sum",
44
+ "vector",
45
+ "formula",
46
+ ]
47
+
48
+ class Model:
49
+ """Represents a function that returns an output from INPUT, THETA parameters, and sometimes INDEX's.
50
+
51
+ Parameters
52
+ ----------
53
+ fn : function
54
+ A function that takes in input scalars and returns an output
55
+ args : list
56
+ A list of parameters that correspond to the scalars of the input of fn.
57
+ memory : dictionary
58
+ Acted on by other classes, for now just so that a cost function knows what its based on.
59
+
60
+ """
61
+ _compiled_cache = OrderedDict() # LRU cache for compiled functions
62
+ _cache_limit = 128
63
+
64
+ @classmethod
65
+ def clear_cache(cls):
66
+ """Clear the compiled function cache to free memory."""
67
+ cls._compiled_cache.clear()
68
+
69
+ @classmethod
70
+ def cache_info(cls):
71
+ """Return info about the compilation cache."""
72
+ return {"size": len(cls._compiled_cache), "limit": cls._cache_limit}
73
+
74
+ @property
75
+ def compiled(self) -> bool:
76
+ """Return True if this Model has a compiled numba function in the cache."""
77
+ return hash(self) in Model._compiled_cache
78
+
79
+ def __init__(self, fn, args):
80
+ self.fn = fn
81
+ self.args = args
82
+ self.memory = {}
83
+
84
+ def __array_ufunc__(self, ufunc, method, *inputs, **ufunc_kwargs):
85
+ """Handle numpy ufuncs like np.exp, np.sin, np.add, etc."""
86
+ if method != '__call__':
87
+ return NotImplemented
88
+
89
+ # Numba can't handle **kwargs - only include if non-empty
90
+ if ufunc_kwargs:
91
+ def inner(*inner_args):
92
+ return ufunc(*inner_args, **ufunc_kwargs)
93
+ inner._has_kwargs = True
94
+ inner._kwargs_info = tuple(ufunc_kwargs.keys())
95
+ else:
96
+ def inner(*inner_args):
97
+ return ufunc(*inner_args)
98
+ inner.__name__ = ufunc.__name__
99
+ return Model(inner, list(inputs))
100
+
101
+ def __array_function__(self, func, types, args, kwargs):
102
+ """Handle numpy functions like np.dot, np.matmul, np.sum, etc."""
103
+ # Numba can't handle **kwargs - only include if non-empty
104
+ if kwargs:
105
+ def inner(*inner_args):
106
+ return func(*inner_args, **kwargs)
107
+ inner._has_kwargs = True
108
+ inner._kwargs_info = tuple(kwargs.keys())
109
+ else:
110
+ def inner(*inner_args):
111
+ return func(*inner_args)
112
+ inner.__name__ = func.__name__
113
+ return Model(inner, list(args))
114
+
115
+ # for selecting models in trees
116
+ @property
117
+ def components(self):
118
+ """
119
+ Return a 1D list of components obtained by walking the tree
120
+ and cutting at nodes with fn == iden.
121
+
122
+ - Traverse the expression tree depth-first.
123
+ - Whenever we see a Model with fn is iden, we treat its *inner*
124
+ expression as a single component and do not recurse further.
125
+ - If there are no iden boundaries at all, return [self].
126
+ """
127
+ comps = []
128
+
129
+ def walk(node):
130
+ # Only care about Model nodes structurally
131
+ if not isinstance(node, Model):
132
+ return
133
+
134
+ # If this is a boundary: stop and record the inner expression
135
+ if node.fn is iden or getattr(node.fn, "__name__", "") == "iden":
136
+ if node.args:
137
+ comps.append(node.args[0])
138
+ else:
139
+ comps.append(node)
140
+ return
141
+
142
+ # Otherwise recurse into children
143
+ for a in node.args:
144
+ walk(a)
145
+
146
+ walk(self)
147
+
148
+ # If no iden nodes found, the whole model is a single component
149
+ return comps or [self]
150
+
151
+ @property
152
+ def params(self):
153
+ """A list of all the THETA params that act on the model.
154
+ """
155
+ # Return cached params if available (models are effectively immutable)
156
+ if hasattr(self, '_cached_params'):
157
+ return self._cached_params
158
+
159
+ flat = []
160
+ seen = set()
161
+
162
+ def walk(m):
163
+ if isinstance(m, Model):
164
+ for arg in m.args:
165
+ walk(arg)
166
+ elif isinstance(m, Iterable) and not isinstance(m, (str, bytes, np.ndarray)):
167
+ for item in m:
168
+ walk(item)
169
+ elif isinstance(m, (int, float, np.number)):
170
+ return
171
+ elif isinstance(m, _Param) and m.kind not in (_Param.input, _Param.index):
172
+ if m not in seen:
173
+ seen.add(m)
174
+ flat.append(m)
175
+
176
+ walk(self)
177
+ self._cached_params = flat
178
+ return flat
179
+
180
+ @property
181
+ def free(self):
182
+ """A list of all the free params, which are INPUT and INDEX that act on the model.
183
+ """
184
+ # Return cached free params if available (models are effectively immutable)
185
+ if hasattr(self, '_cached_free'):
186
+ return self._cached_free
187
+
188
+ flat = []
189
+ seen = set()
190
+
191
+ def walk(m):
192
+ if isinstance(m, Model):
193
+ if m is not self:
194
+ for f in m.free:
195
+ if f not in seen:
196
+ seen.add(f)
197
+ flat.append(f)
198
+ else:
199
+ for arg in m.args:
200
+ walk(arg)
201
+ elif isinstance(m, Iterable) and not isinstance(m, (str, bytes, np.ndarray)):
202
+ for item in m:
203
+ walk(item)
204
+ elif isinstance(m, (int, float, np.number)):
205
+ return
206
+ elif isinstance(m, _Param) and m.kind in (_Param.input, _Param.index):
207
+ if m not in seen:
208
+ seen.add(m)
209
+ flat.append(m)
210
+
211
+ walk(self)
212
+ self._cached_free = flat
213
+ return flat
214
+
215
+ def __hash__(self):
216
+ """Two equal-hashed models may have different parameters, but if you use the same scalars for those parameters, they will give the same output.
217
+ """
218
+ # Return cached hash if available (models are effectively immutable)
219
+ if hasattr(self, '_cached_hash'):
220
+ return self._cached_hash
221
+
222
+ def walk(m):
223
+ if isinstance(m, _Param):
224
+ return ("param", m.kind)
225
+ elif isinstance(m, Reduction):
226
+ return ("reduce", walk(m.model), hash(m.index), m.op.__name__)
227
+ elif isinstance(m, Model):
228
+ fn = m.fn
229
+
230
+ # --- special case: zero-arg const() ---
231
+ if not m.args and getattr(fn, "__name__", "") == "const":
232
+ val = fn()
233
+ if isinstance(val, np.ndarray):
234
+ return ("const_array", val.shape, val.dtype.str, tuple(val.flatten().tolist()))
235
+ else:
236
+ return ("const_scalar", val)
237
+
238
+ # --- otherwise: normal Model node ---
239
+ def _fn_key(f):
240
+ # Prefer __name__ since named() sets it explicitly
241
+ if hasattr(f, "__name__"):
242
+ if hasattr(f, "__module__"):
243
+ return (f.__module__, f.__name__)
244
+ return f.__name__
245
+ if hasattr(f, "__qualname__"):
246
+ return (f.__module__, f.__qualname__)
247
+ return repr(f)
248
+
249
+ return ("model", _fn_key(fn), tuple(walk(arg) for arg in m.args))
250
+ elif isinstance(m, np.ndarray):
251
+ return ("ndarray", m.shape, m.dtype.str, tuple(m.flatten().tolist()))
252
+ elif isinstance(m, (list, tuple)):
253
+ return (type(m).__name__, tuple(walk(x) for x in m))
254
+ else:
255
+ try:
256
+ hash(m)
257
+ return ("const", m)
258
+ except TypeError:
259
+ return ("unhashable", type(m).__name__)
260
+ self._cached_hash = hash(walk(self))
261
+ return self._cached_hash
262
+
263
+ def __eq__(self, other):
264
+ if self is other:
265
+ return True
266
+ if not isinstance(other, Model):
267
+ return False
268
+
269
+ def walk(a, b):
270
+ if isinstance(a, _Param) and isinstance(b, _Param):
271
+ if a.kind != b.kind:
272
+ return False
273
+ if a.kind != _Param.input:
274
+ return a is b
275
+ else:
276
+ return True
277
+ if isinstance(a, Reduction) and isinstance(b, Reduction):
278
+ return (a.index == b.index and
279
+ a.op is b.op and
280
+ walk(a.model, b.model))
281
+ if isinstance(a, Model) and isinstance(b, Model):
282
+ fn_a = getattr(a.fn, "__name__", repr(a.fn))
283
+ fn_b = getattr(b.fn, "__name__", repr(b.fn))
284
+ if fn_a != fn_b or len(a.args) != len(b.args):
285
+ return False
286
+ return all(walk(x, y) for x, y in zip(a.args, b.args))
287
+ if isinstance(a, np.ndarray) and isinstance(b, np.ndarray):
288
+ return (a.shape == b.shape and
289
+ a.dtype == b.dtype and
290
+ np.array_equal(a, b))
291
+ if isinstance(a, (list, tuple)) and isinstance(b, (list, tuple)):
292
+ return (type(a) is type(b) and
293
+ len(a) == len(b) and
294
+ all(walk(x, y) for x, y in zip(a, b)))
295
+ return a == b
296
+
297
+ return walk(self, other)
298
+
299
+ def eval_py(self, x: NDArray[np.floating] | None, index_map: dict[_Param, int]) -> Any:
300
+ """Evaluate the model using pure Python (no Numba).
301
+
302
+ Recursively evaluates the expression tree by calling each
303
+ function node with its evaluated arguments.
304
+
305
+ Parameters
306
+ ----------
307
+ x : ndarray | None
308
+ Input data array, or None if the model has no INPUT dependency.
309
+ index_map : dict[_Param, int]
310
+ Mapping from INDEX parameters to their current integer values.
311
+
312
+ Returns
313
+ -------
314
+ Any
315
+ The evaluated result (typically ndarray or scalar).
316
+ """
317
+ import warnings
318
+
319
+ # Collect warnings with their model context
320
+ collected_warnings = []
321
+ seen_base_messages = set()
322
+
323
+ def _eval(m):
324
+ if isinstance(m, Reduction):
325
+ index = m.index
326
+ bound = index.range
327
+ return functools.reduce(
328
+ m.op,
329
+ [_eval(m.model % {index: i}) for i in bound]
330
+ )
331
+
332
+ if isinstance(m, Model):
333
+ # Capture numpy warnings and add model context
334
+ with warnings.catch_warnings(record=True) as caught:
335
+ warnings.simplefilter("always")
336
+ result = m.fn(*[_eval(arg) for arg in m.args])
337
+
338
+ for w in caught:
339
+ base_msg = str(w.message).split("\n")[0]
340
+ # Only keep the first occurrence (innermost expression)
341
+ if base_msg not in seen_base_messages:
342
+ seen_base_messages.add(base_msg)
343
+ collected_warnings.append((base_msg, m, w.category))
344
+
345
+ return result
346
+ if isinstance(m, _Param):
347
+ if m.kind == _Param.theta:
348
+ return m.value
349
+ if m.kind == _Param.input:
350
+ return x
351
+ if m.kind == _Param.index:
352
+ return index_map[m]
353
+ raise ValueError(
354
+ f"Unknown parameter kind: {m.kind!r}.\n"
355
+ f" Expected: _Param.theta, _Param.input, or _Param.index.\n"
356
+ f" This usually indicates a corrupted Param object."
357
+ )
358
+ return m
359
+
360
+ result = _eval(self)
361
+
362
+ # Emit all collected warnings after evaluation completes
363
+ for base_msg, model_expr, category in collected_warnings:
364
+ msg = f"{base_msg}\n In expression: {model_expr}"
365
+ warnings.warn(msg, category, stacklevel=4)
366
+
367
+ return result
368
+
369
+ def eval(self, x: NDArray[np.floating] | None, index_map: dict[_Param, int], numba: bool = False) -> Any:
370
+ """Evaluate the model, using compiled code if available.
371
+
372
+ Checks the compilation cache for a Numba-compiled version of this
373
+ model's structure. If found, uses the fast compiled path; otherwise
374
+ falls back to Python evaluation.
375
+
376
+ Parameters
377
+ ----------
378
+ x : ndarray | None
379
+ Input data array, or None if the model has no INPUT dependency.
380
+ index_map : dict[_Param, int]
381
+ Mapping from INDEX parameters to their current integer values.
382
+ numba : bool, default False
383
+ If True, raises an error when no compiled function is available.
384
+
385
+ Returns
386
+ -------
387
+ Any
388
+ The evaluated result (typically ndarray or scalar).
389
+
390
+ Raises
391
+ ------
392
+ AttributeError
393
+ If ``numba=True`` and no compiled function exists in cache.
394
+ """
395
+ if not self.params:
396
+ theta = None
397
+ else:
398
+ theta = np.array([p.value for p in self.params])
399
+
400
+ index_params = [p for p in self.free if p.kind == _Param.index]
401
+ index_list = [index_map[p] for p in index_params] if index_params else None
402
+
403
+ current_hash = hash(self) # Hash depends on symbolic structure
404
+ if current_hash in Model._compiled_cache:
405
+ return Model._compiled_cache[current_hash](x, index_list, theta)
406
+ else:
407
+ if numba:
408
+ raise AttributeError("No compiled function in cache")
409
+ return self.eval_py(x, index_map)
410
+
411
+ def __call__(self, x: NDArray[np.floating] | _Param | Model | None = None) -> Any:
412
+ """Evaluate the model or perform substitution.
413
+
414
+ The behavior depends on the argument type:
415
+ - If ``x`` is a Param or Model, performs substitution (same as ``%``).
416
+ - If ``x`` is array-like, evaluates the model with that input data.
417
+ - If ``x`` is None, evaluates a model with no INPUT dependency.
418
+
419
+ Parameters
420
+ ----------
421
+ x : ndarray | _Param | Model | None, optional
422
+ Input data for evaluation, or a Param/Model for substitution.
423
+
424
+ Returns
425
+ -------
426
+ Any
427
+ Evaluation result (ndarray/scalar) or substituted Model.
428
+
429
+ Raises
430
+ ------
431
+ TypeError
432
+ If the model requires INPUT but none provided, or vice versa.
433
+
434
+ Examples
435
+ --------
436
+ >>> model = Param("a") * INPUT
437
+ >>> model(np.array([1, 2, 3])) # Evaluate
438
+ >>> model(other_param) # Substitute (same as model % other_param)
439
+ """
440
+ # If x is a Param/Model, treat as substitution, not evaluation
441
+ if isinstance(x, (_Param, Model)):
442
+ return self % x
443
+ if x is not None and not isinstance(x, np.ndarray):
444
+ x = np.asarray(x)
445
+ # For cost models with preserved INPUT, use stored data if x not provided
446
+ if INPUT in self.free and x is None:
447
+ if '_eval_x' in self.memory:
448
+ x = self.memory['_eval_x']
449
+ else:
450
+ raise TypeError(
451
+ f"Model requires input data but none provided.\n"
452
+ f" Call as: model(x) where x is your data array.\n"
453
+ f" Model: {self}"
454
+ )
455
+ if INPUT not in self.free and x is not None:
456
+ raise TypeError(
457
+ f"Model doesn't accept input data.\n"
458
+ f" This model has no INPUT dependency, call as: model()\n"
459
+ f" Model: {self}"
460
+ )
461
+ if not self.free:
462
+ return self.eval(None, {})
463
+ if self.free == [INPUT]:
464
+ return self.eval(x, {})
465
+ else:
466
+ return self % x
467
+ def __getitem__(self, key: dict | int | _Param) -> Any:
468
+ """Access model values by index or make model indexable.
469
+
470
+ Provides convenient syntax for working with INDEX parameters:
471
+ - ``model[index_param]``: Make model indexable by that INDEX param
472
+ - ``model[2]``: If model has no INDEX, wrap and evaluate at index 2
473
+ - ``model[{idx: 5}]``: Substitute specific index param with value
474
+
475
+ Parameters
476
+ ----------
477
+ key : dict | int | _Param
478
+ An INDEX parameter, an integer index value, or a dictionary
479
+ mapping INDEX params to values.
480
+
481
+ Returns
482
+ -------
483
+ Model | Any
484
+ A Model if INPUT is present or wrapping in _indecise,
485
+ otherwise the evaluated result.
486
+
487
+ Examples
488
+ --------
489
+ >>> arr = const([10, 20, 30])
490
+ >>> arr[INDEX] # Make indexable by INDEX
491
+ >>> arr[1] # Get element 1 (implicitly wraps in _indecise)
492
+ >>> indexed_model[{my_index: 5}] # Substitute specific index
493
+ """
494
+ # If key is an INDEX param, wrap in _indecise
495
+ if isinstance(key, _Param) and key.kind is ParamKind.INDEX:
496
+ return _indecise(self, key)
497
+
498
+ # Check if model already has INDEX dependencies
499
+ has_index = any(
500
+ isinstance(p, _Param) and p.kind is ParamKind.INDEX
501
+ for p in self.free
502
+ )
503
+
504
+ if isinstance(key, int) and not has_index:
505
+ # No INDEX params - wrap in _indecise with global INDEX first
506
+ indexed = _indecise(self, INDEX)
507
+ if INPUT in indexed.free:
508
+ return indexed % {INDEX: key}
509
+ return indexed.eval(None, {INDEX: key})
510
+
511
+ # Current behavior: substitute INDEX
512
+ if INPUT in self.free:
513
+ if not isinstance(key, dict):
514
+ return self % {INDEX: key}
515
+ return self % key
516
+ if not isinstance(key, dict):
517
+ return self.eval(None, {INDEX: key})
518
+ return self.eval(None, key)
519
+
520
+ def copy_with_args(self, args: list) -> Model:
521
+ """Create a shallow copy of this Model with new arguments.
522
+
523
+ Parameters
524
+ ----------
525
+ args : list
526
+ New argument list to use instead of the current args.
527
+
528
+ Returns
529
+ -------
530
+ Model
531
+ A new Model with the same function but different arguments.
532
+ """
533
+ return type(self)(self.fn, args)
534
+
535
+ def copy(self) -> Model:
536
+ """Create a deep copy of the model expression tree.
537
+
538
+ Creates a new Model with:
539
+ - All Model/Reduction nodes recreated as new instances
540
+ - THETA Params cloned into new Param instances (preserving values)
541
+ - INPUT/INDEX Params shared (same singletons)
542
+ - Lists/tuples inside args recursively copied
543
+
544
+ Returns
545
+ -------
546
+ Model
547
+ A deep copy of this model with independent THETA parameters.
548
+ """
549
+ model_memo = {}
550
+ param_memo = {}
551
+
552
+ def walk(node):
553
+ # --- Models (including Reduction via copy_with_args) ---
554
+ if isinstance(node, Model):
555
+ obj_id = id(node)
556
+ if obj_id in model_memo:
557
+ return model_memo[obj_id]
558
+
559
+ new_args = [walk(a) for a in node.args]
560
+ new_node = node.copy_with_args(new_args)
561
+ model_memo[obj_id] = new_node
562
+ return new_node
563
+
564
+ # --- Params ---
565
+ if isinstance(node, _Param):
566
+ # Keep INPUT/INDEX singletons shared
567
+ if node.kind in (_Param.input, _Param.index):
568
+ return node
569
+
570
+ # Clone θ-params, reusing mapping so they stay consistent
571
+ if node in param_memo:
572
+ return param_memo[node]
573
+
574
+ new_p = _copy.copy(node) # new Param instance, same attributes
575
+ param_memo[node] = new_p
576
+ return new_p
577
+
578
+ # --- Lists / tuples inside args ---
579
+ if isinstance(node, (list, tuple)):
580
+ return type(node)(walk(a) for a in node)
581
+
582
+ # --- Scalars, ndarrays, etc. ---
583
+ return node
584
+
585
+ return walk(self)
586
+
587
+
588
+ def __mod__(self, subs: dict | Any) -> Model:
589
+ """Substitute parameters or sub-expressions in this model.
590
+
591
+ The ``%`` operator performs symbolic substitution, replacing
592
+ occurrences of specified parameters or models with new values.
593
+
594
+ Parameters
595
+ ----------
596
+ subs : dict | Any
597
+ Either a dictionary mapping old nodes to new values, or a
598
+ single value to substitute for INPUT.
599
+
600
+ Returns
601
+ -------
602
+ Model
603
+ A new Model with substitutions applied.
604
+
605
+ Examples
606
+ --------
607
+ >>> model = Param("a") * INPUT + Param("b")
608
+ >>> model % 5 # Substitute INPUT with 5
609
+ >>> model % {INPUT: x_data} # Same as above
610
+ >>> model % {some_param: 2.0} # Fix a parameter to a constant
611
+ """
612
+ if not isinstance(subs, dict):
613
+ subs = {INPUT: subs}
614
+
615
+ def walk(m):
616
+ # 1) If this node is exactly one of the keys, replace it wholesale
617
+ if m in subs:
618
+ return subs[m]
619
+
620
+ # 2) Otherwise recurse structurally
621
+ if isinstance(m, Model):
622
+ return m.copy_with_args([walk(a) for a in m.args])
623
+
624
+ elif isinstance(m, Iterable) and not isinstance(m, (str, bytes, np.ndarray)):
625
+ return type(m)(walk(x) for x in m)
626
+
627
+ # 3) Fallback: leave as is
628
+ return m
629
+
630
+ return walk(self)
631
+
632
+
633
+
634
+
635
+ #REPRESENTATION
636
+
637
+ def __repr__(self):
638
+ #fn_name = getattr(self.fn, '__name__', 'λ')
639
+ #if fn_name == '<lambda>':
640
+ # fn_name = 'λ'
641
+ #arg_strs = [repr(arg) for arg in self.args]
642
+ #return f"Model<{fn_name}>({', '.join(arg_strs)})"
643
+ return self._format()
644
+
645
+ def __str__(self):
646
+ return self._format()
647
+
648
+ def _format(self, parent_prec: int = 0, side: str | None = None) -> str:
649
+ """Format the model as a human-readable expression string.
650
+
651
+ Recursively formats the expression tree with proper operator
652
+ precedence and parenthesization.
653
+
654
+ Parameters
655
+ ----------
656
+ parent_prec : int, default 0
657
+ Precedence level of the parent expression (for parentheses).
658
+ side : str | None, default None
659
+ Which side of a binary op this is ('left' or 'right').
660
+
661
+ Returns
662
+ -------
663
+ str
664
+ A formatted string representation of the model.
665
+ """
666
+ if isinstance(self, Reduction):
667
+ inner = self.model._format() if isinstance(self.model, Model) else str(self.model)
668
+ return f"{self.op.__name__}_reduce({inner}, index={self.index})"
669
+ fn_name = getattr(self.fn, '__name__', 'λ')
670
+ if fn_name == '<lambda>':
671
+ fn_name = 'λ'
672
+
673
+ op_info = {
674
+ 'add': ('+', 1, 'left'),
675
+ 'radd': ('+', 1, 'left'),
676
+ 'sub': ('-', 1, 'left'),
677
+ 'rsub': ('-', 1, 'left'),
678
+ 'mul': ('*', 2, 'left'),
679
+ 'rmul': ('*', 2, 'left'),
680
+ 'div': ('/', 2, 'left'),
681
+ 'rdiv': ('/', 2, 'left'),
682
+ 'pow': ('**', 3, 'right'),
683
+ 'rpow': ('**', 3, 'right'),
684
+ 'eq': ('==', 0, 'left'),
685
+ 'ne': ('!=', 0, 'left'),
686
+ 'lt': ('<', 0, 'left'),
687
+ 'le': ('<=', 0, 'left'),
688
+ 'gt': ('>', 0, 'left'),
689
+ 'ge': ('>=', 0, 'left'),
690
+ }
691
+
692
+ def parens_needed(p_prec, p_assoc, c_prec, is_left):
693
+ if c_prec < p_prec:
694
+ return True
695
+ if c_prec > p_prec:
696
+ return False
697
+ if p_assoc == 'left' and not is_left:
698
+ return True
699
+ if p_assoc == 'right' and is_left:
700
+ return True
701
+ return False
702
+
703
+ def get_prec(m):
704
+ """Return precedence for formatting a Model node."""
705
+ if isinstance(m, Model):
706
+ fn_name = getattr(m.fn, "__name__", "")
707
+ if fn_name == "const":
708
+ return 100 # const literals are atomic
709
+ if fn_name not in op_info:
710
+ return 100 # function calls (sum, exp, log, etc.) are atomic
711
+ return op_info[fn_name][1]
712
+ return 100 # numbers, arrays, etc. are atomic
713
+
714
+ if fn_name in op_info and len(self.args) == 2:
715
+ op, prec, assoc = op_info[fn_name]
716
+ if fn_name.startswith('r'):
717
+ right, left = self.args
718
+ else:
719
+ left, right = self.args
720
+
721
+ if isinstance(left, Model):
722
+ lstr = left._format(prec, 'left')
723
+ else:
724
+ lstr = str(left)
725
+ if isinstance(right, Model):
726
+ rstr = right._format(prec, 'right')
727
+ else:
728
+ rstr = str(right)
729
+
730
+ if isinstance(left, Model):
731
+ if parens_needed(prec, assoc, get_prec(left), True):
732
+ lstr = f'({lstr})'
733
+ if isinstance(right, Model):
734
+ if parens_needed(prec, assoc, get_prec(right), False):
735
+ rstr = f'({rstr})'
736
+
737
+ return f"{lstr} {op} {rstr}"
738
+
739
+ elif fn_name == 'neg' and len(self.args) == 1:
740
+ arg = self.args[0]
741
+ astr = arg._format(4) if isinstance(arg, Model) else str(arg)
742
+ return f"-{astr}"
743
+
744
+ elif fn_name == 'const' and len(self.args) == 0:
745
+ try:
746
+ val = self.fn()
747
+ except Exception:
748
+ return "const(?)"
749
+ if isinstance(val, np.ndarray):
750
+ # Show small arrays fully, large arrays with first/last elements
751
+ if val.size <= 6:
752
+ return f"{val}"
753
+ elif val.ndim == 1:
754
+ return f"[{val[0]:.4g}, {val[1]:.4g}, ..., {val[-2]:.4g}, {val[-1]:.4g}]"
755
+ else:
756
+ return f"const(array, shape={val.shape}, dtype={val.dtype})"
757
+ else:
758
+ return f"{val!r}"
759
+
760
+ # generic case
761
+
762
+ arg_strs = [arg._format() if isinstance(arg, Model) else str(arg) for arg in self.args]
763
+ return f"{fn_name}({', '.join(arg_strs)})"
764
+
765
+ def freeze(self) -> Model:
766
+ """Replace all THETA parameters with their current values.
767
+
768
+ Creates a new Model where every optimizable parameter is
769
+ substituted with its current numeric value, effectively
770
+ "freezing" the model at its current parameter state.
771
+
772
+ Returns
773
+ -------
774
+ Model
775
+ A new Model with all parameters replaced by constants.
776
+
777
+ Examples
778
+ --------
779
+ >>> fitted_model.freeze() # Lock in fitted parameter values
780
+ """
781
+ return self % {p : p.value for p in self.params}
782
+
783
+ # Operations
784
+
785
+ def named(fn, name):
786
+ fn.__name__ = name
787
+ return fn
788
+
789
+ _op_map = {
790
+ '__add__': named(lambda a, b: a + b, 'add'),
791
+ '__radd__': named(lambda a, b: b + a, 'radd'),
792
+ '__sub__': named(lambda a, b: a - b, 'sub'),
793
+ '__rsub__': named(lambda a, b: b - a, 'rsub'),
794
+ '__mul__': named(lambda a, b: a * b, 'mul'),
795
+ '__rmul__': named(lambda a, b: b * a, 'rmul'),
796
+ '__truediv__': named(lambda a, b: a / b, 'div'),
797
+ '__rtruediv__': named(lambda a, b: b / a, 'rdiv'),
798
+ '__pow__': named(lambda a, b: a ** b, 'pow'),
799
+ '__rpow__': named(lambda a, b: b ** a, 'rpow'),
800
+ '__neg__': named(lambda a: -a, 'neg'),
801
+ #DO NOT UNCOMMENT '__eq__': named(lambda a, b: a == b, 'eq'),
802
+ '__ne__': named(lambda a, b: a != b, 'ne'),
803
+ '__lt__': named(lambda a, b: a < b, 'lt'),
804
+ '__le__': named(lambda a, b: a <= b, 'le'),
805
+ '__gt__': named(lambda a, b: a > b, 'gt'),
806
+ '__ge__': named(lambda a, b: a >= b, 'ge'),
807
+ }
808
+
809
+ def bind_ops(cls):
810
+ for name, fn in _op_map.items():
811
+ def op_method(self, other=None, fn=fn):
812
+ if other is None:
813
+ return Model(fn, [self])
814
+ if not isinstance(other, typing.Hashable):
815
+ other = const(other)
816
+ return Model(fn, [self, other])# if 'r' not in name else Model(fn, [other, self])
817
+ setattr(cls, name, op_method)
818
+
819
+ bind_ops(Model)
820
+ bind_ops(_Param)
821
+
822
+
823
+ # Reduction
824
+
825
+ class Reduction(Model):
826
+ """A Model that reduces over an INDEX parameter using an operator.
827
+
828
+ Represents a summation (or other reduction) over a loop variable,
829
+ e.g., ``sum_{i=0}^{n} f(i)``. Currently only ``operator.add`` is
830
+ supported for Numba compilation.
831
+
832
+ Parameters
833
+ ----------
834
+ model : Model
835
+ The expression to reduce over.
836
+ index_param : Param
837
+ An INDEX parameter with a ``range`` attribute defining the
838
+ iteration bounds.
839
+ op : callable, default operator.add
840
+ The reduction operator. Must be ``operator.add``.
841
+
842
+ Attributes
843
+ ----------
844
+ model : Model
845
+ The inner expression being reduced.
846
+ index : Param
847
+ The INDEX parameter controlling the loop.
848
+ op : callable
849
+ The reduction operator.
850
+
851
+ Examples
852
+ --------
853
+ >>> i = index(10) # Loop from 0 to 9
854
+ >>> weights = _indecise(const([...]), i)
855
+ >>> total = Reduction(weights * some_model, i) # Sum over i
856
+ """
857
+ _supported_ops = {operator.add: 'add'} # Only add is supported by compiler
858
+
859
+ def __init__(self, model: Model, index_param: _Param, op: Callable = operator.add):
860
+ if not isinstance(index_param, _Param):
861
+ raise TypeError("Reduction index must be a Param")
862
+ if op not in Reduction._supported_ops:
863
+ raise ValueError(
864
+ f"Reduction only supports operator.add, got {op.__name__}.\n"
865
+ f" For products, use: exp(Reduction(log(model), index))"
866
+ )
867
+ self.model = model
868
+ self.index = index_param
869
+ self.op = op
870
+ super().__init__(op, [model])
871
+
872
+ @property
873
+ def params(self):
874
+ return self.model.params
875
+
876
+ @property
877
+ def free(self):
878
+ return [p for p in self.model.free if p is not self.index]
879
+
880
+ def copy_with_args(self, args):
881
+ return Reduction(args[0], self.index, self.op)
882
+
883
+ def __repr__(self):
884
+ op_name = getattr(self.op, '__name__', 'λ')
885
+ if op_name == '<lambda>':
886
+ op_name = 'λ'
887
+ return f"Reduce<{op_name}>({repr(self.model)}, index={self.index})"
888
+
889
+ def __str__(self):
890
+ op_name = getattr(self.op, '__name__', 'λ')
891
+ if op_name == '<lambda>':
892
+ op_name = 'λ'
893
+ return f"{op_name}_reduce({str(self.model)}, index={self.index})"
894
+
895
+
896
+ # Useful methods
897
+
898
+ def const(val: Any) -> Model:
899
+ """Wrap a constant value as a Model node.
900
+
901
+ Creates a Model that always returns the given constant value
902
+ when evaluated. Useful for embedding literal values in
903
+ expression trees.
904
+
905
+ Parameters
906
+ ----------
907
+ val : Any
908
+ The constant value to wrap (scalar, array, etc.).
909
+
910
+ Returns
911
+ -------
912
+ Model
913
+ A Model node that evaluates to the constant value.
914
+
915
+ Examples
916
+ --------
917
+ >>> c = const(5.0)
918
+ >>> c()
919
+ 5.0
920
+ >>> arr = const(np.array([1, 2, 3]))
921
+ """
922
+ # Convert lists/tuples to arrays for consistency and hashability
923
+ if isinstance(val, (list, tuple)):
924
+ val = np.asarray(val)
925
+ f = lambda val=val: val
926
+ f.__name__ = f"const"
927
+ return Model(f, [])
928
+
929
+ def _indecise(obj: Any, index: _Param = INDEX) -> Model:
930
+ """Create a Model that selects from an array by index.
931
+
932
+ Wraps an array (or constant) so that it can be indexed by
933
+ an INDEX parameter, enabling iteration over array elements
934
+ in reductions.
935
+
936
+ Parameters
937
+ ----------
938
+ obj : Any
939
+ The array or constant to index into.
940
+ index : Param, default INDEX
941
+ The INDEX parameter to use for selection.
942
+
943
+ Returns
944
+ -------
945
+ Model
946
+ A Model that evaluates to ``obj[index]``.
947
+
948
+ Examples
949
+ --------
950
+ >>> weights = _indecise(const([0.3, 0.5, 0.2]), i)
951
+ >>> Reduction(weights * some_model, i) # Sum weighted models
952
+ """
953
+ if not isinstance(obj, typing.Hashable):
954
+ obj = const(obj)
955
+ fn = lambda arr, i: arr[int(i)]
956
+ fn.__name__ = '_indecise'
957
+ return Model(fn, [obj, index])
958
+
959
+
960
+
961
+ # gradient
962
+
963
+ def _zero(): return 0
964
+ def _one(): return 1
965
+
966
+ def _grad_fn(model: Model | _Param | Any, wrt: _Param) -> Model | int:
967
+ """Compute the symbolic gradient of a model w.r.t. a parameter.
968
+
969
+ Recursively applies differentiation rules to build a new Model
970
+ representing the derivative. Supports standard arithmetic operations,
971
+ exp, log, sqrt, sum, where, and _indecise.
972
+
973
+ Parameters
974
+ ----------
975
+ model : Model | _Param | Any
976
+ The expression to differentiate.
977
+ wrt : Param
978
+ The parameter to differentiate with respect to.
979
+
980
+ Returns
981
+ -------
982
+ Model | int
983
+ The derivative expression (0 or 1 for simple cases).
984
+
985
+ Raises
986
+ ------
987
+ ValueError
988
+ If an unsupported operation is encountered.
989
+ """
990
+ if isinstance(model, _Param):
991
+ return _one() if model is wrt else _zero()
992
+
993
+ if not isinstance(model, Model):
994
+ return _zero()
995
+
996
+ if isinstance(model, Reduction):
997
+ df = _grad_fn(model.model, wrt)
998
+ if isinstance(df, (int, float, np.number)):
999
+ df = const(df)
1000
+ return Reduction(df, model.index, model.op)
1001
+
1002
+ if isinstance(model, Model) and not model.args:
1003
+ # constant Model (i.e., const(...))
1004
+ return _zero()
1005
+
1006
+ fn = getattr(model.fn, '__name__', None)
1007
+ args = model.args
1008
+
1009
+ # unary ops
1010
+ if fn == 'iden':
1011
+ return _grad_fn(args[0], wrt)
1012
+ if fn == 'neg':
1013
+ return -_grad_fn(args[0], wrt)
1014
+ if fn == 'exp':
1015
+ return model * _grad_fn(args[0], wrt)
1016
+ if fn == 'sqrt':
1017
+ return _grad_fn(args[0], wrt) / (2 * model)
1018
+ if fn == 'log':
1019
+ return _grad_fn(args[0], wrt) / args[0]
1020
+
1021
+ # binary ops
1022
+ if fn == 'add' or fn == 'radd':
1023
+ return _grad_fn(args[0], wrt) + _grad_fn(args[1], wrt)
1024
+ if fn == 'sub':
1025
+ return _grad_fn(args[0], wrt) - _grad_fn(args[1], wrt)
1026
+ if fn == 'rsub':
1027
+ return _grad_fn(args[1], wrt) - _grad_fn(args[0], wrt)
1028
+ if fn == 'mul' or fn == 'rmul':
1029
+ return args[0] * _grad_fn(args[1], wrt) + args[1] * _grad_fn(args[0], wrt)
1030
+ if fn == 'div':
1031
+ num = _grad_fn(args[0], wrt) * args[1] - args[0] * _grad_fn(args[1], wrt)
1032
+ denom = args[1] ** 2
1033
+ return num / denom
1034
+ if fn == 'rdiv':
1035
+ num = _grad_fn(args[1], wrt) * args[0] - args[1] * _grad_fn(args[0], wrt)
1036
+ denom = args[0] ** 2
1037
+ return num / denom
1038
+ if fn == 'pow':
1039
+ base, exp = args
1040
+ df = _grad_fn(base, wrt)
1041
+ if isinstance(exp, (Model, _Param)) and not base is exp:
1042
+ return model * (_grad_fn(exp, wrt) * np.log(base) + exp * df / base)
1043
+ elif isinstance(exp, Model) and exp.params:
1044
+ return model * (_grad_fn(exp, wrt) * np.log(base) + exp * df / base)
1045
+ else:
1046
+ # constant exponent
1047
+ return exp * (base ** (exp - 1)) * df
1048
+
1049
+ if fn == 'rpow':
1050
+ exp, base = args
1051
+ df = _grad_fn(base, wrt)
1052
+ if isinstance(exp, (Model, _Param)) and not base is exp:
1053
+ return model * (_grad_fn(exp, wrt) * np.log(base) + exp * df / base)
1054
+ elif isinstance(exp, Model) and exp.params:
1055
+ return model * (_grad_fn(exp, wrt) * np.log(base) + exp * df / base)
1056
+ else:
1057
+ return exp * (base ** (exp - 1)) * df
1058
+
1059
+ if fn == '_indecise':
1060
+ entries, index = model.args
1061
+ if isinstance(entries, (list, tuple)):
1062
+ # differentiate each entry
1063
+ grads = []
1064
+ for e in entries:
1065
+ if isinstance(e, Model):
1066
+ grads.append(_grad_fn(e, wrt))
1067
+ elif isinstance(e, _Param):
1068
+ grads.append(_one() if e is wrt else _zero())
1069
+ else:
1070
+ grads.append(_zero())
1071
+ return Model(model.fn, [grads, index])
1072
+ else:
1073
+ d_entries = simplify(_grad_fn(entries, wrt))
1074
+ if d_entries == 0:
1075
+ return 0
1076
+ return Model(model.fn, [d_entries, index])
1077
+
1078
+ if fn == 'sum':
1079
+ return Model(np.sum, [_grad_fn(args[0], wrt)])
1080
+
1081
+ if fn == 'where':
1082
+ cond, x, y = args
1083
+ # Differentiate only the "branches"
1084
+ dx = _grad_fn(x, wrt)
1085
+ dy = _grad_fn(y, wrt)
1086
+ return Model(np.where, [cond, dx, dy])
1087
+ raise ValueError(
1088
+ f"Cannot differentiate operation '{fn}'.\n"
1089
+ f" Supported: add, sub, mul, div, pow, neg, exp, sqrt, log, sum, where, _indecise.\n"
1090
+ f" Consider using grad=False in fit() for numerical gradients."
1091
+ )
1092
+
1093
+ def _grad(self, wrt=None):
1094
+ if wrt is None:
1095
+ wrt = self.params
1096
+ if isinstance(wrt, _Param):
1097
+ return ensure_model(_grad_fn(self, wrt)).simplify()
1098
+ if isinstance(wrt, (list, tuple)):
1099
+ return vector(*[ensure_model(_grad_fn(self, p)).simplify() for p in wrt])
1100
+ raise TypeError(f"grad expects Param, list of Param, or None, got {type(wrt)}")
1101
+
1102
+
1103
+ Model.grad = _grad
1104
+
1105
+ def iden(x):
1106
+ """Identity function, returns input unchanged."""
1107
+ return x
1108
+
1109
+
1110
+ def identity(val: Any) -> Model:
1111
+ """Wrap a value in an identity Model node.
1112
+
1113
+ Creates a Model that simply passes through its argument unchanged.
1114
+ Useful for marking component boundaries in composite models.
1115
+
1116
+ Parameters
1117
+ ----------
1118
+ val : Any
1119
+ The value or Model to wrap.
1120
+
1121
+ Returns
1122
+ -------
1123
+ Model
1124
+ A Model that evaluates to the input value.
1125
+ """
1126
+ return Model(iden, [val])
1127
+
1128
+
1129
+ def model_sum(models: list, N=None, weights: list | None = None) -> Model:
1130
+ """Create a weighted sum of models with a total normalization.
1131
+
1132
+ Builds a mixture model of the form: N * (w1*m1 + w2*m2 + ... + (1-sum(w))*mN)
1133
+ where the weights sum to 1 and N is the total normalization.
1134
+
1135
+ Parameters
1136
+ ----------
1137
+ models : list[Model]
1138
+ List of component models to combine.
1139
+ N : Param | float | None, optional
1140
+ Total normalization parameter. If None, creates a new positive Param.
1141
+ If a scalar, creates a positive Param with that starting value.
1142
+ weights : list[Param] | None, optional
1143
+ Weight parameters for each model except the last (which gets 1 - sum).
1144
+ If None, creates unit-constrained Params named 'w'.
1145
+
1146
+ Returns
1147
+ -------
1148
+ Model
1149
+ A composite model representing the weighted sum.
1150
+
1151
+ Examples
1152
+ --------
1153
+ >>> peak = model_sum([gaussian(mu1, s1), gaussian(mu2, s2)], N=1e6)
1154
+ >>> # Creates: N * (w * gauss1 + (1-w) * gauss2)
1155
+ """
1156
+ from .param import Param
1157
+
1158
+ if N is None:
1159
+ N = Param.positive('N')
1160
+ elif np.isscalar(N):
1161
+ N = Param.positive('N')(N)
1162
+
1163
+ if weights is None:
1164
+ weights = [Param.unit('w') for _ in range(len(models) - 1)]
1165
+
1166
+ weighted = [
1167
+ identity(weights[i] * models[i]) if i < len(models) - 1
1168
+ else identity(models[i] * (1 - sum(weights)))
1169
+ for i in range(len(models))
1170
+ ]
1171
+
1172
+ return identity(N) * sum(weighted)
1173
+
1174
+
1175
+ def ensure_model(x):
1176
+ return x if isinstance(x, Model) else identity(x)
1177
+
1178
+ def vector(*models):
1179
+ """Create a Model that evaluates multiple models and stacks results."""
1180
+ def stack_fn(*args):
1181
+ return np.array(args)
1182
+ stack_fn.__name__ = "vector"
1183
+ return Model(stack_fn, [ensure_model(m) for m in models])
1184
+
1185
+
1186
+ def formula(fn: Callable) -> Callable[..., Model]:
1187
+ """Decorator to create a Model factory from a function.
1188
+
1189
+ The decorated function's first argument becomes INPUT (the independent
1190
+ variable), and remaining arguments become Model parameters. Returns a
1191
+ factory that takes the parameters and produces a Model.
1192
+
1193
+ Parameters
1194
+ ----------
1195
+ fn : Callable
1196
+ A function where the first argument is the input data and
1197
+ subsequent arguments are parameters.
1198
+
1199
+ Returns
1200
+ -------
1201
+ Callable[..., Model]
1202
+ A factory function that takes parameters and returns a Model.
1203
+
1204
+ Examples
1205
+ --------
1206
+ >>> @formula
1207
+ ... def line(x, a, b):
1208
+ ... return a * x + b
1209
+ >>> model = line(Param('slope'), Param('intercept'))
1210
+ >>> model(np.array([1, 2, 3]))
1211
+
1212
+ >>> @formula
1213
+ ... def gaussian(x, mu, sigma):
1214
+ ... return np.exp(-0.5 * ((x - mu) / sigma)**2) / (sigma * np.sqrt(2*np.pi))
1215
+ >>> g = gaussian(Param('mu')(0), Param.positive('sigma')(1))
1216
+ """
1217
+ @functools.wraps(fn)
1218
+ def factory(*args):
1219
+ return Model(fn, [INPUT, *args])
1220
+ return factory
1221
+
1222
+
1223
+ def _is_scalar_equal(x, val):
1224
+ """Check if x equals val, handling floats with tolerance."""
1225
+ if isinstance(x, (Model, _Param)):
1226
+ return False
1227
+ if isinstance(x, (int, float, np.number)):
1228
+ return np.isclose(x, val, rtol=1e-14, atol=1e-14)
1229
+ return x == val
1230
+
1231
+
1232
+ def simplify(m: Model | Any) -> Model | Any:
1233
+ """Simplify a model by applying algebraic identities.
1234
+
1235
+ Performs constant folding and removes redundant operations:
1236
+ - ``x * 0 -> 0``, ``x * 1 -> x``
1237
+ - ``x + 0 -> x``
1238
+ - ``x - 0 -> x``, ``0 - x -> -x``
1239
+ - ``x / 1 -> x``, ``0 / x -> 0``
1240
+ - ``x ** 0 -> 1``, ``x ** 1 -> x``
1241
+
1242
+ Parameters
1243
+ ----------
1244
+ m : Model | Any
1245
+ The expression to simplify.
1246
+
1247
+ Returns
1248
+ -------
1249
+ Model | Any
1250
+ A simplified expression (may be a constant if fully reduced).
1251
+ """
1252
+ if not isinstance(m, Model):
1253
+ return m
1254
+
1255
+ if isinstance(m, Reduction):
1256
+ return Reduction(simplify(m.model), m.index, m.op)
1257
+
1258
+ fn = getattr(m.fn, '__name__', None)
1259
+ args = [simplify(arg) for arg in m.args]
1260
+
1261
+ is_zero = lambda x: _is_scalar_equal(x, 0)
1262
+ is_one = lambda x: _is_scalar_equal(x, 1)
1263
+
1264
+ if fn in ('mul', 'rmul'):
1265
+ if any(is_zero(arg) for arg in args):
1266
+ return 0
1267
+ non_one = [arg for arg in args if not is_one(arg)]
1268
+ if len(non_one) == 0:
1269
+ return 1
1270
+ if len(non_one) == 1:
1271
+ return ensure_model(non_one[0])
1272
+ return Model(m.fn, non_one)
1273
+
1274
+ if fn in ('add', 'radd'):
1275
+ non_zero = [arg for arg in args if not is_zero(arg)]
1276
+ if len(non_zero) == 0:
1277
+ return 0
1278
+ if len(non_zero) == 1:
1279
+ return ensure_model(non_zero[0])
1280
+ return Model(m.fn, non_zero)
1281
+
1282
+ if fn == 'sub':
1283
+ if is_zero(args[1]):
1284
+ return ensure_model(args[0])
1285
+ if is_zero(args[0]):
1286
+ return ensure_model(-args[1])
1287
+ return Model(m.fn, args)
1288
+
1289
+ if fn in ('div', 'truediv'):
1290
+ if is_zero(args[0]):
1291
+ return 0
1292
+ if is_one(args[1]):
1293
+ return ensure_model(args[0])
1294
+ return Model(m.fn, args)
1295
+
1296
+ if fn == 'pow':
1297
+ base, exp = args
1298
+ if is_zero(exp):
1299
+ return 1
1300
+ if is_one(exp):
1301
+ return ensure_model(base)
1302
+ return Model(m.fn, args)
1303
+
1304
+ if fn == 'neg':
1305
+ return ensure_model(-args[0])
1306
+
1307
+ return m.copy_with_args(args)
1308
+
1309
+ Model.simplify = simplify
1310
+
1311
+
1312
+ def shape(obj: Any) -> tuple | _Param:
1313
+ """Infer the output shape of a model or value.
1314
+
1315
+ Recursively determines what shape the expression will produce
1316
+ when evaluated.
1317
+
1318
+ Parameters
1319
+ ----------
1320
+ obj : Any
1321
+ A Model, Param, array, or scalar.
1322
+
1323
+ Returns
1324
+ -------
1325
+ tuple | _Param
1326
+ The shape as a tuple, or INPUT if the shape depends on input data.
1327
+ """
1328
+ if isinstance(obj, (int, float, np.number)):
1329
+ return ()
1330
+
1331
+ if isinstance(obj, np.ndarray):
1332
+ return obj.shape
1333
+
1334
+ if obj is INPUT:
1335
+ return INPUT # e.g. you called shape(X) directly
1336
+
1337
+ if isinstance(obj, _Param):
1338
+ return () # θ_k etc. are scalars
1339
+
1340
+ if isinstance(obj, Reduction):
1341
+ return shape(obj.model) # reduction never *adds* new shape
1342
+
1343
+ if isinstance(obj, Model):
1344
+ fn_name = getattr(obj.fn, '__name__', '')
1345
+
1346
+ # _indecise always returns a scalar for a single index lookup
1347
+ if fn_name == '_indecise':
1348
+ return ()
1349
+
1350
+ # 1. if expression explicitly depends on free X → vector
1351
+ if INPUT in obj.free:
1352
+ return INPUT
1353
+
1354
+ # 2. constant Model (no args) → try to evaluate once
1355
+ if not obj.args:
1356
+ try:
1357
+ val = obj.fn()
1358
+ return shape(val)
1359
+ except Exception:
1360
+ return ()
1361
+
1362
+ # 3. otherwise: first non-scalar arg determines shape
1363
+ for arg in obj.args:
1364
+ sh = shape(arg)
1365
+ if sh not in ((), None):
1366
+ return sh
1367
+ return () # pure-scalar combination
1368
+
1369
+ # ---------------------------------------------------------------- fallback
1370
+ return ()
1371
+
1372
+ Model.shape = shape