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.

If you use the RINSE crystal descriptor (occ describe on a crystal structure, or Rinse in the Python and Lua bindings), cite the X-ray scattering factors it is built on:

  • D. Waasmaier, A. Kirfel, New analytical scattering-factor functions for free atoms and ions, Acta Cryst. A 51, 416-431 (1995). doi:10.1107/S0108767394013292
  • R. F. Stewart, E. R. Davidson, W. T. Simpson, Coherent X-Ray Scattering for the Hydrogen Atom in the Hydrogen Molecule, J. Chem. Phys. 42, 3175-3187 (1965). doi:10.1063/1.1696397
  • R. W. Grosse-Kunstleve, N. K. Sauter, N. W. Moriarty, P. D. Adams, The Computational Crystallography Toolbox: crystallographic algorithms in a reusable software framework, J. Appl. Cryst. 35, 126-136 (2002). doi:10.1107/S0021889801017824 -- the source of the five-Gaussian fit to the Stewart-Davidson-Simpson bonded hydrogen used for H.

The OCC implementation is a port of, and reproduces the descriptors and hashes of, the rinse-descriptor reference implementation by T. Fellowes, including its bundled PCA hash model.

Metadata

Release files for occpy 0.9.7

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.7
File Actions
occpy-0.9.7-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.12 abi3 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for occpy-0.9.7-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
occpy-0.9.7-cp312-abi3-macosx_11_0_arm64.whl CPython 3.12 abi3 macOS 11.0+ ARM64 Details for occpy-0.9.7-cp312-abi3-macosx_11_0_arm64.whl
occpy-0.9.7-cp312-abi3-macosx_10_15_universal2.whl CPython 3.12 abi3 macOS 10.15+ universal2 (ARM64, x86-64) Details for occpy-0.9.7-cp312-abi3-macosx_10_15_universal2.whl
occpy-0.9.7-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.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
occpy-0.9.7-cp311-cp311-macosx_11_0_arm64.whl CPython 3.11 CPython 3.11 macOS 11.0+ ARM64 Details for occpy-0.9.7-cp311-cp311-macosx_11_0_arm64.whl
occpy-0.9.7-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.7-cp311-cp311-macosx_10_15_universal2.whl
occpy-0.9.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl CPython 3.10 CPython 3.10 Linux glibc 2.27+ x86-64, Linux glibc 2.28+ x86-64 Details for occpy-0.9.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
occpy-0.9.7-cp310-cp310-macosx_11_0_arm64.whl CPython 3.10 CPython 3.10 macOS 11.0+ ARM64 Details for occpy-0.9.7-cp310-cp310-macosx_11_0_arm64.whl
occpy-0.9.7-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.7-cp310-cp310-macosx_10_15_universal2.whl

Total release size: 482.0 MB

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

Download URL occpy-0.9.7-cp312-abi3-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 54.0 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
5aa553721c8eccba606904d25800cffc9e5c73c3ac768d3f6bcd3341950342a5
BLAKE2b-256 checksum
How to use checksums
6f078863a77414ed46bd6c21dad04b1d8d72ec4c522632bc39ebd71267fdb0aa
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp312-abi3-macosx_11_0_arm64.whl
Size 34.3 MB
Tags CPython 3.12 abi3 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
3fed15103b8a80fc9ce45faee1817c20b2322abb9f19c99e550f8caf4520dc6b
BLAKE2b-256 checksum
How to use checksums
e6bc907ec84594129d77bee773c24c59b9961a733ac43c3d23971552f3446a97
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp312-abi3-macosx_10_15_universal2.whl
Size 72.4 MB
Tags CPython 3.12 abi3 macOS 10.15+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
25a3d2c261d736c226f915b811f8af5a4aaee508a8551ff1aa47099443ef59c4
BLAKE2b-256 checksum
How to use checksums
25c6c23046eef660e2a9e26fbc5e2be3143a1a528957c719154f456d72ed37e8
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp311-cp311-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 54.0 MB
Tags CPython 3.11 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
b29b02449b09543826e194cf689e1fc64e964ebc1b7a6047a6adb566378b234f
BLAKE2b-256 checksum
How to use checksums
1418054e96e957d402d00039fa955282ef6165824c3f4855ba4b3db7db66f436
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp311-cp311-macosx_11_0_arm64.whl
Size 34.3 MB
Tags CPython 3.11 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
35c16067e1856ba8323a8114eb2b12ca19145113e7bc33e8dc23799fbcf88914
BLAKE2b-256 checksum
How to use checksums
1913e75cff8d0583b9f20c875a0bdddf476f1984cc8546a547b771baae8f6ee8
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp311-cp311-macosx_10_15_universal2.whl
Size 72.4 MB
Tags CPython 3.11 macOS 10.15+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
efa2b77fad03ba5bd46780814b9e8e0be9f557db1eee8554b81e632c01eff572
BLAKE2b-256 checksum
How to use checksums
0a9435a903ecd0679280eb02fba2d2b09e8f6a1abcc271ed29730bdc40a34f60
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp310-cp310-manylinux_2_27_x86_64.manylinux_2_28_x86_64.whl
Size 54.0 MB
Tags CPython 3.10 Linux glibc 2.27+ x86-64 Linux glibc 2.28+ x86-64
SHA-256 checksum
How to use checksums
0ed93001d8e3de61e85e318aa564fd271fc867eb9b304144c62a72f856c70619
BLAKE2b-256 checksum
How to use checksums
cc0a6930f544bebb88513757da6b9b18fbe0c8b5d30494804ecff89f5d8d5183
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp310-cp310-macosx_11_0_arm64.whl
Size 34.3 MB
Tags CPython 3.10 macOS 11.0+ ARM64
SHA-256 checksum
How to use checksums
658dcc982d44d92803fe092f4722429dd8765003d82610acc758e3cfe76bd6b4
BLAKE2b-256 checksum
How to use checksums
03254ed473e67d06e11141314d495a706e89b99a491bd56542bf79e8e1ab9091
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 Nov 5, 2026.

Transparency log

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

Download URL occpy-0.9.7-cp310-cp310-macosx_10_15_universal2.whl
Size 72.4 MB
Tags CPython 3.10 macOS 10.15+ universal2 (ARM64, x86-64)
SHA-256 checksum
How to use checksums
514f83ab7e73dd3c67a67d2d0dd75947303e2f5660b357130213d23f4ef3b769
BLAKE2b-256 checksum
How to use checksums
30704fab3a87501f5d5cff75690c99d49fcf9930ddb56cb978fff0fd7c7247d4
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 Nov 5, 2026.

Transparency log

Security for occpy 0.9.7

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.7-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 Nov 5, 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