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. This API is a WIP exploration; its current scope and guarantees are below.

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.parameters[0].symbol == check.reading.x
True
>>> family.parameter_domain
Reals
>>> family.expression(check.total) == check.reading.x**2 + 1
True
>>> family.values(check.total)
Interval(1, oo)

problem.symbols exposes the declared component tree with its model type, so attribute completion follows Check and Reading. Like component references in a class definition, this read-only namespace provides symbols, rather than solved instances or their methods. Each quantity has its own symbol, including derived fields such as check.total: observing that symbol can constrain the inputs that produce it. family.symbols exposes the same view.

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

Coordinate count is not generally a dimension: a coordinate domain can still contain equations, discrete alternatives, or unresolved conditions.

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 and methods retain their model types. Materialisation uses the same population mechanism as solved components; custom constructor hooks are not invoked. The source problem and earlier families stay unchanged. Calling observe() or where() without arguments returns the same family without repeating symbolic reduction.

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

Use symbolic relations to constrain a nested quantity without constructing its component, or to relate quantities across layers:

>>> 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

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.

Directed substitutions and exact rational affine elimination simplify the system without discarding other equations. A one-coordinate system can use solveset and real inequality solving. External coefficients and unevaluated functions remain conditional where generic solving could lose a singular case. Solver failures retain the condition; they do not imply an empty family. General multivariate nonlinear systems keep their joint ConditionSet.

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. Evaluate bound-variable expressions such as integrals and derivatives before exploring. Other model-construction behaviour is unchanged. Scalar queries and observations follow the same commutative-scalar scope as model fields. where(...) accepts symbolic relations and Python booleans; the SymbolicCondition protocol keeps this boundary visible to type checkers. Unsupported domain predicates raise ModelInputError instead of being omitted. These limits keep unsupported operations explicit while the WIP develops.

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(). problem retains the source; symbols provides typed quantity access. parameters and parameter_domain describe the chart. conditions and issues retain added relations and unsuccessful reductions. is_empty is True, False, or None.

SolutionFamily.format(expression: Basic) → str

Format chart symbols as the model’s named paths without substitution.

SolutionFamily.expression(expression: ScalarValue) → Expr

Express a scalar in the remaining coordinates, using public symbols.

SolutionFamily.values(*expressions: ScalarValue) → Set

Return possible scalar values, or coupled tuples for multiple outputs.

SolutionFamily.where(*conditions: SymbolicCondition | bool) → SolutionFamily[ModelT]

Retain further symbolic conditions; use Eq for equality observations.

SolutionFamily.observe(**inputs: ScalarValue | 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.