Skip to main content

Open Computational Chemistry (OCC)

Build & Test PyPI version PyPI Downloads Zenodo DOI Paper DOI

A next-generation quantum chemistry and crystallography program and library, designed for modern computational workflows.

Note: OCC is in active development and undergoes frequent changes. The API and features are not yet stable.

Installation

From PyPI

The easiest way to install OCC is via pip:

pip install occpy

Supported Python versions:

  • Python 3.10, 3.11, 3.12, 3.13

Pre-built wheels are available for:

  • Linux (x86_64)
  • macOS (x86_64 and ARM64/Apple Silicon via universal2 wheels)

Features

Quantum Chemistry

OCC provides comprehensive functionality for ground-state single-point calculations:

  • Electronic Structure Methods

    • Hartree-Fock (Restricted, Unrestricted, and General Spinorbitals)
    • Density-Functional Theory (Restricted & Unrestricted)
      • Supported approximations: LDA, GGA, meta-GGA
      • Global hybrid functionals (range-separated support planned)
    • Density fitting (RI-JK) with auxiliary basis sets
    • GFN2-xTB semi-empirical tight-binding (molecular + periodic; see below)
    • Implicit solvation: SMD, and openCOSMO-RS 24a (occ cosmo-rs, or occ cg --solvation-model cosmo-rs); CPCM-X for xTB. No solvent segment ensembles are shipped: compute them with occ cosmo-rs <solvent>.xyz --write-segments <solvent>.json, or give a solvent geometry directly with --solvent-geometry
    • XDM dispersion model
    • D4 (DFT-D4) dispersion correction
  • Property Calculations

    • Molecular and atomic multipole moments (up to hexadecapole)
    • Electron density, Electrostatic potential
    • CHELPG charges
    • Isosurfaces, generation of volumetric data and more...

Crystal Structure Analysis

  • CIF file processing (via gemmi)
  • Advanced periodic analysis:
    • Fast periodic bond detection
    • Symmetry-unique molecule generation
    • Dimer identification
  • Energy calculations:
    • CrystalExplorer model energies
    • Automatic direct space lattice energy summation
    • Wolf summation for neutral molecular crystals
  • Surface analysis:
    • Hirshfeld surfaces
    • Promolecule surfaces

GFN2-xTB

OCC ships a native C++ implementation of the GFN2-xTB semi-empirical tight-binding method (Bannwarth, Ehlers, Grimme, J. Chem. Theory Comput. 15, 1652 (2019), doi:10.1021/acs.jctc.8b01176). The implementation was developed with reference to Grimme's xTB and the tblite reference implementation (Apache-2.0 / LGPL-3.0+), and uses the published GFN2-xTB parameter set (bundled in share/xtb/gfn2.json).

Available now

  • Molecular SCC: full GFN2 with CAMM multipole AES, on-site polarisation, third-order, and native D4 dispersion -- agrees with xTB to single uHa on small molecules.
  • Periodic SCC (Gamma-only and Monkhorst-Pack k-point sampling) on real molecular crystals, with multipole AES, Ewald-summed gamma, and lattice-summed D4.
  • Analytical molecular gradient, with or without multipoles, validated to 1e-5 Ha/Bohr against finite differences of the energy; numerical Hessian for frequencies.
  • Implicit solvation via CPCM-X and SMD-xTB.
  • Bindings via the XtbCalculator class in Python (nanobind) and JS/WASM (emscripten/embind).

Current limitations

  • Periodic gradient and crystal-cell optimisation are not yet wired up.
  • Open-shell GFN2 (and GFN1/GFN0) are out of scope for v1.
  • Periodic energies on dense molecular crystals are ~0.4-0.6 mHa/atom too bound versus tblite (missing WSC-image averaging in the gamma build is the leading suspect).

Additional Features

  • Spherical harmonic transforms (FFT-based)
  • Molecular point group detection
  • File format support:
    • Gaussian fchk files (read/write)
    • Molden files
    • NumPy .npy arrays (write)
    • QCSchema JSON
    • Basic Gaussian input files
  • Geometric algorithms:
    • Marching cubes
    • Morton codes for linear-hashed octrees
  • Electronegativity equilibration method for charges
  • Python bindings via nanobind

Python API Examples

import occpy
from occpy import Crystal, Molecule, AOBasis, HartreeFock, DFT
from occpy import SpinorbitalKind

# Set up basic configuration
occpy.set_log_level(occpy.LogLevel.WARN)  # Configure logging level
# occpy.set_data_directory("/path/to/basis/sets")  # Optional: Set basis set path

# Load molecule from XYZ file
mol = Molecule.from_xyz_file("h2o.xyz")

# Basic Restricted Hartree-Fock calculation
basis = AOBasis.load(mol.atoms(), "6-31G")
hf = HartreeFock(basis)
scf = hf.scf()
energy = scf.run()
wfn = scf.wavefunction()

# DFT calculation
dft = DFT("B3LYP", basis)
ks = dft.scf(SpinorbitalKind.Unrestricted)
ks.set_charge_multiplicity(0, 1)
energy = ks.run()

