| name | pyscf |
| description | Use when running molecular quantum chemistry calculations in Python. Computes single-point energies, optimized geometries, vibrational frequencies, and population analysis using HF, DFT, or MP2 methods. |
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
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.
