Phonon Kit

A clean, modular Python library for phonon analysis.

Overview

Phonon Kit is a refactored, domain-driven Python library for phonon analysis. It breaks down the monolithic design of phonproj into focused, single-responsibility modules, making the codebase maintainable and LLM-friendly.

Key Goals:

• Replace the 3432-line PhononModes god class with modular architecture
• Eliminate code duplication (duplicate structure_analysis.py, supercell.py files)
• Enable < 30 second code navigation by domain concept
• Maintain 100% functional equivalence with phonproj (all 36 tests passing)
• Keep all modules under 500 lines
• Full type safety with pyright strict mode

Installation

# Create virtual environment and install in development mode
uv venv .venv
source .venv/bin/activate
uv pip install -e '.[dev]'

Or from PyPI (when published):

pip install phononkit

Package Structure

phononkit/
├── core/              # Layer 0: TypedDict contracts, constants
│   ├── types.py
│   └── constants.py
├── qpoints/           # Layer 0: Q-point mathematics
│   ├── grid.py           # Q-point grid generation
│   ├── commensurate.py   # Commensurate q-point operations
│   ├── path.py           # Q-path generation
│   └── utils.py          # Q-point utilities
├── modes/              # Layer 1: Phonon mode representation
│   ├── mode.py           # Single PhononMode class
│   ├── collection.py     # PhononModeCollection
│   └── gauge.py          # Gauge transformations
├── displacements/      # Layer 2: Displacement generation
│   ├── generator.py       # Displacement generation
│   └── thermal.py         # Thermal displacement patterns
├── projections/        # Layer 2: Mass-weighted projections
│   ├── mass_weighted.py  # Mass-weighting logic
│   └── orthonormality.py # Orthonormality verification
├── supercells/         # Layer 2: Supercell operations
│   ├── builder.py         # Supercell construction
│   └── phase.py           # Phase factor application
├── analysis/           # Layer 2: Structure analysis
│   ├── structure.py       # Atomic correspondence
│   ├── substitution.py    # Species substitution
│   └── symmetry.py        # Irreps analysis (placeholder)
└── io/                 # Layer 2: Data I/O
    ├── phonopy_loader.py # Load from phonopy YAML
    └── mcif.py            # MCIF export (placeholder)

tests/                  # Test suite (mirrors package structure)
├── validation/        # Property-based validation tests
├── modes/            # Modes tests
├── qpoints/          # Q-points tests
├── displacements/    # Displacements tests
├── projections/      # Projections tests
├── supercells/       # Supercells tests
├── analysis/          # Analysis tests
└── io/               # I/O tests

examples/               # End-to-end examples with real data
├── data/              # Real phonon data files
└── *.py              # Example scripts

LLMdocs/              # LLM-friendly documentation
├── architecture_overview.md
├── module_relationships.md
└── design_patterns.md

docs/                  # Technical documentation (Phase 2)
├── api/               # Auto-generated API reference
├── methodology/        # Mathematical methodology
└── user_guide/         # User guide

Quick Start

from phononkit import load_from_phonopy_yaml
from phononkit import PhononMode, PhononModeCollection
from phononkit import generate_mode_displacement, generate_thermal_displacement

# Load phonon data from phonopy YAML file
structure, modes = load_from_phonopy_yaml('path/to/phonopy.yaml')

# Filter modes by frequency
low_freq_modes = modes.filter_by_frequency(freq_min=0, freq_max=5)

# Generate displacement for a mode
displacement = generate_mode_displacement(low_freq_modes[0], amplitude=1.0)

# Generate thermal displacement pattern at 300K
thermal_disp = generate_thermal_displacement(modes, temperature=300)

Development

# Run tests
pytest tests/

# Type checking
pyright phononkit/

# Linting
ruff check phononkit/

Dependencies

• numpy >= 1.20.0
• scipy >= 1.7.0
• ase >= 3.22.0
• phonopy >= 2.0.0

Development dependencies:

• pytest >= 7.0.0
• pyright >= 1.1.0
• sphinx >= 5.0.0
• sphinx-rtd-theme >= 1.0.0

Python Version Support

Python 3.9, 3.10, 3.11, 3.12, 3.13, 3.14

License

MIT License

Comparison to phonproj

Contributing

See AGENT.md for development guidelines.