# Crystal structure analysis
crystal = Crystal.from_cif_file("structure.cif")
dimers = crystal.symmetry_unique_dimers(10.0)  # Get unique dimers within 10 A

For more examples and detailed API documentation, please refer to the documentation.

Build from Source

Prerequisites

  • C++17 compliant compiler (GCC 10+ recommended)
  • CMake 3.15+
  • Ninja (recommended) or Make

Dependencies

OCC uses modern C++ libraries to provide its functionality:

Library Version Description
CLI11 2.4.2 Command line parser
Eigen3 3.4.0+ Linear algebra
fmt 11.0.2 String formatting
gemmi 0.6.5 Crystallographic file handling
LBFGS++ master Optimization algorithms
libcint 6.1.2 Gaussian integrals
libxc 6.2.2 Exchange-correlation functionals
nlohmann/json 3.11.3 JSON handling
scnlib 4.0.1 String parsing
spdlog 1.15.0 Logging
unordered_dense 4.5.0 Hash containers

Optional dependencies:

  • nanobind (2.4.0) - For Python bindings

Most dependencies are automatically handled through CPM. System-installed versions of Eigen3 and libxc can be used if available.

OCC's geometry optimization implementation for molecules made significant use of the code and documentation from pyberny - the files in the opt submodule are therefore subject to the MPL license.

Build Instructions

  1. Clone the repository:

    git clone https://github.com/peterspackman/occ.git
    cd occ
    
  2. Configure dependency caching (recommended):

    export CPM_SOURCE_CACHE="$HOME/.cache/cpm"
    
  3. Build with CMake:

    mkdir build && cd build
    
    # Using system dependencies (if available)
    cmake .. -GNinja
    
    # OR download all dependencies
    cmake .. -GNinja -DUSE_SYSTEM_LIBXC=OFF -DUSE_SYSTEM_EIGEN=OFF
    
    # Build the executable
    ninja occ
    

CMake Options

  • USE_SYSTEM_LIBXC: Use system-installed libxc (default: ON)
  • USE_SYSTEM_EIGEN: Use system-installed Eigen3 (default: ON)
  • WITH_PYTHON_BINDINGS: Build Python bindings (default: OFF)
  • USE_MLX: Enable MLX integration (default: OFF)
  • USE_QCINT: Use QCInt instead of libcint (default: OFF)
  • ENABLE_HOST_OPT: Enable host-specific optimizations (default: OFF)

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Citation

If you use OCC in your research, please cite the appropriate papers for all functionals, methods etc. you use, along with the citations for the core dependencies here.

If you use the GFN2-xTB implementation, cite:

  • C. Bannwarth, S. Ehlers, S. Grimme, GFN2-xTB -- An Accurate and Broadly Parametrized Self-Consistent Tight-Binding Quantum Chemical Method with Multipole Electrostatics and Density-Dependent Dispersion Contributions, J. Chem. Theory Comput. 15, 1652-1671 (2019). doi:10.1021/acs.jctc.8b01176
  • E. Caldeweyher, S. Ehlers, S. Grimme et al., A generally applicable atomic-charge dependent London dispersion correction, J. Chem. Phys. 150, 154122 (2019). doi:10.1063/1.5090222

The OCC implementation of GFN2-xTB is independent of, but was developed with reference to, the tblite project.

If you use the openCOSMO-RS solvation model (occ cosmo-rs, or occ cg --solvation-model cosmo-rs), cite:

  • S. Müller, T. Nevolianis, M. Garcia-Ratés, C. Riplinger, K. Leonhard, I. Smirnova, Predicting solvation free energies for neutral molecules in any solvent with openCOSMO-RS, Fluid Phase Equilibria 589, 114250 (2025). doi:10.1016/j.fluid.2024.114250
  • A. Grigorash, S. Müller, P. Paricaud, E. H. Stenby, I. Smirnova, W. Yan, A comprehensive approach to incorporating intermolecular dispersion into the openCOSMO-RS, Chemical Engineering Science 309, 121425 (2025). doi:10.1016/j.ces.2025.121425

The OCC implementation uses the published 24a parameter set and is independent of, but was developed with reference to, the openCOSMO-RS_py project.

Metadata

Release files for occpy 0.9.6

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

Built distributions (wheels)

Table of built distributions (wheels) for occpy 0.9.6
File Actions
occpy-0.9.6-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 abi3 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for occpy-0.9.6-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
occpy-0.9.6-cp312-abi3-macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 11.0+ ARM64 Details for occpy-0.9.6-cp312-abi3-macosx_11_0_arm64.whl
occpy-0.9.6-cp312-abi3-macosx_10_15_universal2.whl CPython 3.12 abi3 macOS 10.15+ universal2 (ARM64, x86-64) Details for occpy-0.9.6-cp312-abi3-macosx_10_15_universal2.whl
occpy-0.9.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.11 CPython 3.11 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for occpy-0.9.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
occpy-0.9.6-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for occpy-0.9.6-cp311-cp311-macosx_11_0_arm64.whl
occpy-0.9.6-cp311-cp311-macosx_10_15_universal2.whl CPython 3.11 CPython 3.11 macOS 10.15+ universal2 (ARM64, x86-64) Details for occpy-0.9.6-cp311-cp311-macosx_10_15_universal2.whl
occpy-0.9.6-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.28+ x86-64, Linux glibc 2.27+ x86-64 Details for occpy-0.9.6-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
occpy-0.9.6-cp310-cp310-macosx_11_0_arm64.whl CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details for occpy-0.9.6-cp310-cp310-macosx_11_0_arm64.whl
occpy-0.9.6-cp310-cp310-macosx_10_15_universal2.whl CPython 3.10 CPython 3.10 macOS 10.15+ universal2 (ARM64, x86-64) Details for occpy-0.9.6-cp310-cp310-macosx_10_15_universal2.whl

