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.
Library
- API reference
- Nested models
- Debugging a model
- Explore a solution family
- Diagnostic guarantees and reference
- Interactive model explorer (WIP)
- Curves, areas, and surfaces from one projectile
- Quickstart: your own explorer
- A portfolio to explore
- Choosing what you know
- From a question to its possible answers
- Understanding the interface
- Starting from your model
- Descriptions, units, and guided questions
- Exact edits and validation
- Scope of this draft
- API
Examples
Development