Start modelling

Declare quantities and their relationships, then supply the observations you have. The same model can calculate a result, infer a missing input, or retain a formula while a quantity is unknown. There is no separate inverse model.

This walkthrough builds up four ways to express a problem: scalar quantities, components, vectors, and recurrent states. It uses basic Python and SymPy’s mathematical notation. For a quick choice by formula or scope, see Choose a modelling approach. Install with Python 3.11 or newer:

$ pip install modello

1. Relate scalar quantities

What length of diagonal brace spans a rectangular opening? Declare its two sides and the relationship that determines the diagonal:

>>> from sympy import sqrt
>>> from modello import InstanceDummy, Modello
>>> 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

InstanceDummy declares a quantity to observe or infer. Assumptions such as positive=True state its domain. "brace" labels this case.

To ask the inverse question, supply the diagonal instead of a side:

>>> Triangle("run", b=8, c=10).a
6

To try different measurements, construct another case:

>>> Triangle("larger", a=6, b=8).c
10

Omitting an input keeps the result symbolic:

>>> undecided = Triangle("open", b=4)
>>> undecided.c == sqrt(undecided.a**2 + 16)
True

Results are ordinary SymPy expressions. A new construction answers a new question; assigning an attribute afterward does not recalculate the model.

2. Compose models

A parcel’s full diagonal depends on its base diagonal and height. Reuse the triangle as a typed component rather than repeating its equation:

>>> from modello import component
>>> class Box(Modello):
...     base = component(Triangle)
...     height = InstanceDummy("height", positive=True)
...     diagonal = sqrt(base.c**2 + height**2)
>>> base = Triangle("base", a=3, b=4)
>>> Box("parcel", base=base, height=12).diagonal
13

A parent observation can determine an unknown inside a child. Specify exactly 13 units of diagonal clearance and infer the base width:

>>> parcel = Box("width", base=Triangle("base", b=4), height=12, diagonal=13)
>>> parcel.base.a
3

The parent and children are one system of relationships. parcel.base is still a Triangle.

Join components with a shared quantity

Suppose two openings need braces of the same length. Declare the components first, then the equations joining their diagonals:

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

The repeated length assignments express length = first.c AND length = second.c. Both links and each component’s own equations must hold together. This lets a measurement in one component determine a quantity in another. See Component models for partial observations and conflicting claims.

3. Model collections and fit parameters

For a line through sensor readings, express predictions for each observation, then combine their residuals into an error objective:

>>> from sympy import Derivative
>>> from modello import Index, Vector, vector
>>> class Calibration(Modello):
...     N = InstanceDummy("N", integer=True, positive=True)
...     times = Vector("t", size=N, real=True)
...     observations = Vector("y", size=N, real=True)
...     slope = InstanceDummy("slope", real=True)
...     intercept = InstanceDummy("intercept", real=True)
...     i = Index("i")
...     fitted = vector(intercept + slope * times[i], (i, 0, N - 1))
...     residuals = observations - fitted
...     squared_error = residuals.dot(residuals)
...     slope_gradient = Derivative(squared_error, slope)
...     intercept_gradient = Derivative(squared_error, intercept)
>>> readings = dict(times=[0, 1, 2, 3], observations=[1, 2, 2, 4])
>>> proposed = Calibration("proposed", **readings, slope=1, intercept=1)
>>> proposed.fitted, proposed.squared_error
([1, 2, 3, 4], 1)

Observation lengths determine N. Index is a local integer coordinate; vector includes both endpoints. Another dataset uses the same declaration.

Fitting is another question for this model. Leave the coefficients unknown and require both error gradients to be zero. With distinct times, these conditions minimise the sum of squared errors:

>>> fitted = Calibration("fit", **readings, slope_gradient=0, intercept_gradient=0)
>>> fitted.slope, fitted.intercept, fitted.squared_error
(9/10, 9/10, 7/10)

The readings need not lie exactly on a line. Approximation comes from the objective you declared; Modello does not silently relax equations. See Vectors and indexed formulas for missing entries, reductions, and other symbolic formulas.

4. Relate states across a sequence

When each position contains several related quantities, use a vector of models. An account has inventory and cash; each fill has quantity, price, and fee:

>>> from modello import ModelObservations, model_recurrence, model_vector
>>> class Balance(Modello):
...     quantity = InstanceDummy("quantity", real=True)
...     cash = InstanceDummy("cash", real=True)
>>> class Fill(Modello):
...     quantity = InstanceDummy("quantity", real=True)
...     price = InstanceDummy("price", positive=True)
...     fee = InstanceDummy("fee", nonnegative=True)
...     notional = quantity * price
>>> class Account(Modello):
...     N = InstanceDummy("N", integer=True, nonnegative=True)
...     fills = model_vector(Fill, size=N)
...     states = model_vector(Balance, size=N + 1)
...     n = Index("n")
...     law = model_recurrence(
...         states[n],
...         quantity=states[n - 1].quantity + fills[n - 1].quantity,
...         cash=states[n - 1].cash - fills[n - 1].notional - fills[n - 1].fee,
...     )
...     terminal = states[-1]
>>> opening = Balance("opening", quantity=3, cash=1000)
>>> buy = Fill("buy", quantity=2, price=100, fee=1)
>>> sale = Fill("sale", quantity=-1, price=110, fee=1)
>>> posted = Account("posted", fills=[buy, sale], states=ModelObservations({0: opening}))
>>> posted.terminal.quantity, posted.terminal.cash
(4, 908)

There are N fills and N+1 account boundaries. n-1 means the previous position. ModelObservations supplies the opening boundary without fixing the window length; adding a fill creates another state.

The same recurrence can infer an unreported sale price from closing cash:

>>> reconciled = Account(
...     "reconciled", fills=[buy, Fill("sale", quantity=-1, fee=1)],
...     states=ModelObservations({0: opening}),
...     terminal=Balance("statement", cash=908),
... )
>>> reconciled.fills[1].price
110

Without that closing observation, cash remains a formula in the missing price. See Finite state sequences for partial states and boundary equations. A scalar recurrence can instead answer position queries without choosing a finite state window; Choose a sequence representation explains when to use each representation.

Keep alternatives and check observations

When observations leave several possibilities, keep a solution family and narrow it with more information:

>>> from modello import inspect_model
>>> family = inspect_model(Triangle, "possible", a=3).solutions()
>>> family.observe(c=5).one().b
4

observe adds constraints; it does not replace earlier observations. Start a new case for a different dataset. Solution families require exact observations; use SymPy Rational(9, 10) or Rational("0.9") for fractional or decimal data. See Explore a solution family for bounds, alternatives, and expressions in the remaining unknowns.

Extra observations can check a model against measurements:

>>> report = inspect_model(Triangle, "check", a=3, b=4, c=4).analyse()
>>> report.status
'inconsistent'

For larger problems, inspect the equations and reported conflict before deciding which observation to correct. A solver that cannot resolve a question has not necessarily proved a contradiction. The debugging guide and solver boundaries explain these outcomes when needed.

Try the same questions interactively

The gallery follows these four concepts. Each example offers the same questions: calculate, infer, change inputs, leave unknowns, and check observations. Its optional explorer displays the formulas and lets you change the supplied observations.

For domain-specific formulas, see the opt-in stochastic extension. The API reference covers individual methods, input types, and model refinement.