Metadata-Version: 2.1
Name: occpy
Version: 0.9.3
Summary: A library for quantum chemistry
Author-Email: Peter Spackman <peterspackman@fastmail.com>
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: License :: OSI Approved :: GNU Lesser General Public License v3 or later (LGPLv3+)
Project-URL: Homepage, https://github.com/peterspackman/occ
Requires-Python: >=3.10
Requires-Dist: numpy>1.24.4
Description-Content-Type: text/markdown

# Open Computational Chemistry (OCC)
<img src="https://github.com/peterspackman/occ/raw/main/docs/static/occ.png" width=640/>

[![Build & Test](https://github.com/peterspackman/occ/actions/workflows/build_test.yml/badge.svg)](https://github.com/peterspackman/occ/actions/workflows/build_test.yml)
[![PyPI version](https://badge.fury.io/py/occpy.svg)](https://badge.fury.io/py/occpy)
[![PyPI Downloads](https://img.shields.io/pypi/dm/occpy)](https://pypi.org/project/occpy/)
[![Zenodo DOI](https://zenodo.org/badge/292276139.svg)](https://zenodo.org/doi/10.5281/zenodo.10703204)
[![Paper DOI](https://joss.theoj.org/papers/10.21105/joss.09609/status.svg)](https://doi.org/10.21105/joss.09609)

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:

```bash
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 via SMD, CPCM-X for xTB
  - 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](https://doi.org/10.1021/acs.jctc.8b01176)).
The implementation was developed with reference to Grimme's xTB and the
[tblite](https://github.com/tblite/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 (charge-only SCC variant), validated to
  5e-5 Ha/Bohr against finite differences; 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.
- The "multipole-on" analytical gradient still has a known ~1 mHa gap
  versus FD-of-energy from missing AO-multipole integral derivatives --
  the charge-only gradient is the production variant.
- 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

```python
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](docs_url_here).

## 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](https://github.com/CLIUtils/CLI11) | 2.4.2 | Command line parser |
| [Eigen3](https://eigen.tuxfamily.org/) | 3.4.0+ | Linear algebra |
| [fmt](https://github.com/fmtlib/fmt) | 11.0.2 | String formatting |
| [gemmi](https://gemmi.readthedocs.io/) | 0.6.5 | Crystallographic file handling |
| [LBFGS++](https://lbfgspp.statr.me/) | master | Optimization algorithms |
| [libcint](https://github.com/sunqm/libcint) | 6.1.2 | Gaussian integrals |
| [libxc](http://www.tddft.org/programs/libxc/) | 6.2.2 | Exchange-correlation functionals |
| [nlohmann/json](https://github.com/nlohmann/json) | 3.11.3 | JSON handling |
| [scnlib](https://github.com/eliaskosunen/scnlib) | 4.0.1 | String parsing |
| [spdlog](https://github.com/gabime/spdlog) | 1.15.0 | Logging |
| [unordered_dense](https://github.com/martinus/unordered_dense) | 4.5.0 | Hash containers |

Optional dependencies:
- [nanobind](https://github.com/wjakob/nanobind) (2.4.0) - For Python bindings

Most dependencies are automatically handled through [CPM](https://github.com/cpm-cmake/CPM.cmake). 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](https://github.com/jhrmnn/pyberny) - the files in the `opt` submodule are therefore subject to the MPL license.

### Build Instructions

1. Clone the repository:
   ```bash
   git clone https://github.com/peterspackman/occ.git
   cd occ
   ```

2. Configure dependency caching (recommended):
   ```bash
   export CPM_SOURCE_CACHE="$HOME/.cache/cpm"
   ```

3. Build with CMake:
   ```bash
   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](https://doi.org/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](https://doi.org/10.1063/1.5090222)

The OCC implementation of GFN2-xTB is independent of, but was developed
with reference to, the [tblite](https://github.com/tblite/tblite) project.
