Scalar recurrence queries
Series names an indexed scalar family. Recurrence relates discrete
positions. Their queries are scalar formulas in an ordinary Modello model, so
the same solver can calculate results or infer parameters from observations.
Use this representation for a quantity such as T[n] when you want to query
positions without choosing a finite horizon. A finite model sequence instead solves joint equations over a declared window and can
also express implicit updates and boundary constraints. See
Choose a sequence representation for their overlap and different semantics.
One relative law, many queries
>>> from modello import Index, InstanceDummy, Modello, Recurrence, Series
>>> class Growth(Modello):
... n = Index("n", nonnegative=True)
... T = Series("T", n, positive=True)
... opening = InstanceDummy("opening", positive=True)
... ratio = InstanceDummy("ratio", positive=True)
... periods = InstanceDummy("periods", integer=True, nonnegative=True)
... law = Recurrence(T[n], ratio * T[n - 1], initial={0: opening})
... closing = T[periods]
... samples = law.window(0, 4)
>>> case = Growth("forward", opening=1, ratio=2, periods=10)
>>> case.closing, case.samples
(1024, [1, 2, 4, 8, 16])
>>> Growth("inverse", closing=1024, ratio=2, periods=10).opening
1
>>> case.law.at(20).doit()
1048576
The law has no fixed horizon. The query at position ten and the window from
zero through four are separate views. In model definitions and family queries,
T[k] uses its declared recurrence; law.at(k) explicitly selects one law.
Use the populated instance’s law for direct evaluation outside a model.
Explicit queries such as other_law.at(n) compose directly, including nested
queries evaluated by one .doit(). Unqualified terms from several series need
the model or solution family’s law registry;
family.expression(problem.symbols.T[k]) retains that context.
Series indices are mathematical positions: T[n-1] is the predecessor and
T[-1] is position minus one. A series has no length or implicit last entry.
law.window(first, last) creates an inclusive finite vector
whose Python position zero represents T[first].
History and domains
A recurrence needs contiguous history ending immediately before start.
Its fixed positive lags must be covered by that history:
>>> n = Index("n")
>>> F = Series("F", n, integer=True)
>>> law = Recurrence(F[n], F[n - 1] + F[n - 2], initial={0: 0, 1: 1})
>>> law.start, law.at(10).doit()
(2, 55)
History may start at a negative or shifted position. law.origin is its first
mathematical position; law.start is the first generated position. Neither is
a Python vector offset. Fixed references to initial positions, such as T[0],
can also appear in the transition. Queries before the history are undefined.
Series domains apply to all declared initial history and every intermediate state needed by the query. For example, a positive terminal value cannot excuse a negative predecessor in a positive series. A later invalid state does not invalidate an earlier query. A finite model sequence checks its entire declared window, so these are different problems when that window includes the invalid state.
Finite causal queries support nonlinear laws. Verified closed forms support constant first-order affine laws and suitable higher-order linear laws through SymPy’s recurrence solver. Zero and unit coefficients retain their special cases. Unsupported symbolic queries remain unevaluated; exact solution families require them to resolve.
Let observations choose the window
The guide’s autoregression declares N once. State observations have
N+1 entries and innovations have N:
class ObservedAutoregression(Modello):
"""A relative law with an independently chosen observation window."""
N = InstanceDummy("N", integer=True, nonnegative=True)
opening = InstanceDummy("opening", real=True)
retention = InstanceDummy("retention", real=True)
innovations = Vector("epsilon", size=N, real=True)
n = Index("n", nonnegative=True)
T = Series("T", n, real=True)
law = Recurrence(T[n], retention * T[n - 1] + innovations[n - 1], initial={0: opening})
levels = law.window(0, N)
closing = T[N]
>>> from examples.series import ObservedAutoregression
>>> case = ObservedAutoregression("states", retention=1, levels=[1, 3, 6, 10])
>>> case.N, case.opening, case.innovations
(3, 1, [2, 3, 4])
Either vector’s length, or an explicit N, determines the finite window.
None entries still count toward its length. Observing states and innovations
constrains the same equation; contradictory observations are rejected. To change
the driving data, construct a new case with innovations instead of observed states.
Although the law has no intrinsic horizon, finite inputs constrain which queries
are defined. Relative input positions use the same checked indexing as
finite model sequences; they never wrap to the
end of an input vector.
History and observation length are separate. A recurrence of order p needs
p history positions, but those quantities may be observed separately or
inferred. A vector of length at least p does not by itself identify unknown
coefficients or innovations. The innovation vector carries no distribution
unless the model declares one.
Fixed finite sums can express a law’s relative lags, for example
Sum(coefficients[j]*T[n-1-j], (j, 0, p-1)) with p initial values.
The nested sum uses its own index. Multiple declared series can drive each
other; finite query cycles must decrease towards their initial boundaries.
To check existing histories with typed model_recurrence laws, see the
window validator.
API
- class modello.Series(name, index=None, **assumptions)
A symbolic scalar family with no chosen sample window.
Series('T', n, real=True)[n-1]is a relative term, not Python negative indexing. An integer coordinate denotes a discrete series; a real coordinate can denote a continuous process. Finite observations remain ordinary model fields or vectors, and aRecurrencesupplies a discrete evolution law.
- class modello.Recurrence(target, expression, initial, start=None)
A causal relative law and an explicit contiguous initial history.
Recurrence(T[n], a*T[n-1], initial={0: opening})holds fromn=1..at(k)is a scalar formula;.window(first, last)is an inclusive finite vector view. Neither view changes the law’s coordinate system.- property index: Symbol
The local integer coordinate used by the law’s equations.