QCSchema in Psi4

Psi4 can read and write QCSchema inputs/results, both through the command line and through the Python API. This is useful when you want a stable, machine-friendly interface for single-point energies, gradients, and related data. It is not appropriate for geometry optimizations, multi-stage computations, or accessing detailed data like integrals.

Psi4 supports both QCSchema v1 (qcelemental.models.v1.AtomicInput / qcelemental.models.v1.AtomicResult ) and QCSchema v2 (qcelemental.models.v2.AtomicInput / qcelemental.models.v2.AtomicResult).

Command-Line Usage

Use --qcschema to run an input file as QCSchema:

psi4 --qcschema input.json

If -o is omitted, Psi4 writes the result back to the same filename. To keep input and output separate, provide -o:

psi4 --qcschema input.json -o output.json

You can also request a specific output schema version:

psi4 --qcschema input.json --return-version 2 -o output.json

Minimal v2 Input (CLI or API)

{
  "schema_name": "qcschema_atomic_input",
  "schema_version": 2,
  "molecule": {
    "symbols": ["O", "H", "H"],
    "geometry": [
      0.0, 0.0, -0.124,
      0.0, -1.432, 0.986,
      0.0,  1.432, 0.986
    ]
  },
  "specification": {
    "driver": "energy",
    "model": {"method": "scf", "basis": "cc-pVDZ"},
    "keywords": {"scf_type": "df"},
    "protocols": {"stdout": true}
   }
 }

Python API: run_qcschema

Programmatic entry point is psi4.schema_wrapper.run_qcschema (also available as psi4.run_qcschema).

psi4.schema_wrapper.run_qcschema(input_data, clean=True, postclean=True, *, return_dict=False, return_version=-1, _allow_v1_dict_shim=False)

Run a quantum chemistry job specified by qcelemental.models.v2.AtomicInput (v1 or v2) input_data in PSI4.

Parameters:

  • input_data (Union[Dict[str, Any], AtomicInput, AtomicInput]) – Quantum chemistry job in either AtomicInput class or dictionary form.

  • clean (bool) – Reset global QCVariables, options, and scratch files to default state.

  • postclean (bool) – When False, remove the output file since absorbed into AtomicResult. When True, simply close the output file. True is useful when calling from a Psi4 session to avoid removing the parent Psi4’s output file.

  • return_dict (bool) – Returns a dict instead of qcelemental AtomicResult This is a workaround for Python 3.14 and QCSchema v1, perhaps temporary.

  • return_version (int) – The schema version to return. If -1, the input schema_version is used.

Return type:

Union[AtomicResult, AtomicResult, FailedOperation, FailedOperation]

Returns:

  • result – AtomicResult, FailedOperation, or Dict representation of any object type A QCSchema representation of the requested output, type depends on return_dict key.

    qcelemental.models.v1.AtomicResult, qcelemental.models.v2.AtomicResult

    Full record of quantum chemistry calculation, including output text. Returned upon job success.

    qcelemental.models.v1.FailedOperation, qcelemental.models.v2.FailedOperation,

    Record to diagnose calculation failure, including output text and input specification. Returned upon job failure.

    good_calc?

    raise_error

    return_dict

    output

    T

    F (def)

    F (def)

    AtomicResult object

    T

    T

    F (def)

    AtomicResult object

    T

    T

    T

    dict of AtomicResult

    T

    F (def)

    T

    dict of AtomicResult

    F

    F (def)

    F (def)

    FailedOperation object

    F

    T

    F (def)

    raises InputError (type encoded in FailedOp)

    F

    T

    T

    raises InputError (type encoded in FailedOp)

    F

    F (def)

    T

    dict of FailedOperation

    good_calc?

    input_data ver

    return_version

    return_dict

    output

    T

    1

    -1 (def) or 1

    F (def)

    v1.AtomicResult object (not avail. Py 3.14+)

    T

    1

    2

    F (def)

    v2.AtomicResult object

    T

    1

    -1 (def) or 1

    T

    dict of v1.AtomicResult

    T

    1

    2

    T

    dict of v2.AtomicResult

    T

    2

    -1 (def) or 2

    F (def)

    v2.AtomicResult object

    T

    2

    1

    F (def)

    v1.AtomicResult object (not avail. Py 3.14+)

    T

    2

    -1 (def) or 2

    T

    dict of v2.AtomicResult

    T

    2

    1

    T

    dict of v1.AtomicResult

    F

    1

    -1 (def) or 1

    F (def)

    v1.FailedOperation object (not avail. Py 3.14+) **

    F

    1

    2

    F (def)

    v2.FailedOperation object

    F

    1

    -1 (def) or 1

    T

    dict of v1.FailedOperation **

    F

    1

    2

    T

    dict of v2.FailedOperation

    F

    2

    -1 (def) or 2

    F (def)

    v2.FailedOperation object **

    F

    2

    1

    F (def)

    v1.FailedOperation object (not avail. Py 3.14+ )

    F

    2

    -1 (def) or 2

    T

    dict of v2.FailedOperation **

    F

    2

    1

    T

    dict of v1.FailedOperation

    ** F

    1, 2

    -1

    for errors before input ver detected, returns 2 if Py 3.14+ else 1

  • .. versionadded:: 1.11.0 – The return_version parameter was added. The return_dict parameter was added, perhaps temporarily.

Model return (default):

import pprint
import psi4

inp = {
    "schema_name": "qcschema_atomic_input",
    "schema_version": 2,
    "molecule": {
        "symbols": ["He", "He"],
        "geometry": [0.0, 0.0, -2.5, 0.0, 0.0, 2.5]
    },
    "specification": {
        "driver": "energy",
        "model": {"method": "scf", "basis": "cc-pVDZ"},
        "keywords": {"scf_type": "df"}
    }
}

ret = psi4.run_qcschema(inp)
print(ret.success)
print(ret.return_result)
pprint.pprint(ret.model_dump(), width=200)

Dictionary return:

ret = psi4.schema_wrapper.run_qcschema(inp, return_dict=True)
print(ret["success"])
print(ret["return_result"])
print(ret["extras"]["qcvars"]["SCF TOTAL ENERGY"])

Serialization Notes

  • For v1 model objects, use .dict() for Python dictionary or .json() for JSON.

  • For v2 model objects, use .model_dump() or .model_dump_json(), respectively.

  • If you request return_dict=True, you already have plain Python containers and can use json.dump(...) directly. Note that with Python 3.14 or later, you can only use QCSchema v1 with dictionaries, not Pydantic models, due to Pydantic restrictions. See the run_qcschema docstring for details.

Running Through QCEngine

QCEngine can run Psi4 as a backend using the same QCSchema payload.

import qcengine as qcng

inp = {
    "schema_name": "qcschema_atomic_input",
    "schema_version": 2,
    "molecule": {
        "symbols": ["O", "H", "H"],
        "geometry": [0.0, 0.0, -0.124, 0.0, -1.432, 0.986, 0.0, 1.432, 0.986],
    },
    "specification": {
        "driver": "energy",
        "model": {"method": "scf", "basis": "cc-pVDZ"},
        "keywords": {"scf_type": "df"},
    },
}

ret = qcng.compute(inp, "psi4", return_dict=True)
print(ret["success"])
print(ret["return_result"])

You may also pass return_version=1 or return_version=2 to control the output schema version.

Where to Find More Examples