CLAUDE.md

This file provides guidance for Claude Code when working with the pyquante2 codebase.

Project Overview

PyQuante2 is a Python quantum chemistry suite for developing and testing quantum chemistry methods. It includes implementations of Hartree-Fock (RHF, UHF), DFT, and MP2, with optional Cython extensions for performance-critical routines.

Status: Published on PyPI as pyquante2 (current version: 0.2.0)

Project Structure

pyquante2/
├── src/pyquante2/       # Main source code
│   ├── basis/           # Gaussian basis sets (PGBF, CGBF)
│   ├── cints/           # Cython/C integral routines
│   ├── dft/             # Density functional theory
│   ├── geo/             # Molecular geometry (atoms, molecules)
│   ├── graphics/        # Visualization tools
│   ├── grid/            # Numerical grids for DFT
│   ├── hylleraas/       # Hylleraas variational methods
│   ├── ints/            # Integral evaluation (one/two-electron)
│   ├── pt/              # Perturbation theory (MP2)
│   ├── scf/             # SCF solvers and Hamiltonians
│   └── viewer/          # Molecular viewer
├── tests/               # Test suite
├── attic/               # Archived/deprecated code
├── docs/                # Documentation
├── CHANGELOG.md         # Release history
├── VERSION_MANAGEMENT.md # Version bump checklist
├── FUTURE_TASKS.md      # Planned improvements
├── CODE_REVIEW.md       # Code quality findings
└── TODO.md              # Original task list

Development Commands

# Install with dev dependencies
uv sync --extra dev

# Run tests (preferred)
make test

# Or directly with pytest
uv run pytest

# Run tests with doctests
uv run pytest --doctest-modules --ignore=attic

# Build package for PyPI
make clean          # Clean old builds
make build          # Build wheel + source distribution
uv run twine check dist/*  # Verify package

# Publish to PyPI (see VERSION_MANAGEMENT.md first!)
make install_test   # Upload to TestPyPI
make install        # Upload to PyPI

Testing

• Tests are in tests/ directory using pytest
• Many modules include doctests in docstrings
• Run make test to run all tests including doctests
• 3 DFT tests are skipped (conditional functionality)

Code Style

• Python 3.11+ required
• Uses numpy extensively for numerical operations
• Classes use lowercase names (e.g., molecule, atom, cgbf)
• Doctests serve as both documentation and tests
• No type annotations currently used

Key Concepts

• PGBF: Primitive Gaussian Basis Function
• CGBF: Contracted Gaussian Basis Function
• HGP: Head-Gordon-Pople integral algorithm
• RHF/UHF: Restricted/Unrestricted Hartree-Fock
• DFT: Density Functional Theory (LDA, GGA functionals)

Dependencies

• Core: numpy, ipykernel
• Dev/Test: pytest, matplotlib, build, twine
• Build: setuptools, Cython (for C extensions)

Notes

• Cython extensions in src/pyquante2/cints/ are optional but improve performance
• The attic/ directory contains archived code - ignore when searching
• Uses uv for package management (uv.lock present)
• Before version bumps: Review VERSION_MANAGEMENT.md checklist
• For future tasks: See FUTURE_TASKS.md
• PyPI package: Available at https://pypi.org/project/pyquante2/