Choose a modelling approach

Start with the relationship you want to express. These approaches compose; choose the notation and scope that fit your question. These runnable examples show their imports; the linked guides develop each approach.

Relate quantities or reuse a component

\[c^2 = a^2 + b^2\]

Declare lengths and their relationship, then supply the known measurements:

>>> from sympy import sqrt
>>> from modello import InstanceDummy, Modello, component
>>> class Triangle(Modello):
...     a = InstanceDummy("a", positive=True)
...     b = InstanceDummy("b", positive=True)
...     c = sqrt(a**2 + b**2)
>>> Triangle("brace", a=3, b=4).c
5

Reuse that relationship in typed components, then join their shared quantity:

>>> class LinkedBraces(Modello):
...     first = component(Triangle)
...     second = component(Triangle)
...
...     length = first.c
...     length = second.c
>>> LinkedBraces("shared", first=Triangle("first", a=3, b=4),
...              second=Triangle("second", b=3)).second.a
4

The repeated assignments mean length = first.c AND length = second.c; both components retain their own equations. See Join components with a shared quantity.

See Start modelling for inverse questions and Component models for connecting quantities across components.

Differentiate or integrate a formula

\[\frac{\partial f}{\partial x},\qquad A = \int_0^{\tau} r t\,dt\]

Use native SymPy operators such as Derivative(f, x) and Integral. Coordinate names a local continuous variable; InstanceDummy names a quantity to observe or infer:

>>> from sympy import Derivative, Integral
>>> from modello import Coordinate, InstanceDummy
>>> t = Coordinate("t", real=True)
>>> rate = InstanceDummy("rate", real=True)
>>> duration = InstanceDummy("duration", positive=True)
>>> area = Integral(rate * t, (t, 0, duration))
>>> area.subs({rate: 2, duration: 3}).doit()
9
>>> Derivative(area, rate).doit() == duration**2 / 2
True

A finite integration interval does not imply a finite sample vector. See Calculus uses SymPy for using these formulas inside a model.

When a calculation needs mathematical shape or regularity guarantees, use the opt-in verification workflow. It records explicit and operation-derived obligations, parameter conditions, and proof evidence alongside immutable verification contexts.

Work with finite data and indexed formulas

\[\vec{x} = (x_0,\ldots,x_{N-1}),\qquad y_i = a x_i + b\]

Use Vector for finite scalar data and vector for indexed predictions. Index is a local integer coordinate; comprehension bounds are inclusive:

>>> from sympy import Product, Sum
>>> from modello import Index, Vector, vector
>>> i = Index("i")
>>> x = Vector(1, 2, 3)
>>> N = x.shape[0]
>>> y = vector(2*x[i] + 1, (i, 0, N-1))
>>> y.doit()
[3, 5, 7]

Compact operations and native SymPy notation give the same finite reductions \(\sum_i x_i\), \(\prod_i x_i\), and \(\sum_i x_i y_i\):

>>> x.sum().doit(), Sum(x[i], (i, 0, N-1)).doit()
(6, 6)
>>> x.product().doit(), Product(x[i], (i, 0, N-1)).doit()
(6, 6)
>>> x.dot(y).doit(), Sum(x[i]*y[i], (i, 0, N-1)).doit()
(34, 34)

For your own pointwise operation \(f(x_i)\), use applyfunc with a Python function or SymPy Lambda. It uses the same name as SymPy arrays:

>>> from sympy import Array, Lambda, Symbol
>>> z = Symbol("z")
>>> operation = Lambda(z, z**2 + 1)
>>> x.applyfunc(operation).doit(), Array(x).applyfunc(operation)
([2, 5, 10], [2, 5, 10])
>>> x.applyfunc(lambda value: value**2 + 1).sum().doit()
17
>>> Sum(operation(x[i]), (i, 0, N-1)).doit()
17

Use an indexed comprehension when the operation needs positions or several vectors. See Custom scalar operations for composition and Work with SymPy for exchanging native containers, formulas, and solver answers.

See Vectors and indexed formulas for partial data, domains, and fitting with these formulas. For a collection of complete models, use model_vector. For an infinite bound, such as \(\sum_{i=0}^{\infty} q^i\), use native Sum directly:

>>> from sympy import Rational, Sum, oo
>>> q = Rational(1, 2)
>>> Sum(q**i, (i, 0, oo)).doit()
2

A Vector always has finite size. Infinite-bound convergence and evaluation follow SymPy’s supported cases and conditions.

Express relative evolution

\[T_n = aT_{n-1} + b,\qquad T_0 = u\]

Two representations describe this law. Both examples below calculate \(a=2, b=1, u=1\).

Query a scalar law without choosing a horizon

>>> from sympy import symbols
>>> from modello import Index, Recurrence, Series
>>> a, b, opening = symbols("a b opening", real=True)
>>> n = Index("n")
>>> T = Series("T", n, real=True)
>>> scalar_law = Recurrence(T[n], a*T[n-1] + b, initial={0: opening})
>>> bound = scalar_law.subs({a: 2, b: 1, opening: 1})
>>> bound.at(3).doit(), bound.window(0, 3).doit()
(15, [1, 3, 7, 15])

The rule applies for \(n\ge 1\). Use scalar_law.at(k) for a position or scalar_law.window(0, N) for a finite view. No infinite vector is materialized; symbolic-position queries use verified supported closed forms. See Scalar recurrence queries.

Solve a finite window of model states

>>> from modello import Index, InstanceDummy, Modello, model_recurrence, model_vector
>>> class State(Modello):
...     value = InstanceDummy("value", real=True)
>>> class StateWindow(Modello):
...     N = InstanceDummy("N", integer=True, nonnegative=True)
...     a = InstanceDummy("a", real=True)
...     b = InstanceDummy("b", real=True)
...     n = Index("n")
...     states = model_vector(State, size=N + 1)
...     state_law = model_recurrence(states[n], value=a*states[n-1].value + b)
...     opening = states[0].value
...     closing = states[-1].value
...     levels = states.project(lambda s: s.value)
>>> case = StateWindow("forward", N=3, a=2, b=1, opening=1)
>>> case.closing, case.levels
(15, [1, 3, 7, 15])
>>> StateWindow("inverse", N=3, a=2, b=1, closing=15).opening
1
>>> case.states.project(lambda state: state.value**2).sum().doit()
284

The equations apply for \(n\in\{1,\ldots,N\}\). Observing opening gives the same finite initial-value path as the scalar law. Observing closing instead asks an inverse question.

Use this form when each state has related quantities, or the equations need implicit updates, forward references, or terminal boundaries. It solves the whole declared window jointly. project can combine a member’s fields into any scalar formula, ready for reductions and applyfunc. See Finite state sequences and the comparison of sequence semantics.

In every form, observations choose the question: calculate results, infer missing inputs, or retain formulas. Use Explore a solution family to keep alternatives and obtain SymPy expressions with family.expression(...), and Debugging a model to check conflicting observations.