pyscf

What this skill does

# PySCF - Quantum Chemistry Framework

Python library for ab initio electronic structure calculations and quantum chemistry.

## When to Use

- Running Hartree-Fock (HF) and Density Functional Theory (DFT) calculations
- Calculating molecular energies and gradients
- Optimizing molecular geometries
- Computing post-HF methods (MP2, CCSD, CI, coupled-cluster)
- Analyzing molecular orbitals and electron density
- Calculating excited states (TD-DFT, CI, EOM-CCSD)
- Computing molecular properties (dipole, charges, NMR, IR)
- Performing periodic calculations (solids, surfaces)
- Benchmarking quantum chemistry methods
- Integrating quantum calculations with ML/AI workflows

## Reference Documentation

**Official docs**: https://pyscf.org/  
**Search patterns**: `gto.M`, `scf.RHF`, `dft.RKS`, `mp.MP2`, `optimize`, `tddft.TDDFT`

## Core Principles

### Use PySCF For

| Task | Module | Example |
|------|--------|---------|
| Build molecule | `gto` | `gto.M(atom='H 0 0 0; H 0 0 1')` |
| Hartree-Fock | `scf` | `scf.RHF(mol).run()` |
| DFT calculation | `dft` | `dft.RKS(mol, xc='B3LYP')` |
| MP2 correlation | `mp` | `mp.MP2(mf).run()` |
| Coupled-cluster | `cc` | `cc.CCSD(mf).run()` |
| Geometry optimization | `geomopt` | `optimize(mf)` |
| Excited states | `tddft` | `tddft.TDDFT(mf).run()` |
| Periodic systems | `pbc` | `pbc.gto.Cell()` |

### Do NOT Use For

- Molecular dynamics simulations (use GROMACS, OpenMM, ASE)
- Very large systems (>1000 atoms) - use semi-empirical or force fields
- Interactive visualization (use PyMOL, VMD)
- High-throughput virtual screening (too slow)
- Real-time quantum simulations

## Quick Reference

### Installation

```bash
# pip (recommended)
pip install pyscf

# With extensions
pip install pyscf[geomopt,dftd3,dmrgscf]

# From conda
conda install -c pyscf pyscf

# Development version
pip install git+https://github.com/pyscf/pyscf
```

### Standard Imports

```python
# Core modules
from pyscf import gto, scf, dft
from pyscf import mp, cc, ci
from pyscf import grad, geomopt
from pyscf import tddft, tdscf
from pyscf import lo, ao2mo

# Tools
from pyscf.tools import molden, cubegen
import numpy as np
```

### Basic Pattern - Single Point Energy

```python
from pyscf import gto, scf

# 1. Build molecule
mol = gto.M(
    atom='O 0 0 0; H 0 1 0; H 0 0 1',
    basis='6-31g',
    charge=0,
    spin=0  # 2S, 0 = singlet
)

# 2. Run SCF
mf = scf.RHF(mol)
energy = mf.kernel()

# 3. Check convergence
if not mf.converged:
    raise RuntimeError("SCF did not converge")

print(f"E(HF) = {energy:.8f} Hartree")
```

### Basic Pattern - DFT Calculation

```python
from pyscf import gto, dft

mol = gto.M(atom='C 0 0 0; O 0 0 1.2', basis='def2-tzvp')

# DFT with B3LYP
mf = dft.RKS(mol)
mf.xc = 'B3LYP'
energy = mf.kernel()

print(f"E(B3LYP) = {energy:.8f} Hartree")
```

### Basic Pattern - Geometry Optimization

```python
from pyscf import gto, scf
from pyscf.geomopt.geometric_solver import optimize

mol = gto.M(atom='H 0 0 0; H 0 0 1.5', basis='6-31g')
mf = scf.RHF(mol)

# Optimize geometry
mol_eq = optimize(mf)

print(f"Optimized geometry:\n{mol_eq.atom}")
```

## Critical Rules

### ✅ DO

- **Check convergence** - Always verify `mf.converged == True`
- **Start with small basis** - Test with STO-3G or 3-21G first
- **Specify charge and spin** - Be explicit about electronic state
- **Save results** - Use `chkfile` for restart capability
- **Use symmetry** - Enable when applicable for speed
- **Provide good initial guess** - Use `init_guess='minao'` or previous results
- **Monitor memory** - Set `max_memory` appropriately
- **Verify units** - PySCF uses Bohr and Hartree internally
- **Use density fitting** - Enable for large systems
- **Check multiplicity** - Ensure spin matches expected state

### ❌ DON'T

- **Skip convergence check** - Never use results from unconverged calculation
- **Use huge basis sets initially** - Start small, expand gradually
- **Ignore charge/spin** - Defaults may not match your system
- **Run without `chkfile`** - You'll lose data if crash occurs
- **Disable symmetry unnecessarily** - It speeds up calculations
- **Mix coordinate systems** - Be consistent with Angstrom vs Bohr
- **Use wrong multiplicity** - 2S+1, not 2S
- **Forget about memory** - Large calculations can OOM
- **Trust unconverged results** - They're meaningless
- **Compare methods without same basis** - Use consistent basis sets

