Skip to content

Outputs

ProgramOutput is the core object that captures a QC program execution, including the exact input, the structured output payload at .results, logs, traceback information for failures, and ExecutionInfo at .execution. Producer identity belongs to .results.provenance.

qcdata.ProgramOutput

The core output object from a quantum chemistry calculation.

Success, logs, traceback, and execution come from OutputBase, shared with Frame.

Attributes:

Name Type Description
input_data InputType

The input data for the calculation. Any of qcdata.Inputs.

results DataType

Scientific data returned by the calculation, including output files. Any of qcdata.Data.

resolved Resolved | None

The settings the calculation actually used, with every "auto" replaced, and the reasons; passed back as keywords they reproduce the run.

failure classmethod

failure(
    input_data: InputType,
    error: ErrorInfo,
    *,
    results: Any = None,
    traceback: str | None = None,
    **fields: Any,
) -> ProgramOutput[InputType, Any]

A failed output of the right shape for its input's calculation type.

Programs return this instead of building empty results by hand: an optimization input needs OptimizationData results even when nothing ran.

Parameters:

Name Type Description Default
input_data InputType

The input that failed.

required
error ErrorInfo

Why it failed.

required
results Any

Partial results, if any; else empty results of the calctype's data type with the program's provenance.

None
traceback str | None

The failure's details; defaults to the error's message.

None
**fields Any

Other output fields (logs, execution, warnings, record).

{}

Returns:

Type Description
ProgramOutput[InputType, Any]

The failed output.

Source code in src/qcdata/models/outputs.py
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
@classmethod
def failure(
    cls,
    input_data: ProgramInputType,
    error: ErrorInfo,
    *,
    results: Any = None,
    traceback: str | None = None,
    **fields: Any,
) -> ProgramOutput[ProgramInputType, Any]:
    """A failed output of the right shape for its input's calculation type.

    Programs return this instead of building empty results by hand: an
    ``optimization`` input needs `OptimizationData` results even when nothing ran.

    Args:
        input_data: The input that failed.
        error: Why it failed.
        results: Partial results, if any; else empty results of the calctype's
            data type with the program's provenance.
        traceback: The failure's details; defaults to the error's message.
        **fields: Other output fields (``logs``, ``execution``, ``warnings``,
            ``record``).

    Returns:
        The failed output.
    """
    from .base_models import Provenance
    from .data import get_data_type
    from .inputs import ProgramInput as _ProgramInput

    if results is None:
        data_type = (
            get_data_type(input_data.calctype)
            if isinstance(input_data, _ProgramInput)
            else FileData
        )
        results = data_type(provenance=Provenance(program=input_data.program))
    return ProgramOutput(
        input_data=input_data,
        results=results,
        success=False,
        error=error,
        traceback=traceback or error.message,
        **fields,
    )

options: members: false

success, logs, traceback, and execution come from OutputBase, which ProgramOutput shares with Frame.

Canonical results field

Scientific models retain their Data names and can exist independently of an execution. Within ProgramOutput, that data is the calculation's results: use output.results.energy, output.results.gradient, or output.results.final_structure.

The results live in "results". The former name "data" is not accepted: a payload that uses it fails validation like any unknown field, and the .data attribute is gone.

The old Results and *Results classes, qcdata.models.results module, qcio import shim, stdout/files forwarding, and deprecated convenience helpers have been removed. Use ProgramOutput, *Data, logs, results.files, and explicit scientific attributes instead.

Input and result contract

The result type depends on the input, regardless of success or failure:

Input Result type
FileInput FileData only
Energy, gradient, Hessian ProgramInput SinglePointData
Optimization or transition-state ProgramInput OptimizationData
Conformer-search ProgramInput ConformerSearchData
Scan ProgramInput ScanData
IRC ProgramInput PathData
Path-optimization ProgramInput PathOptimizationData

Successful single-point calculations require the requested value; successful optimizations and IRCs require frames, scans require points, path optimizations require paths, and successful conformer searches require conformers. Failed calculations require a traceback and retain the corresponding scientific type, with empty or partial values allowed. Producer provenance is always required.

When deserializing, ProgramOutput uses the input contract to select the result model. Empty scientific payloads therefore retain their type when saved and reopened, including inside frames and scan points. No additional serialized type tag is needed. Explicit generic types must agree with the input contract.

input_data belongs on ProgramOutput, not inside results. Save the whole output when you need scientific values together with the requested calculation and execution context. Save a standalone data object when exchanging only scientific values and producer identity.

Migrating existing outputs

This is a breaking schema change with no automatic legacy-provenance loader:

  • Move provenance.program, provenance.program_version, and provenance.extras into results.provenance.
  • Move scratch_dir, wall_time, and hostname into execution; rename hostcpus to host_cpu and hostmem to host_mem_gib. Memory accepts fractional GiB. These renames have no compatibility aliases.
  • Remove the old top-level provenance field.
  • Use FileData(provenance=...) only with FileInput. For failed structured calculations, construct the corresponding scientific type, such as SinglePointData(provenance=...), and update generic annotations accordingly.
  • Apply the same migration to each nested trajectory output. Do not copy parent provenance or execution information to children.

Standalone structured data now also requires explicit provenance.

External callers must migrate too: qccodec should attach the parsed producer and version to the returned data; qccompute should supply execution and return the corresponding scientific data type even when a structured calculation fails without producing values.

Reconstructed frames

Parsers reconstruct frames from what a program saved (structures and energies, sometimes gradients). Such frames describe recovered scientific evaluations, which need not be separate process invocations, and carry no input of their own: the parent output's input describes the calculation. A frame's results holds whatever was recovered; missing an optional gradient does not by itself make a frame a failure.