Errors and what they mean

Every error says what is wrong, where, why it is refused, and what to write instead.

Conatus refuses rather than guesses. When a problem is ill-posed, a choice is missing or a solver does not converge, it raises an exception that says what is wrong, where (equation, term, variable, group), why it is refused and a suggested fix, which it never applies for you (see Principles). The last line of every message links to the section of this page named after the exception class.

All errors derive from ConatusError, and each also derives from the built-in exception its code raised before 0.1 (ValueError, TypeError, KeyError, RuntimeError, NotImplementedError, ImportError, FileNotFoundError), so except ValueError: keeps working.

import conatus.errors
print(conatus.errors.explain())   # the tree of exception classes

Warnings

A warning never replaces a result: the result is returned. A warning is shown once per line of your script, and explain() does not repeat every one (it keeps the base residual of a linearization, the group in a result’s header and a growth rule “inferred from the name”), so read the warnings. A statement that the answer may not be the one the call meant is a conatus.errors.CorrectnessWarning (a UserWarning, shown by Python’s default filters wherever it is raised):

Warning	When
BaseStateWarning	m.linearize(about=...) about a base whose steady residual exceeds BASE_RESIDUAL_TOL (not declared with base_residual="accept"); refused in v0.2
GroupWarning	eigenvalues() without k= on a periodic model (only k = 0 is solved), or without m= on a curvilinear one (only the first group); required in v0.2

Resolution detections are ResolutionWarning, UnderResolvedWarning, InitialDataWarning and IllPosedWarning. A former spelling with the same meaning (a renamed argument) is a DeprecationWarning, which Python shows only for code run as __main__.

Catalogue

The list below is generated from conatus.errors at each build.

ConatusError

Derives from Exception

Base class. ``ConatusError(message, where=..., why=..., fix=..., doc=...)``.

Only ``message`` is positional, so the historical one-argument raises keep their text as the
first line; the structured fields are appended below it and kept as attributes.

EquationError

Derives from ConatusError, ValueError · alias: ProblemError

An equation (or the whole problem) is inconsistent with the problem type or variables.

NonlinearLHSError

Derives from EquationError

The LHS contains a term that is not linear in the problem variables.

UndeclaredVariableError

Derives from EquationError, KeyError

A field is used as an unknown (or needs data) but is neither a variable nor given data.

ParameterError

Derives from EquationError, KeyError

A parameter has no value, or a parameter name is unknown.

BoundaryConditionError

Derives from EquationError

Boundary conditions are missing, in excess, or placed where none is possible.

EquationSyntaxError

Derives from EquationError

A string equation does not follow the declared grammar (``conatus.ir.parse.GRAMMAR``) or
names something that is not in its declared namespace. ``text`` and ``position`` (0-based
character offset) locate the problem; the message shows the text with a caret.

DiscretizationError

Derives from ConatusError, ValueError

The expression cannot be discretized as requested (explicit reason given).

RankError

Derives from DiscretizationError, BoundaryConditionError

The discrete system is under-/over-determined or singular (refused before factorization).

SpectralError

Derives from ConatusError, ValueError

The expression cannot be evaluated by the pseudospectral RHS evaluator.

ResolutionError

Derives from ConatusError, ValueError

The resolution is too small for what is asked (boundary conditions, derivatives...).

CoordinateError

Derives from ConatusError, ValueError

Inconsistent coordinates, bases or domain.

OptionError

Derives from ConatusError, ValueError

An option has an invalid value (scheme, backend, method...); close names are suggested.

SymmetryError

Derives from ConatusError, ValueError

Inconsistent symmetry declaration.

SymmetryBreakingError

Derives from SymmetryError

A term does not have the parity required by the declared subspace.

InputTypeError

Derives from ConatusError, TypeError

An argument has the wrong type (a Parameter, a Field, a number was expected...).

DtypeError

Derives from InputTypeError

Real/complex (dtype) mismatch; conversions are never implicit.

TensorError

Derives from InputTypeError

Tensor signatures do not match (scalar vs vector, different coordinate systems).

ConvergenceError

Derives from ConatusError, RuntimeError

An iteration did not reach its declared tolerance within its declared budget.

