PySCF: Python-based Simulations of Chemistry Framework

2.12.1 · active · verified Thu Apr 16

PySCF is an open-source, Python-based framework for *ab initio* quantum chemistry simulations. It offers a comprehensive suite of electronic structure methods, including Hartree-Fock, Density Functional Theory (DFT), MP2, Coupled Cluster, and various multi-reference methods, for both molecular and periodic systems. The library is actively developed, with version 2.12.1 being the current stable release, and minor versions released roughly every 3-4 months, indicating a robust and ongoing development cycle.

Common errors

```
ZeroDivisionError: division by zero
```
cause This error often occurs in post-Hartree-Fock calculations (e.g., CCSD(T)) when using minimal basis sets (e.g., STO-3G) where the number of virtual orbitals (specifically alpha virtual orbitals) becomes zero, leading to an attempted division by zero in certain energy expressions.

fix Use a larger basis set (e.g., a double-zeta or triple-zeta quality basis set like 6-31g, def2-svp, or cc-pvdz). Minimal basis sets are generally not suitable for correlated methods as they lack the flexibility to describe electron correlation.
```
ImportError: numpy.core.multiarray failed to import
```
cause This typically indicates a binary incompatibility (ABI break) between the installed PySCF package (or its compiled C extensions) and the installed NumPy version. NumPy 2.0 introduced significant ABI changes.

fix Ensure that PySCF and NumPy are compatible. The most robust solution is to create a new Python environment, install NumPy first (preferably the latest compatible version), and then install PySCF: `conda create -n pyscf_env python=3.x numpy scipy h5py` then `conda activate pyscf_env` then `pip install pyscf`.
```
[UNEXPECTED BEHAVIOR] Density fitted TDA is extremely slow.
```
cause While density fitting (DF) generally speeds up calculations, specific combinations of methods and systems can sometimes lead to suboptimal performance, or even slower execution, particularly for certain linear response methods like TDA (Time-Dependent Adiabatic approximation) with DF.

fix Consult the PySCF documentation or GitHub issues for known workarounds or specific auxiliary basis set recommendations for your system. If possible, try disabling density fitting for that particular step or exploring alternative implementations if available within PySCF for your specific calculation type.

Warnings

breaking PySCF versions prior to 2.6.1 and 2.12.1 may have compatibility issues with NumPy 2.x due to significant API, ABI, and type promotion changes in NumPy 2.0. This can lead to `ImportError` or unexpected numerical behavior.
Fix: Upgrade PySCF to version 2.12.1 or newer. If issues persist, reinstall PySCF in an environment with your target NumPy version already installed (`pip install --no-cache-dir --force-reinstall pyscf`).
gotcha When modifying attributes of a `gto.Mole` object (e.g., `mol.atom`, `mol.basis`, `mol.charge`) after its initial creation, you must call `mol.build()` again for the changes to be applied and internal data structures to be refreshed.
Fix: Always call `mol.build()` after directly changing any attributes of a `gto.Mole` or `gto.Cell` instance. The `gto.M()` shortcut implicitly calls `build()`.
gotcha In SCF calculations, particularly with large or diffuse basis sets, linear dependencies in the atomic orbital basis can cause convergence issues or failures with the default generalized eigenvalue solver (SciPy's `eigh`).
Fix: Apply linear dependency removal using `mf.apply(scf.addons.remove_linear_dep_)` or enable partial Cholesky orthonormalization. For example: `mf = scf.RHF(mol).apply(scf.addons.remove_linear_dep_).run()`
gotcha Many PySCF functions, especially post-SCF methods, assume integer occupations. Combining them with mean-field calculations that utilize smearing (e.g., Fermi-Dirac smearing for metals) may lead to unexpected results or errors.
Fix: Carefully review the documentation for specific post-SCF methods when using smearing. If possible, avoid smearing for molecular systems or when subsequent methods explicitly require integer occupations.

Install

pip install pyscf Stable release
pip install pyscf[all] Install with all extensions (e.g., dispersion, dmrgscf)

Imports

gto
```
from pyscf import gto
```
Commonly imported module for Gaussian Type Orbitals, used to define molecular systems.
scf
```
from pyscf import scf
```
Module for Self-Consistent Field methods like Hartree-Fock and DFT.
cc
```
from pyscf import cc
```
Module for Coupled Cluster methods.
M
wrong:
```
mol = pyscf.Mole(atom='...').build()
```
correct:
```
mol = gto.M(atom='O 0 0 0; H 0 1 0; H 0 0 1', basis='ccpvdz')
```
While `pyscf.Mole().build()` works, `gto.M()` or `pyscf.M()` is a more concise and common shortcut for initializing a molecule.

Quickstart

This quickstart defines a water molecule using the `gto` module and then performs a Restricted Hartree-Fock (RHF) calculation using the `scf` module. It demonstrates the basic workflow of defining a system and running a mean-field calculation, printing the total energy.

from pyscf import gto, scf

# Define a molecule (e.g., Water)
mol = gto.M(
    atom = 'O 0 0 0; H 0 0.757 0.587; H 0 -0.757 0.587',
    basis = 'sto-3g')

# Perform a Restricted Hartree-Fock (RHF) calculation
mf = scf.RHF(mol).run()

# Print the RHF energy
print(f'RHF Energy: {mf.e_tot} Hartree')

view raw JSON →