Skip to main content
Pre-release

This release is a pre-release and may not be stable for production use.

qccodec

image image image CI

Translates qcdata inputs into native program inputs and parses program outputs back into qcdata objects, one codec per program.

Documentation, including a copy-and-paste example script for every program and calculation type: qccodec.docs.afh.org

The QC Suite

These packages work together to make quantum chemistry fast, structured, and interoperable.

  • qcref - Reference data for computational chemistry: CODATA physical constants, conversion factors, a periodic table, and solvent properties, each value with its source.
  • qcdata - Data structures for quantum chemistry inputs and results, with Jupyter visualizations. Documentation
  • qcinf - Cheminformatics algorithms and structure utilities for qcdata structures.
  • qccodec - Translates qcdata inputs into native program inputs and parses program outputs back into qcdata objects, one codec per program. Documentation
  • qccompute - Runs programs on qcdata inputs: one input or many, in process or in workers, with a calculation store; external programs come with qccompute[qccodec]. Documentation
  • BigChem - Distributed execution of qccompute calculations across clusters of computers or the cloud.
  • ChemCloud - A web application and Python client that expose a BigChem cluster securely over the internet.

✨ Basic Usage

Every codec is also a program qccompute runs by name: qccodec registers it under the qccompute.programs entry points, and runs the program in a scratch directory with its output captured, a deadline, and its threads and GPUs from the runner.

python -m pip install qccompute[qccodec]   # qccompute runs, qccodec brings the programs
from qcdata import CalcType, Model, ProgramInput, Structure
from qccompute import compute

prog_input = ProgramInput(
    program="psi4",
    calctype=CalcType.gradient,
    structure=Structure(
        symbols=["O", "H", "H"],
        geometry=[[0.0, 0.0, 0.0], [0.524, 1.687, 0.48], [1.146, -0.45, -1.354]],
    ),
    model=Model(method="wb97x-d", basis="def2-svp"),
    keywords={"d_convergence": 1e-8},  # Psi4's own option names
)
output = compute(prog_input)
print(output.results.energy, output.results.gradient)

Decode output you already have, from Python or the command line:

from pathlib import Path
from qccodec import decode

data = decode("terachem", "hessian", stdout=Path("tc.out").read_text())
data.energy, data.hessian, data.vibrational_analysis
qccodec terachem hessian tc.out > data.json

See Decoding program output for directories, failed calculations, and encoding without running.

Supported programs

Each program has a documentation page and a runnable example script for every calculation type in examples/.

program Calculation types Notes
crest energy, gradient, hessian, optimization, conformer_search GFN-xTB and GFN-FF built in
dftbplus energy, gradient, hessian, optimization DFTB3, SCC-DFTB, DFTB, and xTB; parameter-set settings from qcref
geometric optimization, transition_state, irc Drives any gradient program (qccodec[geometric])
sella optimization, transition_state, irc Drives any gradient program; optional Hessian program (qccodec[sella])
orca energy, gradient, hessian, optimization, transition_state
psi4 energy, gradient, hessian, optimization, transition_state Any Psi4 method; point charges for QM/MM
terachem energy, gradient, hessian, optimization GPU quantum chemistry
terachem-fe, terachem-pbs energy, gradient TeraChem servers through tcpb (qccodec[tcpb])
xtb energy, gradient, hessian, optimization GFN0/1/2-xTB, GFN-FF, g-xTB; point charges for QM/MM
tblite energy, gradient GFN1/GFN2/IPEA1-xTB as a Python library
aimnet2 energy, gradient, hessian AIMNet2 machine-learned potentials
fairchem energy, gradient, hessian UMA and eSEN (gated weights)
mace energy, gradient, hessian MACE-OFF, MACE-MP, MACE-OMOL, custom models
orb energy, gradient Orb v3 and OrbMol
torchani energy, gradient, hessian ANI-2x, ANI-1ccx, ...

The last six run in the calling Python process: install the library next to qccompute (for example pip install tblite) instead of putting a program on PATH. Run any of them under geometric or sella for optimizations and transition states.

To support a new program, see Writing a codec and the step-by-step walkthrough in CONTRIBUTING.md.

Contributing

See CONTRIBUTING.md for development setup, the pre-commit workflow, running tests, and the release process.

If there's data you'd like parsed from output files or a program you'd like supported, open an issue describing the data and include an example output file, like this.

Optional dependencies

Optional integrations install with qccodec[geometric], qccodec[sella], or qccodec[tcpb]. To run any program from ASE-based tools, see ASE workflows. The tblite and machine-learned-potential codecs need their own libraries, installed separately (several of them, such as mace-torch and fairchem-core, cannot share an environment). Every library is imported only when a calculation is invoked.

Metadata

Release files for qccodec 0.22.0a1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for qccodec 0.22.0a1
File Size Uploaded Provenance Actions
qccodec-0.22.0a1.tar.gz 1.1 MB With provenance Details for qccodec-0.22.0a1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for qccodec 0.22.0a1
File Interpreter ABI Platform Actions
qccodec-0.22.0a1-py3-none-any.whl Python 3 none any Details for qccodec-0.22.0a1-py3-none-any.whl

Total release size: 1.2 MB

Release files / qccodec-0.22.0a1.tar.gz

Download URL qccodec-0.22.0a1.tar.gz
Size 1.1 MB
Tags Source
SHA-256 checksum
How to use checksums
68f3770055587613f3c86f6c2e8ed98353891ade162da994c055612c1f82607e
BLAKE2b-256 checksum
How to use checksums
4c3f477e4e6fb521aff379c111c9aa6970f669560bfd8a573a9779f462976f4d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Release files / qccodec-0.22.0a1-py3-none-any.whl

Download URL qccodec-0.22.0a1-py3-none-any.whl
Size 125.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
ebcb7865b8392881839f26060a1928f4e3f321f24fbbdcdb007d84f1517afc85
BLAKE2b-256 checksum
How to use checksums
d5d6f2e6ded999ecd5bd72b2c541c6864d6d8bf58a07d6fe59d88973025a4457
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

Security for qccodec 0.22.0a1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for qccodec-0.22.0a1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 17, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release
Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page