Diagnostic guarantees and reference
The debugging guide introduces the interactive workflow. The tools separate recorded facts, witnessed feasibility, exact contradictions, and checks that could not decide. They analyse the recorded SymPy model, with all declared symbol assumptions retained as background constraints.
These report statuses describe the evidence found by analyse(). They are
separate from constructor candidate counts: an ambiguous construction can have
a consistent report, and a zero-count failure need not have an
inconsistent report.
What each conclusion establishes
consistentA closed, finite numerical assignment has passed every recorded equality and every declared domain predicate. This proves existence without establishing uniqueness or enumerating every solution. A solver candidate is checked before it can serve as a witness.
inconsistentAn exact consequence contradicts an equality or domain, an expression is undefined, a univariate subsystem has an empty solution set, or a rational affine subset supplies a contradiction certificate. A certificate is a weighted sum of original equation residuals equal to a nonzero constant. Its
verify()method checks that identity directly.unknownNo checked witness or contradiction has been established. Empty
solveresults, unsupported mathematics, undecided predicates, Float residuals, conditional external parameters, and exhausted search budgets do not become inconsistency proofs.
The analyser propagates ground assignments, checks their necessary consequences, and extracts the affine equations with exact rational coefficients. Those equations can prove a contradiction even when other equations are nonlinear. Otherwise it tries sample assignments and, if needed, SymPy solver candidates as possible witnesses. Failure to find a witness proves nothing.
solution_sets retains SymPy sets for equations that reduce to one model
field after forced, exact, finite numerical substitutions. Each SolutionSet
records the field, original equations, substitutions, search domain, and returned
set. Sets from equations for the same field are intersected. solveset can
represent finite roots, infinite families, and unresolved ConditionSet
expressions; these are not flattened into an allegedly exhaustive candidate list.
External symbolic parameters, Float equations, noncommutative expressions, and
equations still involving several unknowns are excluded from this step.
The search domain respects integer, rational, real, sign, and nonzero restrictions
where declared. It can contain extra values: other predicates, such as primality,
are checked separately. These are necessary solutions to a subsystem after
substitution, not a projection of every constraint in the model. A nonempty set
alone proves neither whole-model consistency nor uniqueness. An empty set proves
inconsistency because the domain contains all permitted finite scalar values.
Finite roots are audited as witness proposals against the original problem;
unresolved sets and solver exceptions do not become inconsistency proofs.
Unevaluated functions remain conditional, including opaque coefficients such as
f(1): these can hide a zero-coefficient case without appearing as free
symbols. Generic solver roots are not treated as exhaustive in that case.
LinearAnalysis reports only the rational affine part. Its complete flag
states whether that part includes every recorded equation. Rank and nullity
ignore domain restrictions and are not general model dimensions: x**2 = 0
has a unique real solution despite a singular Jacobian, while nonnegative
x + y = 0 permits only zero despite equality nullity one. Symbolic
coefficients are excluded rather than assigning a generic rank to all parameter
values. The actual included fields and equations remain inspectable.
Exact checks do not infer domain restrictions erased before capture by Python, SymPy, or model-definition simplification. Declare requirements such as a nonzero denominator explicitly when they belong to the mathematical model.
Copied component values retain a construction-time distinction: input
means the quantity was explicitly supplied, while inferred means it was a
construction result. Those results can still be symbolic. This is recorded
from actual constructor observations, including aliases and nested components;
it is not guessed from whether the field has a defining expression, and does
not reconstruct the solver’s derivation. The constraint’s input groups both
kinds under the supplied component argument for removal probes.
If a field’s value has changed since construction, copying it treats the new
value as an input rather than attributing it to the original inference.
Numerical views preserve this distinction for evaluated inputs and outputs too.
Constraint kinds are ConstraintKind string-enum members: DEFINITION,
INPUT, and INFERRED. They retain their lowercase string values in reports
and JSON.
Conflicts, probes, and costs
When available, a linear certificate identifies a proven conflict directly.
With conflicts=True, a cached deletion filter removes a constraint only
when its removal leaves a proven contradiction. The remaining set is a proven
conflict. It is labelled irreducible only when every single-member deletion
admits a checked witness. Each final deletion check is available through
conflict.removal_checks. Unknown checks or a limited budget leave
irreducibility unestablished. The filter finds one conflict, without claiming
minimum cardinality, preferences, or enumeration of all conflicts.
Once inconsistency is established, relaxations=True checks the original
problem after removing each whole supplied constructor argument, within the
shared budget. Definitions and all domain assumptions stay fixed. Component
inputs group all copied fields, including derived values.
input_checks records all outcomes; relaxations includes only witnessed
feasible removals. These are single-input probes, not an enumeration of minimal
diagnoses. Multiple independent conflicts can require several changes.
The shared max_checks budget counts distinct subset assessments, including
the original problem. Conflict reduction runs before input probes. Individual
assessments may simplify and solve expressions, so this is not a wall-clock
timeout. Field queries, component views, snapshot formatting, and ordinary
exception formatting do not run analysis. Preparing a problem and analysing it
leave existing model values unchanged.
Reports distinguish field paths from external parameters. Nested equations omit
their longest common component prefix on both sides.
An equation reaching outside its component is relative to the nearest common
ancestor of the referenced fields. Aliases prefer a path within the displayed
component where available. Structured paths and problem.format(expression)
retain paths from the model root.
Research and SymPy foundations
Raymond Reiter, A Theory of Diagnosis from First Principles, Artificial Intelligence 32(1), 57–95 (1987), doi:10.1016/0004-3702(87)90062-2. This supplies the distinction between conflicting requirements and alternative diagnoses. The current tooling does not implement diagnosis enumeration.
Ulrich Junker, QUICKXPLAIN: Preferred Explanations and Relaxations for Over-Constrained Problems, AAAI 2004, 167–172, published paper. The background/requirement distinction and basic deletion construction guide conflict filtering. The implementation uses conservative three-valued checks, rather than claiming QuickXplain’s complete-oracle guarantees.
John W. Chinneck and Erik W. Dravnieks, Locating Minimal Infeasible Constraint Sets in Linear Programs, ORSA Journal on Computing 3(2), 157–168 (1991), doi:10.1287/ijoc.3.2.157. Infeasible-subsystem filtering motivates evidence that helps locate formulation problems. The current exact affine checker is not a general LP feasibility solver.
SymPy’s assumptions guide and solution checking reference document inconclusive results. Candidate generation disables numerical solver checks; diagnostic equality verdicts use exact residuals and preserve unknowns.
The solveset reference explains its set-valued results and explicit domains: unlike
solve, the domain is not inferred from the target symbol’s assumptions. The algebraic solving guide explains why some solution sets cannot be enumerated. Diagnostics retain these representations and use an explicit domain rather than assuming complex roots satisfy a real field’s requirements.The linear equation conversion reference and matrix zero-testing discussion motivate restricting rank certificates to exact rational coefficients, retaining the original equations, and avoiding universal conclusions from symbolic pivots.
Recorded problems and reports
- class modello.diagnostics.ModelProblem(model: type[ModelT], name: str, fields: tuple[ModelField, ...], constraints: tuple[ModelConstraint, ...], candidates: tuple[Candidate, ...] = ())
A frozen snapshot shared by preparation, construction, and failure handling.
- property symbols: ModelT
Access this problem’s independent quantities through typed components.
Like references in a model declaration, this read-only namespace exposes scalar symbols and nested components, rather than solved model methods. Derived fields also have their own symbols, so they can be observed.
- field(*path: str) ModelField
Look up a declared path, without matching symbols by printed name.
- aliases(field: ModelField) tuple[ModelField, ...]
Find all paths to the same quantity in this problem.
- uses(field: ModelField) tuple[ModelConstraint, ...]
Find constraints mentioning a quantity, in either equation direction.
- at(*path: str) ComponentView
Inspect a component subtree and its boundary; this does not isolate a solve.
- without(*inputs: str) ModelProblem[ModelT]
Remove whole recorded constructor inputs, keeping definitions and domains.
- check(candidate: Candidate) CandidateCheck
Audit a candidate against original equations and all declared domains.
- analyse(*, conflicts: bool = False, relaxations: bool = False, max_checks: int = 100) ProblemAnalysis
Run explicit exact checks and bounded searches; unknown never means inconsistent.
max_checksbounds distinct subset assessments, not elapsed time. Domain assumptions remain fixed throughout. Relaxations remove one complete constructor argument and require a validated closed witness.
- solutions(*parameters: SymbolicScalar) SolutionFamily[ModelT]
Explore the joint family, optionally retaining chosen parameter fields.
This explicit operation can invoke exact symbolic solvers. It preserves unresolved conditions rather than choosing a candidate or branch.
- class modello.diagnostics.ModelField(path: tuple[str, ...], symbol: Symbol)
One public path to a quantity; aliases retain the same symbol identity.
- class modello.diagnostics.ConstraintKind(*values)
A defining equation, supplied input, or inferred component result.
- class modello.diagnostics.ModelConstraint(index: int, path: tuple[str, ...], kind: ConstraintKind, left: Symbol, right: Basic, input: str | None = None)
An equation’s origin, original sides, and optional constructor-input group.
Copied component values distinguish supplied inputs from inferred results.
inputgroups both under the component argument; it does not mean that each copied value was supplied explicitly.
- class modello.diagnostics.ComponentView(path: FieldPath, model: type[Modello], fields: tuple[ModelField, ...], owned_constraints: tuple[ModelConstraint, ...], boundary_constraints: tuple[ModelConstraint, ...])
A structural view, including equations crossing this component’s boundary.
- class modello.diagnostics.Candidate(values: tuple[FieldValue, ...])
A proposed assignment, rather than a claim of validity or completeness.
- value(field: ModelField) Expr
Read a quantity through any of its recorded aliases.
- class modello.diagnostics.FieldValue(field: ModelField, value: ScalarValue)
A value associated with an actual field of this problem.
- class modello.diagnostics.CandidateCheck(candidate: Candidate, residuals: tuple[ResidualCheck, ...], assumptions: tuple[AssumptionCheck, ...], verdict: Literal['satisfied', 'violated', 'unknown'])
An audit; only a satisfied, closed assignment is a consistency witness.
- class modello.diagnostics.SolutionSet(field: ModelField, domain: Set, values: Set, constraints: tuple[ModelConstraint, ...], substitutions: tuple[FieldValue, ...], solver_errors: tuple[str, ...] = ())
Necessary values for one field, after substituting forced ground values.
valuessolves only the recordedconstraintsindomain. Other equations and predicates still require checking against the whole problem. Infinite families and unresolved ConditionSets are retained as SymPy sets.
- class modello.diagnostics.ResidualCheck(constraint: ModelConstraint, residual: Basic, verdict: Literal['satisfied', 'violated', 'unknown'])
An equation checked against a candidate, retaining an undecided outcome.
- class modello.diagnostics.AssumptionCheck(value: FieldValue, predicate: str, expected: bool, actual: bool | None)
A field’s required predicate compared with its proposed value.
- class modello.diagnostics.ProblemAnalysis(problem: ModelProblem, status: Literal['consistent', 'inconsistent', 'unknown'], reason: str, linear: LinearAnalysis | None, deductions: CandidateCheck, candidates: tuple[CandidateCheck, ...], witness: CandidateCheck | None, conflict: Conflict | None, input_checks: tuple[InputCheck, ...], checks: int, budget_exhausted: bool, solution_sets: tuple[SolutionSet, ...] = ())
Evidence-backed conclusions, with the scope and unfinished work retained.
- property relaxations: tuple[InputCheck, ...]
Return just the input removals with a checked closed witness.
- class modello.diagnostics.LinearAnalysis(fields: tuple[ModelField, ...], constraints: tuple[ModelConstraint, ...], rank: int, augmented_rank: int, complete: bool, certificate: LinearCertificate | None = None)
Rank of the exact rational affine part, ignoring variable domains.
- class modello.diagnostics.LinearCertificate(terms: tuple[tuple[ModelConstraint, Expr], ...], constant: Expr)
An exact weighted sum of original residuals equal to a nonzero constant.
- class modello.diagnostics.Conflict(constraints: tuple[ModelConstraint, ...], irreducible: bool | None, reason: str, linear_certificate: LinearCertificate | None = None, removal_checks: tuple[RemovalCheck, ...] = ())
A proven conflict relative to all declared domains; minimality may be unknown.
- class modello.diagnostics.RemovalCheck(removed: tuple[ModelConstraint, ...], status: Literal['consistent', 'inconsistent', 'unknown'], reason: str, witness: CandidateCheck | None)
The evidenced outcome of removing specified constraints.
- class modello.diagnostics.InputCheck(removed: tuple[ModelConstraint, ...], status: Literal['consistent', 'inconsistent', 'unknown'], reason: str, witness: CandidateCheck | None, input: str)
A removal probe for one entire constructor argument, including copied values.