Errors¶
Every FastMACE error derives from FastMACEError.
errors ¶
FastMACE exceptions (SPEC §7.6 "Exceptions") and their message shape (§7.7 "Errors").
Every exception FastMACE raises derives from FastMACEError. Its message has
one shape, so that no traceback needs reading: what happened; why, in one or
two sentences; what to do next; where the record is (run.plan,
run.gate, metadata.json); and fastmace doctor for environment
problems. The CLI prints this message alone (§7.5).
This module imports nothing heavy: import fastmace imports neither torch
nor MACE, and the 1a modules that defined these classes re-export them.
FastMACEError ¶
Bases: Exception
Base class of every error FastMACE raises.
FastMACEError(what, why=None, next_step=None, record=None, environment=None);
a plain one-argument construction gives just what. Each class may set a
default next step, record location and environment flag; None takes the
class default.
Reason ¶
Bases: str
One refusal reason: the text, the §9.3 hard rule (None for a run request) and a stable code.
Reports and tests match code, never the text. Decisions use the same record. Plan task 5-T01's contract
(fastmace.planner.rules): rule is None or one of 1-15; with a rule, code is one of that
rule's codes (or rules.OVERRIDE_CODE for an overridden preference), and a rule's code never comes
without its number. rules.check_reason says what is wrong; the conformance suite calls it
(tests/cpu/test_rules_meta.py), the planner does not, so a reason costs nothing at run time.
PlanRefused ¶
Bases: FastMACEError, ValueError
The planner cannot plan this workload, or a run request the plan does not cover.
reasons lists every hard-constraint reason of the refusal at once (SPEC
§9.3): plain strings (1a) or Reason records. Raise through
PlanRefused.from_reasons, which picks SpeciesNotInSuperset when rule
2 is among them.
from_reasons
classmethod
¶
from_reasons(reasons, **parts)
One exception carrying every reason: SpeciesNotInSuperset if a reason has rule == 2.
SpeciesNotInSuperset ¶
Bases: PlanRefused
Rule 2: a species outside the ForceField's declared superset (SPEC §8.5), with every reason.
ChargeParityRefused ¶
Bases: PlanRefused
A transmutable set violates the charge and spin rule of SPEC §10.4: a move needs ΔZ − Δq even.
Raised by the planner through ChargeParityRefused.from_reasons with a reason coded
CHARGE_PARITY_CODE (3-T09); every other reason of the refusal comes with it.
ProcessConstraintError ¶
InputError ¶
Bases: FastMACEError, ValueError
The run's input cannot start: no plan or fallback candidate changes that, so it is raised at once.
FallbackExhausted ¶
Bases: PlanRefused
No fallback candidate passed validation (SPEC §9.4 step 5); revisions holds every tried plan.
revisions is the revision chain of the fallback, oldest first: the failed plan, then each
candidate tried, each with its reason. reasons are the refusal's, as for PlanRefused.
SubprocessRunnerError ¶
Bases: FastMACEError, RuntimeError
The subprocess runner's child failed, was killed or stalled (SPEC §8.7); never a hang.
exit_code is the child's (negative: killed by that signal; None: still running when it
was stopped), child_message its error message, and directory the hand-off directory,
kept after an error.
TemplateChangedError ¶
Bases: FastMACEError, RuntimeError
A cached converted model (opt-1 OPT-T06) changed after it was stored; it is never copied for a plan.
IsolationError ¶
Bases: FastMACEError, RuntimeError
An instance whose lease on a shared component was taken by another instance (SPEC §8.7).
component names the shared component, holder the instance that holds its lease now.
ReproducibilityError ¶
Bases: FastMACEError
A (backend, model family) failed qualification for reproducible=True (SPEC §9.3 rule 5).
blocking names the kernels or operators without a deterministic implementation. A plan that
asks for reproducible=True without a qualified family is refused by PlanRefused (rule 5),
not by this error.
GateFailed ¶
Bases: _GateError
The gate on the user's structure failed (SPEC §12.3); gate_record holds the comparison.
GateUnavailable ¶
Bases: _GateError
The gate's reference could not run on any allowed device (SPEC §12.3).
ModelElementError ¶
RestartMismatch ¶
Bases: FastMACEError
A restart's force-field identity differs, or its plan changed without allow_plan_change (§10.6).
CheckpointTrustError ¶
Bases: FastMACEError
A checkpoint would be unpickled without a matching SHA-256 or trusted=True (SPEC §7.6).
NonFiniteError ¶
Bases: FastMACEError
A non-finite energy or observable stopped the run (SPEC §9.6); it is never "fixed".
CellDivergedError ¶
Bases: FastMACEError
An NPT run's cell left the range its integrator record allows (3b-T07): V/V0 outside
[1 / max_volume_ratio, max_volume_ratio] or a cell vector longer than max_cell_length_A. The run
stops with a restart at the stop; step is the step whose cell was checked.
CellListTooLargeError ¶
Bases: FastMACEError, ValueError
A CPU neighbour search whose matscipy cell list would need more bins than memory allows (3b-T07).
HybridUnavailableError ¶
Bases: FastMACEError
The cuEq/OEq hybrid cannot be built in this process; reason says why (SPEC §9.4 falls back).
BackendError ¶
Bases: FastMACEError
The requested backend was not built as asked (missing package, failed conversion).
NaiveCueqError ¶
Bases: FastMACEError
cuEquivariance fell back to its naive kernels (MACE PR 1614; SPEC §9.2, §9.3 rule 6).
PolarUnavailableError ¶
OEqRuntimeError ¶
CacheLocationError ¶
RewriteError ¶
RewriteRefusedError ¶
Bases: RewriteError
An explicitly requested rewrite ("on") cannot be enabled; the message gives the reasons.
SelfCheckError ¶
RegistryError ¶
Bases: FastMACEError, RuntimeError
A persistent buffer without a policy, a restore whose buffer moved (SPEC §8.1), or two scheme records that
give one buffer different restart policies (4-T01b). fastmace.engine.registry re-exports it.
BaselineExportError ¶
ModelLicenceWarning ¶
Bases: UserWarning
The licence of a loaded model (SPEC §4.3: shown at load time).