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

consistent

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

inconsistent

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

unknown

No checked witness or contradiction has been established. Empty solve results, 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.

format(expression: Basic) → str

Render paths from the model root without changing the expression.

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_checks bounds 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. input groups both under the component argument; it does not mean that each copied value was supplied explicitly.

property symbols: frozenset[Symbol]

Return identities mentioned by either side, without simplifying them.

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.

values solves only the recorded constraints in domain. 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.

property nullity: int

Return the affine equality nullity, not a nonlinear/domain dimension.

class modello.diagnostics.LinearCertificate(terms: tuple[tuple[ModelConstraint, Expr], ...], constant: Expr)

An exact weighted sum of original residuals equal to a nonzero constant.

verify() → bool

Independently check the certificate against its original equations.

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.