Debugging a model
A model can be useful before every quantity is numerical. An under-specified model may describe a family of answers. Over-specifying a model with extra observations can be useful for consistency checks. Distinguish these cases:
Situation |
Behaviour |
|---|---|
Some quantities remain undetermined |
Construction can succeed with symbolic expressions. |
Extra observations repeat information already supplied |
Redundancy is allowed; it does not itself cause a failure. |
The constructor retains no solver candidate |
|
Several solver candidates remain |
|
The solver raises an exception |
|
Counts of inputs and equations alone cannot establish consistency or uniqueness.
Conflicting observations and several valid answers can both be useful modelling
outcomes. Both solve exception types inherit from ModelSolveError (also a
ValueError) and carry the recorded problem. A zero candidate count alone
does not prove inconsistency. Use the structured attributes to handle failures;
the error reference describes them and the common ModelloError
base for library failures.
The following small model illustrates how to investigate each case:
>>> from modello import InstanceDummy, Modello, ModelSolveError, SolutionCountError, component, inspect_model
>>> class Reading(Modello):
... x = InstanceDummy("x", real=True)
... squared = x**2
>>> class Check(Modello):
... reading = component(Reading)
... total = reading.squared + 1
Inspect what remains symbolic
Without an observation, the result depends on the reading’s unknown x:
>>> partial = Check("partial")
>>> partial.total
_partial_reading_x**2 + 1
>>> partial.total.free_symbols
{_partial_reading_x}
The bound symbol belongs to partial.reading.x. Check free_symbols on the
particular result you need. An empty set means no free symbols occur in that
expression; an unevaluated function such as f(1) can still prevent a numerical
result. It does not establish that every other field is determined. Nor is the
number of free symbols in one expression a general count of the system’s degrees
of freedom.
Dependencies can also be intentional external parameters:
>>> from sympy import Symbol
>>> parameter = Symbol("parameter", real=True)
>>> parameterised = Check("external", reading=Reading("input", x=parameter))
>>> parameterised.total
parameter**2 + 1
An external symbol is distinct from a model’s independently bound quantity, even if their printed names look similar. Supply another observation or retain the expression for later substitution or differentiation, according to the question you want the model to answer.
Distinguish redundancy from contradiction
Supplying both the reading and its total is valid when they agree:
>>> known = Reading("known", x=2)
>>> Check("consistent", reading=known, total=5).total
5
Changing that total conflicts with the reading. Catch the exception and keep its structured snapshot for investigation:
>>> try:
... Check("conflict", reading=known, total=6)
... except SolutionCountError as error:
... problem = error.problem
... print(error.solution_count)
0
>>> problem
ModelProblem(Check, 'conflict', fields=3, constraints=5)
>>> print(problem)
Check('conflict')
c0: total = reading.squared + 1 [definition]
c4: total = 6 [input 'total']
reading: Reading
c1: squared = x**2 [definition]
c2: x = 2 [input 'reading']
c3: squared = 4 [inferred in 'reading']
Here the child fixes x = 2, so its square is 4 and the parent’s total must
be 5. Remove or correct the conflicting observation. Adding more observations
cannot repair that contradiction.
Within each component, equations omit the shared path prefix, so the reading’s
definition is simply squared = x**2. When an equation crosses layers, both
sides use paths from their nearest common ancestor; see the connection example
below. problem.format(expression) uses full paths from the model root for
standalone expressions. External
parameters appear as external[name]; distinct external symbols sharing a
name are numbered. Copied component values
retain whether they were supplied or inferred during construction: x = 2
was an input when building known, while squared = 4 was inferred.
Supplying known as reading to Check preserves that distinction:
x remains an input, grouped under the reading argument.
The distinction comes from the actual construction inputs, so solving a
positive reading backwards from squared=4 instead marks x as inferred.
Aliased fields share a quantity and may appear
under one representative path. The original identities remain available through
problem.fields, problem.aliases(field), and problem.uses(field).
Resolve ambiguity with a meaningful constraint
Observing only a total of 5 leaves two real readings, -2 and 2:
>>> try:
... Check("ambiguous", total=5)
... except SolutionCountError as error:
... ambiguous = error.problem
... print(error.solution_count, error.returned_count)
2 2
>>> field = ambiguous.field("reading", "x")
>>> sorted(candidate.value(field) for candidate in ambiguous.candidates)
[-2, 2]
>>> answers = ambiguous.analyse()
>>> answers.status
'consistent'
>>> roots, = answers.solution_sets
>>> roots.field == field, roots.values, roots.domain
(True, {-2, 2}, Reals)
Here consistent establishes existence, not uniqueness. Each candidate can
be audited with ambiguous.check(candidate). Its verdict is satisfied,
violated, or unknown; residual and assumption checks explain the outcome.
Modello does not choose a branch arbitrarily. Supply an observation that selects the intended answer, or refine the model’s domain if that is part of its meaning. For example, a positive reading selects the positive root:
>>> class PositiveReading(Reading):
... x = InstanceDummy("x", positive=True)
>>> class PositiveCheck(Check):
... reading = component(PositiveReading)
>>> PositiveCheck("positive", total=5).reading.x
2
Assumptions are constraints too. A total of 1 would require x = 0, which
violates this model’s strict positivity:
>>> try:
... PositiveCheck("outside_domain", total=1)
... except SolutionCountError as error:
... print(error.solution_count)
0
>>> PositiveCheck("inspect_domain").reading.x.is_positive
True
Check the assumptions on the symbolic field, not just the supplied number.
Undefined expressions, such as 1 / x at zero, can also leave no valid
solution. Assumptions about external symbolic parameters may remain undecided;
successful construction is not proof of all possible parameter values’ validity.
solution_count counts retained solver candidates. A candidate may contain
symbolic expressions representing a family of numerical answers, as in the
unresolved partial model above. returned_count counts captured candidates
before domain filtering; error.problem.candidates retains them for inspection,
including rejected proposals.
solution_sets uses SymPy’s solveset where equations reduce to one
unknown after forced numerical substitutions. Unlike a finite candidate list,
a SymPy set can retain an infinite family or an unresolved ConditionSet:
>>> from sympy import ImageSet, pi, sin
>>> class Oscillation(Modello):
... angle = InstanceDummy("angle", real=True)
... sine = sin(angle)
>>> periodic = inspect_model(Oscillation, "periodic", sine=0).analyse()
>>> family, = periodic.solution_sets
>>> family.values.has(ImageSet), family.values.contains(7 * pi)
(True, True)
These are necessary values for the recorded subsystem, with its substitutions and search domain retained. Other equations and declared predicates can still exclude values; a nonempty set alone does not establish whole-model consistency. An unresolved set is not evidence of inconsistency. See Diagnostic guarantees and reference for the scope of these results.
To retain the joint family, add observations, inspect possible outputs, or select several valid model instances, see Explore a solution family. That exploration starts from the same recorded problem, including one retained on an exception.
Inspect components and their connections
You can prepare the same problem without solving it, then inspect components and the equations crossing their boundaries:
>>> prepared = inspect_model(Check, "investigate", reading=known, total=6)
>>> reading = prepared.at("reading")
>>> reading.model is Reading
True
>>> tuple(c.path for c in reading.boundary_constraints)
(('total',),)
reading.owned_constraints contains the subtree’s definitions, copied
observations, and inferred construction results. Its boundary includes the
parent’s total equation. This describes
structure; a conflict can span individually valid layers, with no single guilty
component.
A copied symbolic input can reference a quantity in an enclosing component. For example, link the reading to its check’s total, then inspect that check inside another layer:
>>> class Audit(Modello):
... check = component(Check)
>>> linked_reading = Reading("linked_reading", x=Audit.check.total - 1)
>>> linked_check = Check("linked_check", reading=linked_reading)
>>> linked = inspect_model(Audit, "linked", check=linked_check)
>>> print(linked)
Audit('linked')
check: Check
c0: total = reading.squared + 1 [definition]
c2: total = (total - 1)**2 + 1 [inferred in 'check']
reading: Reading
c1: squared = x**2 [definition]
c3: reading.x = total - 1 [input 'check']
c4: reading.squared = (total - 1)**2 [inferred in 'check']
In c1, both fields belong to reading, so neither needs a prefix. In
c3, total belongs to its parent check. Both sides are therefore
relative to check: reading.x = total - 1. The common check. prefix
is omitted; keeping reading. on the left makes the cross-layer connection
visible. Structured constraint paths remain complete:
>>> linked.constraints[3].path
('check', 'reading', 'x')
An explicitly constructed child such as Reading("bad", x=2, squared=5)
raises before it can be passed to Check. In that case, inspect the child’s
exception: the parent has not been constructed. A supplied child has therefore
already passed construction in its own context, so investigate the additional
parent observations and connections first. That does not prove the child is
correct for the intended application or for every external parameter value.
component(Reading) declares a type rather than constructing a child.
Class definitions do not check satisfiability: even an inconsistent child type
can appear in a parent declaration. An omitted child, or a supplied child with
symbolic quantities, can gain constraints when the parent is solved. Those
constraints can conflict with the
child’s equations or domain even though its declaration or earlier construction
succeeded.
Ask for evidence explicitly
Analysis is opt-in because it can simplify expressions, perform exact linear algebra, generate and check solver candidates, and assess many subsets:
>>> report = problem.analyse(conflicts=True, relaxations=True)
>>> print(report)
Check('conflict'): inconsistent
An exact linear combination proves a contradiction.
Exact equality rank 3; augmented rank 4; nullity 0 (affine subset only, domains excluded).
Proven conflict (irreducible; declared domains retained):
c0: total = reading.squared + 1 [definition]
c4: total = 6 [input 'total']
reading: Reading
c3: squared = 4 [inferred in 'reading']
Certificate: (-1)*c0 + (-1)*c3 + (1)*c4 gives -1 = 0.
Input removals:
reading: consistent
total: consistent
Subset assessments: 6.
>>> report.conflict.linear_certificate.verify()
True
The smaller conflict proves that the copied square and observed total cannot
both agree with the parent’s equation. irreducible means removing any one
member admits a checked witness, with declared symbol domains retained. It does
not mean the smallest possible conflict or the only conflict.
report.input_checks retains every attempted whole-input removal, including
inconsistent and unknown outcomes. report.relaxations selects only those
with validated witnesses. Removing reading releases all its copied values,
including derived fields. These are possibilities to investigate, not choices
of which observation is wrong:
>>> reconsidered = problem.without("reading").analyse()
>>> reconsidered.status
'consistent'
For a single report in an exception handler, invoke analysis at that call site:
try:
result = Check("case", reading=known, total=6)
except ModelSolveError as error:
print(error.problem.analyse(
conflicts=True, relaxations=True, max_checks=100,
))
max_checks limits distinct subset assessments, not elapsed time. A single
symbolic operation may be expensive. Exhausted budgets and inconclusive checks
remain visible; neither is evidence of inconsistency. unknown means the
analyser has not established a result, and can occur even for a valid model.
Float arithmetic is not used for exact equality proofs; use SymPy Rational
values when exact decimal relationships matter. See Diagnostic guarantees and reference for
the guarantees, supported checks, and research behind the tools.
Use observations on joining models to ask questions across components, as in the portfolio example. Reconstruct a model when changing observations; changing an attribute does not solve it again.
Unknown field names, invalid scalar inputs, and incompatible component types
raise ModelInputError (a TypeError) before solving. Backend failures
raise SolverBackendError with the original backend_error also chained as
the cause, with the recorded problem still available. Keep that
cause when investigating unsupported mathematics. See API reference for input rules and
Nested models for component copying, scope, and refinement.