phononkit 0.1.0
A clean, modular Python library for phonon analysis
License: MIT
Requires Python: <3.15,>=3.9

# 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

```bash
# 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):
```bash
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

```python
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

```bash
# 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

| Feature | phonproj | phononkit |
|---------|-----------|------------|
| Code organization | Monolithic 3432-line class | Modular < 500-line modules |
| Navigation | Search 3000+ lines | < 30 seconds by domain |
| Duplication | Duplicate files | Single canonical implementations |
| Type safety | Partial coverage | 100% pyright strict mode |
| Test coverage | 36 tests | Property-based validation |

## Contributing

See AGENT.md for development guidelines.