modello documentation

modello expresses symbolic models as Python classes. Compose typed components, supply the values you know, and let SymPy solve the combined equations. The same model can calculate outputs or infer missing inputs from observed results.

Install with Python 3.10 or newer:

$ pip install modello

Build a system from its parts. Each component owns its quantities; the parent connects them with equations. Here a fill relates a holding’s opening and closing states:

from modello import InstanceDummy, Modello, component


class HoldingState(Modello):
    quantity = InstanceDummy("quantity", real=True)
    cash = InstanceDummy("cash", real=True)


class Execution(Modello):
    quantity = InstanceDummy("quantity", real=True)
    price = InstanceDummy("price", positive=True)
    fee = InstanceDummy("fee", nonnegative=True)
    notional = quantity * price


class FillPosting(HoldingState):
    before = component(HoldingState)
    fill = component(Execution)
    after = component(HoldingState)

    quantity = after.quantity
    quantity = before.quantity + fill.quantity
    cash = after.cash
    cash = before.cash - fill.notional - fill.fee

The first quantity assignment binds that name to after.quantity; the second defines its relationship to the opening state and execution. Cash follows the same pattern. Supply typed instances with the values you know:

opening = HoldingState("opening", quantity=3, cash=1000)
posted = FillPosting(
    "buy", before=opening,
    fill=Execution("execution", quantity=2, price=100, fee=1),
)
assert posted.after.quantity == 5
assert posted.after.cash == 799

The components are solved jointly. Supplying closing cash instead of execution price lets the same equations infer that price. The nested-model guide develops composition, connected components, and symbolic inputs. The practical applications use it for invoice totals, production yield, and circuit measurements. The CDS reconciliation walkthrough compares source components, checks common entry errors, and exposes the pricing formula. The portfolio walkthrough adds nested transitions, reporting, and fitting a refined component from an outer constraint.

Distinct instances receive distinct bound symbols, even if they share a name. Values are solved at construction time; changing an attribute afterward does not recompute the model. Construction requires one retained solver candidate; zero or several candidates raise SolutionCountError. A candidate may still represent a symbolic family of answers. The debugging guide explains these outcomes and how to inspect them. Use solution families to explore alternatives before selecting a state.

The examples directory contains geometry, flow-scaling, and historical tax-model examples. Tax examples illustrate symbolic modeling with fixed historical rates.