NewtonNotConverged

Derives from ConvergenceError

Newton did not reach the declared tolerance within the declared number of iterations.

NumericalError

Derives from ConatusError, ArithmeticError

A computed state is not finite (NaN or inf): a time integration blew up.
Raised by the finite-state check of the time steppers (``check_finite=``).

UnderResolvedWarning

Derives from UserWarning

A running simulation is under-resolved: the relative spectral tail of an unknown along a
direction exceeds the declared ``RUN_TAIL_TOL`` (measured at the finite-state check; warned
once per run and recorded by ``explain()``).

IllPosedWarning

Derives from UserWarning

An implicit term makes the initial-value problem ill-posed: its leading-order growth rate
increases without bound with the wavenumber (backward diffusion, a negative viscosity),
detected when the model is compiled and named with the term.

InitialDataWarning

Derives from UserWarning

Callable initial data are not fully resolved: their relative spectral tail beyond the
resolution (sampled on twice the grid) lies between ``INITIAL_TAIL_TOL`` and the refusal level
``INITIAL_TAIL_REFUSE`` (a coarse ``N`` of a resolution study); warned once per
``initial(...)`` call and recorded by ``explain()``.

BackendError

Derives from ConatusError, RuntimeError

The requested backend (GPU, compiled core) is not available here.

MissingDependencyError

Derives from BackendError, ImportError

An optional package or the compiled core is missing.

MissingFileError

Derives from ConatusError, FileNotFoundError

A file to read (an output, a checkpoint) does not exist, or is a directory. Derives from
``FileNotFoundError``, which these reads raised before.

UnsupportedError

Derives from ConatusError, NotImplementedError

Declared in the IR but not implemented (yet) for this case.

AmbiguousNameError

Derives from ConatusError, AttributeError

A name means two different things (two modules export it); use one of the explicit names.

Derives from ``AttributeError`` because it is raised by a module attribute lookup
(``conatus.expert.record``), so ``hasattr`` and introspection keep their protocol.

ResolutionWarning

Derives from UserWarning

A returned result is under-resolved by a declared measure:
the mode an eigenvalue result selects has its energy in the last coefficients, a Floquet-Hill
mode in its outermost harmonics. Raised as a warning, never instead of the result: the same
sentence is in the result and its ``explain()``. Not an error class (``warnings.warn``).

CorrectnessWarning

Derives from UserWarning

The returned answer may not be the one the call meant: it is about another base state,
another group of modes, or a choice the call did not declare. Shown under Python's default
filters wherever it is raised (never a ``DeprecationWarning``, which Python hides outside
``__main__``); the result is still returned. ``explain()`` keeps part of it only (the base
residual in ``lin.explain()``, the group in the result's header, the growth rule "inferred
from the name";
Where the message says "refused in v0.2", the same call raises from v0.2.

BaseStateWarning

Derives from CorrectnessWarning

A linearization about a base state that is not a steady solution: its steady residual
exceeds ``BASE_RESIDUAL_TOL`` and ``base_residual='accept'`` was not given, so the modes are
not the normal modes of a flow that exists (accepted in v0.1, refused in v0.2).

GroupWarning

Derives from CorrectnessWarning

An eigenvalue call without a group (no ``k=`` on a periodic model, no ``m=``/``kz=``/
``ell=`` on a curvilinear one) solved one group only (k = 0, or the first group): the modes
of every other wavenumber are absent from the result (required in v0.2).

DefaultChoiceWarning

Derives from CorrectnessWarning

A choice that decides the answer was left out and the v0.1 default or guess was used: the
growth rule of an eigenvalue guessed from its name (``m.eigenvalue("c")`` ranks by Im c), the
top condition of ``this case`` (no-slip). Declare it; required from v0.2.

ExperimentalWarning

Derives from UserWarning

A feature of the experimental list was used (once per feature and process): it is shipped and
tested, but not promised: its API and defaults may change in a minor release without a
deprecation cycle, and some of its claims rest on fewer measurements. The list:
``conatus._experimental.EXPERIMENTAL`` and the guide page "Experimental features". Silence it
with ``warnings.filterwarnings("ignore", category=cn.errors.ExperimentalWarning)``.