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
InstanceDummydeclares a quantity to observe or infer. Each prepared problem and component receives its own identities.IndexandCoordinatename local integer and continuous variables. They do not add observable fields.An ordinary SymPy
Symbolremains 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.