## Anti-Patterns (NEVER)

```python
# ❌ BAD: Not checking convergence
mf = scf.RHF(mol)
energy = mf.kernel()
# Use energy without checking convergence!

# ✅ GOOD: Always check convergence
mf = scf.RHF(mol)
energy = mf.kernel()
if not mf.converged:
    raise RuntimeError("SCF not converged, results unreliable")

# ❌ BAD: Using huge basis immediately
mol = gto.M(atom='protein.xyz', basis='def2-qzvppd')
# This will take forever or crash!

# ✅ GOOD: Start small, expand if needed
mol = gto.M(atom='protein.xyz', basis='sto-3g')
# Test first, then use def2-svp, def2-tzvp, etc.

# ❌ BAD: Ignoring electronic state
mol = gto.M(atom='O 0 0 0; O 0 0 1.2')
mf = scf.RHF(mol)  # What charge? What spin?

# ✅ GOOD: Explicit state specification
mol = gto.M(
    atom='O 0 0 0; O 0 0 1.2',
    charge=0,
    spin=2  # Triplet O2
)
mf = scf.ROHF(mol)  # Restricted open-shell for triplet

# ❌ BAD: No checkpoint file
mf = scf.RHF(mol)
mf.kernel()  # If crash, lose everything!

# ✅ GOOD: Use checkpoint files
mf = scf.RHF(mol)
mf.chkfile = 'calculation.chk'
mf.kernel()
# Can restart if needed

# ❌ BAD: Wrong multiplicity
mol = gto.M(atom='O 0 0 0; O 0 0 1.2', spin=2)  # Wrong!
# spin should be 2S, not multiplicity!

# ✅ GOOD: Correct spin specification
mol = gto.M(
    atom='O 0 0 0; O 0 0 1.2',
    spin=2  # 2S = 2 for triplet (multiplicity = 2S+1 = 3)
)
```

## Molecule Building

### Basic Molecule Definition

```python
from pyscf import gto

# Cartesian coordinates (Angstrom by default)
mol = gto.M(
    atom='''
        O  0.0  0.0  0.0
        H  0.0  1.0  0.0
        H  0.0  0.0  1.0
    ''',
    basis='6-31g',
    charge=0,
    spin=0
)

# Compact format
mol = gto.M(
    atom='O 0 0 0; H 0 1 0; H 0 0 1',
    basis='6-31g'
)

# Using tuple format
mol = gto.M(
    atom=[
        ('O', (0.0, 0.0, 0.0)),
        ('H', (0.0, 1.0, 0.0)),
        ('H', (0.0, 0.0, 1.0))
    ],
    basis='6-31g'
)
```

### Loading from Files

```python
from pyscf import gto

# From XYZ file
mol = gto.M(atom='molecule.xyz', basis='6-31g')

# From PDB file
mol = gto.M(atom='protein.pdb', basis='sto-3g')

# From Z-matrix
mol = gto.M(
    atom='''
    H
    H  1  0.74
    ''',
    basis='6-31g'
)
```

### Molecular Properties and Info

```python
from pyscf import gto

mol = gto.M(atom='H2O', basis='6-31g')

# Basic properties
print(f"Number of atoms: {mol.natm}")
print(f"Number of electrons: {mol.nelectron}")
print(f"Number of basis functions: {mol.nao_nr()}")
print(f"Charge: {mol.charge}")
print(f"Spin (2S): {mol.spin}")
print(f"Nuclear repulsion: {mol.energy_nuc():.8f}")

# Atom information
for i in range(mol.natm):
    atom_symbol = mol.atom_symbol(i)
    atom_charge = mol.atom_charge(i)
    coord = mol.atom_coord(i)
    print(f"Atom {i}: {atom_symbol} (Z={atom_charge}) at {coord}")
```

### Basis Set Specification

```python
from pyscf import gto

# Single basis for all atoms
mol = gto.M(atom='H2O', basis='6-31g')

# Different basis for different atoms
mol = gto.M(
    atom='H2O',
    basis={
        'O': '6-311g**',
        'H': '6-31g'
    }
)

# Custom basis sets
mol = gto.M(
    atom='H 0 0 0; H 0 0 1',
    basis={
        'H': gto.basis.parse('''
            H    S
                 13.0107010              0.19682158E-01
                  1.9622572              0.13796524
                  0.44453796             0.47831935
            H    S
                  0.12194962             1.0000000
        ''')
    }
)
```

### Molecular Symmetry

```python
from pyscf import gto

# Auto-detect symmetry
mol = gto.M(atom='H2O', basis='6-31g', symmetry=True)
print(f"Point group: {