Explore a solution family
An observation can leave several alternatives, or a continuous family of
answers. problem.solutions() keeps those answers together so that you can
restrict them, examine possible outputs, and select ordinary model instances.
Use this after Start modelling when you need bounds, alternative states,
or a formula for the remaining unknowns. Families use exact inputs; use SymPy
Rational(9, 10) or Rational("0.9") for fractional or decimal observations.
Start with the debugging guide’s small composed model:
>>> from modello import InstanceDummy, Modello, component, inspect_model
>>> class Reading(Modello):
... x = InstanceDummy("x", real=True)
... squared = x**2
>>> class Check(Modello):
... reading = component(Reading)
... total = reading.squared + 1
>>> problem = inspect_model(Check, "explore")
>>> check = problem.symbols
>>> family = problem.solutions()
>>> family.expression(check.total) == check.reading.x**2 + 1
True
>>> family.values(check.total)
Interval(1, oo)
problem.symbols provides model quantities by their usual attribute paths.
Use these symbols to ask about outputs or add conditions. family.symbols
provides the same quantities.
The family uses the model’s expressions and domains. Here one real coordinate
describes every possible state. expression(...) rewrites a scalar expression
in the remaining coordinates; values(...) maps it to a SymPy set of possible
values. Both accept model symbols or expressions built from them. For example:
>>> family.expression(check.total - check.reading.squared)
1
Continue with SymPy
The returned expression uses the family’s actual symbols. Use expression
before differentiating to include dependencies resolved by the model. See
Work with SymPy for calculus, numerical compilation, finite vector
exports, and returning native solver candidates for model validation.
Refine observations and select a state
Add observations with the same scalar and component arguments as a constructor:
>>> observed = family.observe(total=5)
>>> observed.values(check.reading.x)
{-2, 2}
>>> observed.values(check.reading.x, check.total)
{(-2, 5), (2, 5)}
With several expressions, values preserves coupling and returns tuples in
the selected expressions’ order.
Taking independent Cartesian products of each field’s values would lose that
relationship. cases() materialises an explicit finite family as checked,
independently bound models:
>>> sorted((case.reading.x, case.total) for case in observed.cases())
[(-2, 5), (2, 5)]
>>> chosen = observed.where(check.reading.x > 0).one()
>>> isinstance(chosen, Check), isinstance(chosen.reading, Reading)
(True, True)
>>> chosen.reading.x, chosen.total
(2, 5)
Each case is checked against the original equations, all declared assumptions, and the added conditions before being returned. Components retain their model types. The source problem and earlier families stay unchanged; see the API reference for copying and model methods.
Observations accumulate; supplying a different value adds a constraint rather than overwriting the earlier one. Typed component observations use the same copying and input/inferred provenance rules as ordinary construction:
>>> fixed = family.observe(reading=Reading("measured", x=2)).one()
>>> fixed.reading.x, fixed.total
(2, 5)
>>> observed.observe(total=6).is_empty
True
To supply one nested scalar directly, use its dotted field path as a dictionary
key. Python’s ** passes that dictionary as keyword arguments. Constructors,
inspect_model, and observe all accept these paths:
>>> direct = family.observe(**{"reading.x": 2}).one()
>>> direct.reading.x, direct.total
(2, 5)
Use symbolic relations to relate quantities across layers or add inequalities:
>>> from sympy import Eq
>>> family.where(Eq(check.reading.squared, 4), check.reading.x > 0).one().total
5
Bounds can be more useful than an exact observation:
>>> bounded = family.where(check.total >= 4, check.total <= 6)
>>> from sympy import Interval, sqrt
>>> bounded.values(check.reading.x) == Interval(-sqrt(5), -sqrt(3)) | Interval(sqrt(3), sqrt(5))
True
The impact calibration example uses a bounded measurement to constrain a parameter and predict another trade’s cost. Such sets describe possibilities, without assigning probabilities to them.
Take a section through a reference
section(..., through=case) varies selected current coordinates and fixes
the others at a checked model instance. Derived outputs follow the equations;
selecting no coordinates gives the reference point:
>>> point = family.section(through=chosen)
>>> point.values(check.reading.x, check.total)
{(2, 5)}
Pass symbols such as check.reading.x to select coordinates. In contrast,
values(...) projects outputs while letting all remaining coordinates vary.
The reference is checked against the equations, domains, and added conditions:
a violation raises ModelValidationError and an undecided check raises
UnresolvedSolutionError with its candidate audit. Sections can remain
discrete or coupled. The example
explores their dimensions and response plots.
Continue after an exception
Ordinary construction still requires one solver candidate. A failed construction already carries the problem needed for exploration:
>>> from modello import ModelSolveError, SolutionSelectionError, UnresolvedSolutionError
>>> try:
... Check("ambiguous", total=5)
... except ModelSolveError as error:
... alternatives = error.problem.solutions()
>>> sorted(case.reading.x for case in alternatives.cases())
[-2, 2]
>>> try:
... observed.one()
... except SolutionSelectionError as error:
... print(error.solution_count, error.family is observed)
2 True
SolutionSelectionError retains the family and an exact count of checked
states when one() finds zero or several. UnresolvedSolutionError retains
family, reason, and an optional candidate check when numerical
materialisation cannot be established. Its family may be continuous or still
conditional. Printing a family shows its coordinates, domain, and nested
expressions; it does not run another solver. family.issues keeps failed
reduction attempts with their original backend exception objects.
Guarantees and current scope
Materialised cases retain model types and methods; custom constructor hooks are not invoked. See API reference for model and component construction behavior.
A family represents the captured equations over finite, commutative scalar
values. Every field’s declared assumptions remain explicit domain restrictions,
including assumptions on quantities eliminated during reduction. Inferred
component values remain constraints just as they are in the recorded problem.
family.conditions retains added symbolic relations; family.problem
records constructor-style observations and their origins. Its symbols retain
their identities across refinements. Symbols from another prepared problem
raise ModelValidationError, even when their printed names coincide.
Some questions retain conditions rather than reducing to an explicit list of answers. External parameters and unevaluated functions may leave conditional results. A failed reduction does not imply an empty family. See Generality and solver boundaries for the supported problem classes.
Returned sets can therefore remain implicit. An ImageSet or ConditionSet
can be an exact representation without an explicit enumeration, a decided
membership test, or a plotting parameterisation. cases() requires an
explicit finite coordinate domain and independently verifies every state.
family.is_empty preserves SymPy’s True, False, or undecided None.
parameters are coordinates, not a general identifiability or dimension
certificate. Pass symbols to problem.solutions(check.reading.x, ...) to
prefer particular coordinates; remaining constraints can still restrict them.
The parameters field records remain available for path and alias inspection.
The exploratory API requires exact expressions: use Rational for decimal
observations. Finite sums and products, and evaluable integrals, derivatives,
and limits are expanded through model definitions before exploring. Operators
that remain unevaluated raise ModelInputError. Vector observations use the
same scalar coordinate domains; vector queries retain coupled tuple outputs.
See Vectors and indexed formulas for examples. where(...) accepts symbolic relations and Python booleans.
Unsupported domain predicates raise ModelInputError instead of being omitted.
Unsupported calculations remain explicit.
The implementation builds on SymPy’s
sets,
set-valued and linear solvers,
and scalar assumptions.
The diagnostic reference describes the distinct, conservative
consistency and conflict reports. Its one-field subsystem solution_sets do
not claim to be the joint family explored here.
Reference
- class modello.solutions.SolutionFamily
Created by
ModelProblem.solutions().problemretains the source;symbolsprovides typed quantity access.parametersandparameter_domaindescribe the chart.conditionsandissuesretain added relations and unsuccessful reductions.is_emptyisTrue,False, orNone.
- SolutionFamily.format(expression: Basic) str
Format chart symbols as the model’s named paths without substitution.
- SolutionFamily.latex(expression: Basic, *, symbol_names: Mapping[Symbol, str] | None = None, vector_names: Mapping[Vector, str] | None = None) str
Export model or chart coordinates, with optional LaTeX name overrides.
- SolutionFamily.expression(expression: Vector) Vector
- SolutionFamily.expression(expression: ScalarValue) Expr
Express a scalar or vector in the remaining public coordinates.
- SolutionFamily.values(*expressions: ScalarValue | Vector) Set
Return scalar values or coupled tuples, retaining vector order.
- SolutionFamily.where(*conditions: SymbolicCondition | bool) SolutionFamily[ModelT]
Retain further symbolic conditions; use Eq for equality observations.
- SolutionFamily.observe(**inputs: ScalarValue | VectorValue | Modello | ModelVectorValue[Modello]) SolutionFamily[ModelT]
Add constructor-style scalar or component observations immutably.
Observations accumulate as constraints. Use
where(Eq(...))for a relation involving nested quantities without constructing a component.
- SolutionFamily.section(*controls: SymbolicScalar, through: ModelT) SolutionFamily[ModelT]
Vary chosen coordinates and fix all other coordinates at a checked case.
Outputs follow the original equations. A section can remain coupled or discrete: the number of selected coordinates is not its dimension.
- SolutionFamily.cases() tuple[ModelT, ...]
Materialize a finite family as independently bound, checked models.
Like solved components, cases use Modello’s population mechanism; custom constructor hooks are not invoked.
- SolutionFamily.one() ModelT
Select exactly one checked state, retaining this family on failure.
- class modello.solutions.SolutionIssue(operation: str, error: Exception)
An unsuccessful simplification; the original condition is still retained.
- class modello.errors.SolutionSelectionError(family: SolutionFamily, solution_count: int)
A family contains zero or several checked points when one was requested.
- class modello.errors.UnresolvedSolutionError(family: SolutionFamily, reason: str, check: CandidateCheck | None = None)
A requested operation needs explicit, checked numerical points.