Total release size: 416.4 MB

Release files / occpy-0.9.6-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL occpy-0.9.6-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 47.5 MB
Tags CPython 3.12 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64 abi3
SHA-256 checksum
How to use checksums
d7e13962d35a6fa23ddf87a4219fd973e0dd9528d0565083172d778b84300133
BLAKE2b-256 checksum
How to use checksums
436e2fba204099e8cd2104a676403cfd341c35b6d68617c8982d08b26345e51d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp312-abi3-macosx_11_0_arm64.whl

Download URL occpy-0.9.6-cp312-abi3-macosx_11_0_arm64.whl
Size 30.0 MB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
707adaf4a4aca9f516539ab7081beca997828beb39aa32fbdcadab74aaf80768
BLAKE2b-256 checksum
How to use checksums
f15d3f6ce7df3025432c270c8bc89e424f0260b4222edb3b18107d1e75bd7c2e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp312-abi3-macosx_10_15_universal2.whl

Download URL occpy-0.9.6-cp312-abi3-macosx_10_15_universal2.whl
Size 61.4 MB
Tags CPython 3.12 abi3 macOS 10.15+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
24a5eb9c8af01046209f3087ad72ee2ca41d2336517e38513b151a69af98463e
BLAKE2b-256 checksum
How to use checksums
f037b7cafaf5d980823b1aefc6ca2b5926d182d5ab7a0fc89fc4948a20b38486
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL occpy-0.9.6-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 47.5 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
7e12e346a6e270830e4285d2be8b45c20aeb563fa57b6804b74e968baa7543ad
BLAKE2b-256 checksum
How to use checksums
eb6c12ed3e669541d068de71313a906f6d1dcd49c118e4cd7db5fce7988dbc62
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp311-cp311-macosx_11_0_arm64.whl

Download URL occpy-0.9.6-cp311-cp311-macosx_11_0_arm64.whl
Size 30.0 MB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
c28d1812b98f2ff328ff4819ddab9dd0eda73dee5bb3f8042aa8e7a47bd5b691
BLAKE2b-256 checksum
How to use checksums
131d10cc69d07ff12744c0084ffebc3a346870f909f8ff17cc4a29e532e76040
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp311-cp311-macosx_10_15_universal2.whl

Download URL occpy-0.9.6-cp311-cp311-macosx_10_15_universal2.whl
Size 61.4 MB
Tags CPython 3.11 macOS 10.15+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
3d67d4c9a883771d6d47f662e88739a16a9f1c114f650550dfdd33bb1ce95a66
BLAKE2b-256 checksum
How to use checksums
554c161061ce4525e14ad07d33c48c626a8fef538daae9a159c25654a2a4b85d
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

Download URL occpy-0.9.6-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 47.5 MB
Tags CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
de23329630edba08c99445a14012dd18f70a7221b09e1a50358a5013a83eb231
BLAKE2b-256 checksum
How to use checksums
8178b85fb71c152ac5cd7d8da32de04937362c58a76e91be9c8db64fcf4f2922
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp310-cp310-macosx_11_0_arm64.whl

Download URL occpy-0.9.6-cp310-cp310-macosx_11_0_arm64.whl
Size 30.0 MB
Tags CPython 3.10 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
6eea8043d27c2eee39ad77780734e27df496a87099f39b2ac298ffae6ae79795
BLAKE2b-256 checksum
How to use checksums
36778c7b21501fac41c4a9013ad53c5c4a09288d0939620749fb6446b31f31af
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Release files / occpy-0.9.6-cp310-cp310-macosx_10_15_universal2.whl

Download URL occpy-0.9.6-cp310-cp310-macosx_10_15_universal2.whl
Size 61.4 MB
Tags CPython 3.10 macOS 10.15+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
4e5674139dc5d8e73eae61e0a8f9c83542a77fe9e8da45a5fd4d16f70f063bf9
BLAKE2b-256 checksum
How to use checksums
c341656a411e74be063e9a0ac1f83da3a2b99f5a0180b7fc0786ebcf1428ae8e
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/6.1.0 CPython/3.12.8

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 Oct 30, 2026.

Transparency log

Security for occpy 0.9.6

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

All 9 files in this release have been uploaded with provenance metadata.

Select from 9 files

Attestation for occpy-0.9.6-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl

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 Oct 30, 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

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