Vectors and indexed formulas

Use Vector for measurements, predictions, or other ordered scalar quantities. The calibration walkthrough shows how vector expressions define a fitting objective. This guide covers the individual operations. Use Scalar recurrence queries for a relative law independent of its observation window, or Finite state sequences when each entry should contain a complete model.

Start with observations

Let the data determine the size instead of building a class for every length:

>>> from modello import InstanceDummy, Modello, Vector, inspect_model
>>> class Window(Modello):
...     N = InstanceDummy("N", integer=True, nonnegative=True)
...     samples = Vector("x", size=N, real=True)
...     total = samples.sum()
>>> case = Window("data", samples=[1, None, 3], total=6)
>>> case.N, case.samples
(3, [1, 2, 3])
>>> Window("shorter", samples=[2, 5]).total
7

None leaves an entry unknown. The total determines the missing value; without that observation it stays symbolic. Vector assumptions apply to every entry, including inferred values.

Observed lengths must agree with the declared sizes: two vectors of size N need matching lengths; a vector of size N+1 needs one more entry. N=3 also requests three unknown entries without supplying a vector. A literal size=3 fixes the size. Use v.shape[0] for an unresolved size; len(v) needs a finite integer. doit() leaves an unresolved length symbolic, so native SymPy transformations can compose before the size is known. Iteration and export need a finite length. Construct another case for a different observation window.

Operations

>>> x, y = Vector(1, 2, 3), Vector([3, 2, 1])
>>> x[-1], x[1:], (x + y).doit(), (2 * x).doit()
(3, [2, 3], [4, 4, 4], [2, 4, 6])
>>> x.sum().doit(), x.product().doit(), x.dot(y).doit()
(6, 6, 10)

Vectors are immutable. Integer indexing and slicing follow Python, including negative indices. Addition and subtraction require equal shapes; multiplication and division scale by a scalar. dot and @ give a bilinear contraction without complex conjugation. Empty vectors have sum zero and product one.

Inside a model, reductions are evaluated as part of answering the question. For standalone calculations like these, call .doit(). Native sums, products, integrals, derivatives, and limits can also be declared directly. Their formulas remain intact for inspection and rendering.

Comprehensions

vector(expression, (index, first, last)) includes both endpoints, like SymPy limits. Its own positions always start at zero:

>>> from modello import Index, vector
>>> i = Index("i")
>>> squares = vector(i**2, (i, 2, 4))
>>> squares[0], squares[-1], squares.doit()
(4, 16, [4, 9, 16])

Use Index for a local integer variable; it is not an observable model field. Bounds may contain declared integer size fields, such as vector(2*samples[i], (i, 0, N-1)). A symbolic origin is also supported when the length is known, for example (i, n, n+2).

To retain domains on a calculated vector, declare its coordinates before assigning the formula:

factors = Vector("g", size=N, positive=True)
factors = vector(1 + returns[i], (i, 0, N - 1))

This requires every gross return to be positive. Inheritance can refine domains or formulas while keeping the declared shape; use a new model shape to change its size expression.

Custom scalar operations

applyfunc(f) preserves the vector’s length and order while applying a scalar expression builder. It accepts ordinary functions, Python lambdas, native SymPy functions, and SymPy Lambda expressions:

>>> from sympy import Array, Lambda, Piecewise, Symbol, conjugate
>>> u = Symbol("u")
>>> operation = Lambda(u, u**2 + 1)
>>> x.applyfunc(operation).doit(), Array(x).applyfunc(operation)
([2, 5, 10], [2, 5, 10])
>>> x.applyfunc(lambda value: Piecewise((value, value > 1), (0, True))).doit()
[0, 2, 3]
>>> x.applyfunc(conjugate).dot(x).doit()
14

Known entries are transformed directly. A symbolic length retains an indexed formula, so the callable must accept symbolic scalar arguments. Use Piecewise for value-dependent branches. For positions, moving windows, or several input vectors, keep the indices explicit with vector(...). For model members, states.project(lambda state: ...) first produces a scalar vector; it can combine fields and use the same operations.

>>> v = Symbol("v")
>>> combine = Lambda((u, v), u*v + 1)
>>> vector(combine(x[i], y[i]), (i, 0, x.shape[0]-1)).doit()
[4, 5, 4]

Inside a model class, use Lambda to capture model quantities in the expression. Python lambdas do not close over a class namespace:

>>> from modello import Coordinate
>>> class Calibration(Modello):
...     N = InstanceDummy("N", integer=True, nonnegative=True)
...     readings = Vector("x", size=N, real=True)
...     scale = InstanceDummy("scale", real=True)
...     u = Coordinate("u", real=True)
...     adjusted = readings.applyfunc(Lambda(u, scale*u + 1))
>>> Calibration("forward", readings=[1, 2, 3], scale=2).adjusted
[3, 5, 7]

Native one-dimensional arrays and row or column matrices also work as vector inputs. See Work with SymPy for exchanging containers, symbolic expressions, and numerical functions with SymPy.

Inspection and solution families

>>> problem = inspect_model(Window, "window", samples=[1, None, 3])
>>> family = problem.solutions().observe(total=6)
>>> family.one().samples
[1, 2, 3]

Use family.expression(...) to obtain a SymPy expression for further analysis, or problem.latex(...) to export a named formula. See Explore a solution family for adding conditions and selecting outputs, and Diagnostic guarantees and reference for field lookup. Family observations accumulate: None adds no constraint and does not release an earlier observation. Construct a new case to replace a dataset.

Exact families require remaining indices and bound operators to resolve. Supply finite bounds and valid coordinates before requesting one. Direct invalid integer indexing raises IndexError; an undefined symbolic selection is excluded from finite solutions.

Calculus uses SymPy

Use a real Coordinate for a local continuous variable, and InstanceDummy for a quantity that should be observed or inferred:

>>> from sympy import Derivative, Integral
>>> from modello import Coordinate
>>> class Exposure(Modello):
...     t = Coordinate("t", real=True)
...     rate = InstanceDummy("rate", real=True)
...     duration = InstanceDummy("duration", positive=True)
...     area = Integral(rate * t, (t, 0, duration))
>>> Exposure("inverse", duration=3, area=9).rate
2
>>> class Sensitivity(Modello):
...     x = InstanceDummy("x", real=True)
...     square = x**2
...     slope = Derivative(square, x)
>>> Sensitivity("point", x=3).slope
6

Referenced formulas are expanded before differentiation; differentiation variables stay independent until their derivatives are taken. To differentiate along a constrained family, first obtain its reduced expression with family.expression. Calculus through cyclic or multiply defined quantities needs an explicit parametrization. Some limits and integrals remain symbolic until the relevant observations are supplied. See Generality and solver boundaries for the supported calculus and domain checks.

See the native SymPy concrete mathematics and calculus APIs for operator syntax. Continue with Scalar recurrence queries for scalar recurrence queries, or Finite state sequences to relate typed states across a finite window. The gallery applies these tools to line fitting and account states.