pyscf

PySCF - Python-based Simulations of Chemistry Framework

Overview

PySCF is a pure-Python quantum chemistry package for molecular electronic-structure calculations.

When to Use PySCF vs. Other Tools

Scenario	Recommended Tool	Why
HF, DFT, or MP2 calculations in a Python workflow	PySCF	Native Python API, easy scripting
Methods requiring dispersion corrections, triple-zeta basis sets, or exotic DFT functionals	ORCA / Gaussian	Broader built-in functional and basis-set libraries
Periodic solids or plane-wave calculations	ASE + VASP / Quantum ESPRESSO / CP2K	PySCF is primarily molecular

Key rule: Use PySCF when you need HF/DFT/MP2 energies, geometries, or frequencies for molecules within a Python codebase.

Installation

uv pip install pyscf

Core Capabilities

1. Single-Point Energy

python scripts/run_calculation.py --molecule "H 0 0 0; H 0 0 0.74" --method HF --basis sto-3g --task energy

2. Geometry Optimization

python scripts/run_calculation.py --molecule "H 0 0 0; H 0 0 0.74" --method DFT:B3LYP --basis 6-31g --task opt

3. Vibrational Frequencies

python scripts/run_calculation.py --molecule "H 0 0 0; H 0 0 0.74" --method HF --basis sto-3g --task freq

Output

All results are printed as JSON to stdout.

Anti-Patterns (Do Not Do These)

• Do not use sto-3g for quantitative results. It is a minimal basis useful only for teaching or very rough guesses.
• Do not rely on default SCF settings for difficult systems. Strongly correlated or open-shell systems often need adjusted convergence helpers.
• Do not use closed-shell RHF for open-shell molecules without caution. Check the spin state; use ROHF or UHF when appropriate.
• Do not run vibrational frequencies on a geometry that is not well optimized. Frequencies are only meaningful at stationary points.

Best Practices

• Start with 6-31g(d) or def2-svp for reasonably accurate geometries and energies.
• Check SCF convergence; increase mf.max_cycle or use a level-shift if convergence is slow.
• For larger systems, enable density fitting (e.g., mf = scf.RHF(mol).density_fit()) to reduce cost.
• If the SCF converges to an unphysical state, run stability analysis (mf.stability()) and re-start.
• Always verify that an optimized geometry has no imaginary frequencies before using it for thermochemistry.
• For questions about the latest PySCF features, newly added methods, or version-specific syntax changes, use WebFetch on https://pyscf.org/manual.html before answering.

Common Errors and Fixes

Error / Symptom	Likely Cause	Fix
SCF does not converge	Bad initial guess, strong correlation, or charge distribution	Try mf.init_guess = '1e', add smearing, or increase max_cycle
BasisSetNotFoundError	Basis set name misspelled or unsupported	Check spelling and case against the Basis Set Exchange
Memory error during large calculation	Exact integrals exceed RAM	Use density fitting (mf.density_fit()) or reduce basis size
Negative frequencies after optimization	Geometry not fully converged to a minimum	Re-optimize with tighter convergence or check for transition states
OverflowError in large systems	Numerical instability in integral evaluation	Switch to density fitting or use a more diffuse basis with care

References

• Official Documentation: https://pyscf.org/manual.html
• ReadTheDocs: https://pyscf.readthedocs.io/en/latest/
• GitHub: https://github.com/pyscf/pyscf

Getting Live Information

If the user asks about recently added features, new options, or version-specific syntax changes, use WebFetch on the official documentation at https://pyscf.org/manual.html before answering.