Metadata-Version: 2.4
Name: atomchain
Version: 0.1.3
Summary: A library to chain the atomic models with applications
Author-email: Xu He <mailhexu@gmail.com>
License: BSD-2
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: BSD License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.7
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.8
Requires-Dist: ase
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: pathos
Requires-Dist: phonopy
Requires-Dist: pyyaml
Provides-Extra: dev
Requires-Dist: black>=21.6b0; extra == 'dev'
Requires-Dist: pre-commit>=2.13.0; extra == 'dev'
Requires-Dist: pytest>=6.2.0; extra == 'dev'
Requires-Dist: sphinx>=4.1.2; extra == 'dev'
Provides-Extra: test
Requires-Dist: pytest>=6.2.0; extra == 'test'
Description-Content-Type: text/markdown

# atomchain

AtomChain provides CLI tools and Python APIs for atomic structure manipulation and ML potential calculations.

## CLI Tools

AtomChain includes several command-line tools for common atomistic workflows:

- **`mlrelax`** - Relax atomic structures using ML potentials
- **`mlphonon`** - Calculate phonon properties and band structures
- **`mlgap`** - Predict band gap using ML potentials
- **`mlsinglepoint`** - Single point energy/forces/stress calculations
- **`mlsupercell`** - Generate supercells with various transformation matrices
- **`mlrattle`** - Generate rattled structure datasets for training
- **`mlbatch`** - Batch process trajectories with ML potentials
- **`mlcompare`** - Compare calculated properties between two trajectories
- **`mlneb`** - Nudged elastic band calculations for reaction pathways

## Installation

```bash
pip install -e .
```

## Quick Start

### Single Point Calculation
```bash
mlsinglepoint input.vasp --calculator chgnet --output results.yaml
```

### Generate Supercell
```bash
mlsupercell input.vasp --size 2 --output supercell.vasp
```

### Generate Training Dataset
```bash
mlrattle input.vasp --stdev 0.05 --count 100 --output structures.traj
```

### Batch Process Trajectory
```bash
mlbatch structures.traj --calculator chgnet --output results.traj
```

### Compare Trajectories
```bash
mlcompare dft.traj ml.traj --labels "DFT" "CHGNet" --output comparison.png
```

### Relax Structure
```bash
mlrelax input.vasp --calculator chgnet --output relaxed.vasp
```

### Calculate Phonons
```bash
mlphonon input.vasp --calculator chgnet --supercell 2,2,2
```

## Documentation

Detailed documentation for each tool is available in the `docs/` directory:

- [docs/singlepoint.md](docs/singlepoint.md) - Single point calculations
- [docs/supercell.md](docs/supercell.md) - Supercell generation
- [docs/rattle.md](docs/rattle.md) - Dataset generation
- [docs/batch.md](docs/batch.md) - Batch trajectory processing
- [docs/compare.md](docs/compare.md) - Trajectory comparison
- [docs/relax.md](docs/relax.md) - Structure relaxation
- [docs/phonon.md](docs/phonon.md) - Phonon calculations

## Python API

All CLI tools have corresponding Python APIs for programmatic use:

```python
from ase.io import read
from atomchain import (
    relax_with_ml,
    phonon_with_ml,
    init_calc,
    calculate_single_point,
    make_supercell_structure,
    generate_rattle_dataset,
    calculate_trajectory_batch,
    compare_trajectories,
    calculate_neb,
    predict_gap,
)

atoms = read("structure.vasp")

# Relax structure
relaxed_atoms = relax_with_ml(atoms, calculator="chgnet")

# Calculate phonons
phonon_with_ml(atoms, calculator="chgnet", supercell_matrix=[[2,0,0],[0,2,0],[0,0,2]])

# Predict band gap
gap = predict_gap(atoms, xc="PBE")

# Single point calculation
results = calculate_single_point(atoms, calculator="chgnet")

# Generate supercell
supercell = make_supercell_structure(atoms, size=2)

# Generate dataset
generate_rattle_dataset(
    atoms,
    stdev=0.05,
    count=100,
    output="dataset.traj"
)

# Batch process trajectory
results = calculate_trajectory_batch(
    "dataset.traj",
    calculator="chgnet",
    output="results.traj"
)

# Compare trajectories
compare_trajectories("dft.traj", "ml.traj", labels=["DFT", "CHGNet"])

# NEB calculation
images = [read(f"image{i}.vasp") for i in range(5)]
calculate_neb(images, calculator="chgnet")
```

## Requirements

- Python 3.9+
- ASE (Atomic Simulation Environment)
- Optional: CHGNet, M3GNet, MACE for ML potentials
- Optional: Phonopy for phonon analysis

## License

[Your license here]
