Work with SymPy

Modello uses SymPy expressions for scalar relationships. Use native operators and functions when writing a model, take its results to SymPy for further analysis, and return observations or candidate answers to the same model. There is no separate scalar expression language to translate.

Write native expressions

Import mathematical operations from SymPy and model declarations from Modello:

>>> from sympy import Derivative, Integral, Rational
>>> from modello import Coordinate, InstanceDummy, Modello
>>> 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))
...     sensitivity = Derivative(area, rate)
>>> case = Exposure("measured", duration=3, area=Rational(9, 2))
>>> case.rate, case.sensitivity
(1, 9/2)

Named dependencies expand before differentiation. Native Sum, Product, Piecewise, Limit, and symbolic functions follow the same expression path. See Calculus uses SymPy for calculus semantics and Generality and solver boundaries for the supported solver classes. Exact solution families require exact values: prefer Rational("0.1") to a binary floating-point observation. Custom scalar wrappers can use SymPy’s _sympy_ conversion protocol. Inputs use this conversion without a numerical round trip; call sympify explicitly when adapting such a wrapper for a statically annotated caller.

Choose symbols by their role

  • InstanceDummy declares a quantity to observe or infer. Each prepared problem and component receives its own identities.

  • Index and Coordinate name local integer and continuous variables. They do not add observable fields.

  • An ordinary SymPy Symbol remains an external parameter. Declaring a model field does not make every symbol in its expression a model quantity.

Use problem.symbols or family.symbols to build expressions about a prepared model. Creating another symbol with the same printed name does not refer to that quantity. A whole Modello instance or ModelVector remains structured; select a scalar field or project its members to a scalar vector.

Series describes an indexed scalar family, rather than the Taylor expansion produced by sympy.series. Recurrence supplies its causal history and relative rule; an unrelated native Function does not acquire that rule automatically. Query a law for a scalar expression or a finite vector view. See Scalar recurrence queries and Finite state sequences for scalar laws versus typed windows.

Exchange finite vector data

Vector accepts native one-dimensional arrays and concrete row or column matrices, as well as scalar sequences:

>>> from sympy import Array, Matrix
>>> from modello import Vector
>>> Vector(Array([1, 2, 3])) == Vector(Matrix([[1, 2, 3]]))
True
>>> Vector(Matrix([1, 2, 3]))
[1, 2, 3]
>>> class Baseline(Modello):
...     values = Array([1, 2, 3])
...     total = values.sum()
>>> Baseline("baseline").total
6

A native array or matrix assigned in a class body becomes a Vector field. Mutable containers are copied into immutable scalar entries. The same containers work as observations and determine symbolic sizes:

>>> from sympy import Lambda
>>> class Calibration(Modello):
...     N = InstanceDummy("N", integer=True, nonnegative=True)
...     readings = Vector("x", size=N, real=True)
...     gain = InstanceDummy("gain", real=True)
...     u = Coordinate("u", real=True)
...     adjusted = readings.applyfunc(Lambda(u, gain*u))
>>> calibrated = Calibration("forward", readings=Matrix([1, 2, 3]), gain=2)
>>> calibrated.N, calibrated.adjusted
(3, [2, 4, 6])
>>> Calibration("inverse", readings=Array([1, 2, 3]), adjusted=Matrix([[2, 4, 6]])).gain
2

Array rank must be one; matrices must have one row or one column. Empty vectors also accept the canonical empty matrix. Higher-rank arrays, genuinely two-dimensional matrices, and abstract MatrixSymbol objects are rejected rather than flattened. Use a list or tuple with None entries for partial observations.

Convert a finite vector back using native constructors. An array is rank one; the default matrix conversion is a column:

>>> Array(calibrated.adjusted).shape, Matrix(calibrated.adjusted).shape
((3,), (3, 1))

Resolve a symbolic length before exporting individual entries. Modello does not add general tensor or matrix algebra; use SymPy containers directly for it.

Reuse your own operations

An ordinary helper can return any supported scalar expression. applyfunc and vector accept native functions and Lambda expressions too:

>>> def squared_error(value):
...     return (value - 1)**2
>>> Vector(1, 2, 3).applyfunc(squared_error).doit()
[0, 1, 4]

Inside a class body, use an inline Lambda to capture model quantities, as in Calibration. Python lambdas do not close over class namespaces. Keep reusable function objects outside the model class; assigning a named Lambda as a field raises an explanatory error because it is a function, not its scalar result. Applied SymPy Function subclasses can supply their own evaluation and differentiation rules. An arbitrary numerical callable does not acquire an inverse or derivative automatically. See Custom scalar operations.

Continue an analysis in SymPy

family.expression resolves dependencies while retaining the family’s remaining coordinates. The returned scalar is a native SymPy expression:

>>> from sympy import diff, lambdify
>>> from modello import inspect_model
>>> class Square(Modello):
...     x = InstanceDummy("x", real=True)
...     squared = x**2
>>> problem = inspect_model(Square, "analysis")
>>> family = problem.solutions()
>>> x = problem.symbols.x
>>> response = family.expression(problem.symbols.squared)
>>> diff(response, x) == 2*x
True
>>> calculate = lambdify(x, response, modules="math")
>>> calculate(3)
9

For a finite vector, pass its elements tuple to lambdify:

>>> from sympy import Symbol
>>> gain = Symbol("gain", real=True)
>>> output = Vector(1, 2, 3) * gain
>>> calculate_vector = lambdify(gain, output.elements, modules="math")
>>> calculate_vector(2)
(2, 4, 6)

Conditions and coordinate domains remain on the family. A numerical function evaluates its formula without checking those conditions.

Return an answer for validation

A native solver may answer just one equation. Add its candidate back to the family to check the complete model, including domains and other observations:

>>> from sympy import Eq, solve
>>> roots = solve(Eq(response, 4), x)
>>> roots
[-2, 2]
>>> positive = family.observe(squared=4).where(x > 0)
>>> positive.where(Eq(x, roots[0])).is_empty
True
>>> chosen = positive.where(Eq(x, roots[1])).one()
>>> isinstance(chosen, Square), chosen.x
(True, 2)

Use constructor arguments or family.observe for new scalar or vector observations. Use where for symbolic conditions, and one or cases to materialize checked model states. See Explore a solution family.

Preserve the original mathematical question

Imported operators remain unevaluated until model observations are available. For example, this limit is zero when a=0 and one when a=1:

>>> from sympy import Limit, oo
>>> class LimitReading(Modello):
...     a = InstanceDummy("a", real=True)
...     value = InstanceDummy("value", real=True)
>>> t = Coordinate("t", real=True)
>>> source = Limit(LimitReading.a*t / (LimitReading.a*t + 1), t, oo)
>>> LimitReading("zero", a=0, value=source).value
0
>>> LimitReading("one", a=1, value=source).value
1

Modello retains explicit denominator exclusions through its own rebinding and evaluation. It cannot recover a pole or exceptional parameter case already removed by SymPy before the expression reaches the model. Keep such domain requirements explicit, and avoid eagerly evaluating a parameterized limit whose exceptional cases matter. Unsupported calculations remain symbolic or raise a clear error rather than validating an unestablished answer.