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

The current alphas are pre-releases, installed together:

uv pip install --prerelease=allow "qcdata==0.24.0a2" "qccompute[qccodec]==0.23.0a1" "qcstore==0.1.0a1"
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.0a3

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.0a3
File Size Uploaded Provenance Actions
qccodec-0.22.0a3.tar.gz 1.2 MB With provenance Details for qccodec-0.22.0a3.tar.gz

Built distribution (wheel)

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

Total release size: 1.3 MB

Release files / qccodec-0.22.0a3.tar.gz

Download URL qccodec-0.22.0a3.tar.gz
Size 1.2 MB
Tags Source
SHA-256 checksum
How to use checksums
487573e13a87f85b11238201fa1a9136f502081621510e180c5fbe4653e3f57b
BLAKE2b-256 checksum
How to use checksums
974fde883ca76171ebe82a8d8aaa29c7b784dc1db81d3c93db941d73eea12f3e
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.0a3-py3-none-any.whl

Download URL qccodec-0.22.0a3-py3-none-any.whl
Size 147.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
44688e73d3b7a4dcbacce4b56151978b7a2c7b0c00e17a5016ee68097c4b25a6
BLAKE2b-256 checksum
How to use checksums
2b55456db68ba7a50769c093416297bb95b60284823fb082fdf4f93ff690d68b
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.0a3

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.0a3.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