Skip to content

Outcome: resolved settings, warnings, errors

Every output says what the calculation decided and, if it failed, why, in the same fields whichever program produced it. warnings, error and record are on ProgramOutput and on each Frame; resolved only on ProgramOutput. The vocabularies are in Conventions.

qcdata.Resolved

The settings a calculation actually used.

Attributes:

Name Type Description
settings FreeDict

The program's complete settings tree with every "auto" replaced, in the shape of ProgramInput.keywords. Passed back as keywords, it reproduces the run. Memory- and backend-dependent choices that can change numbers (DF storage, precision per card class) appear here resolved.

reasons dict[str, str]

Why each automatic choice was made, keyed by dotted settings path ("grid.xc": "calctype hessian: a finer grid").

deferred list[str]

In a plan only: dotted paths of settings left "auto" because the run decides them ("jk.df_storage" from the free memory when the SCF starts). A finished output's resolved settings have every "auto" replaced and nothing deferred.

qcdata.ProgramWarning

Something the program wants the caller to know about a calculation that ran.

Attributes:

Name Type Description
code str

A stable snake_case code: one the conventions share (loosely_converged) or one the program defines and documents.

message str

A human-readable explanation.

path str | None

The settings key the warning concerns, as a dotted path (scf.max_iter), if any.

qcdata.ErrorInfo

A structured description of a failure.

The Python traceback stays in ProgramOutput.traceback; this is what a caller branches on.

Attributes:

Name Type Description
kind ErrorKind

The kind of failure.

message str

A human-readable explanation.

code str | None

A stable snake_case code that refines kind: one the conventions share (scf_not_converged, host_memory) or one the program defines and documents (max_iter, energy_rose, not_first_order_saddle). Callers branch on it instead of parsing message.

program str | None

The subprogram that failed (kind program), or the program that failed when it is not the top-level one.

cause ErrorInfo | None

The subprogram's own error, for kind program: "the gradient failed because the SCF did not converge" stays structured through every level.

details FreeDict

Structured facts about the failure, as plain JSON, so callers need not parse message. The conventions name the keys of shared codes: required_gib and available_gib for host_memory and device_memory, when the program knows them, in the memory keyword's terms: the memory_gib (device_memory_gib) with which the calculation would fit, and the one it ran with (GiB).

qcdata.ErrorKind

Why a calculation failed, in one vocabulary across programs.

Attributes:

Name Type Description
input

Settings or a structure the program cannot run as given (an unknown key, a bad value, an unknown basis set or method).

unsupported

A valid request the program does not implement, or a setting it cannot honour that would change the result.

convergence

An iterative procedure (SCF, response equations, an optimization) did not converge; the results reached are attached.

numerical

A numerical failure: non-finite values, singular matrices.

resource

Not enough memory, disk, or another resource as set up.

backend

The hardware backend failed (no usable GPU, a device error).

program

A subprogram failed; ErrorInfo.cause holds its error.

timeout

The calculation ran out of time (set by the runner).

stopped

The program stopped on request at one of its steps (a runner's stop, which the program sees as ctx.stop_requested()); the partial output it reached is attached. Not a fault of the calculation, so a runner never stores a stopped output and a store never reuses one.

environment

The program could not be run at all: not installed, no licence, the process died (set by the runner).

internal

A failure nobody anticipated: a bug (an exception other than ProgramError, a broken invariant, a crash), or a failure no rule classifies (an unexplained exit, unreadable output). A failure a program anticipates takes the kind that fits it.