Metadata-Version: 2.4
Name: atomchain
Version: 0.2.0
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
Requires-Dist: scipy
Requires-Dist: spgrep-modulation>=0.2.5
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, ML-potential calculations, phonon/DDB workflows, and ABINIT HIST/MULTIBINIT training artifact preparation.

## 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
- **`mlcollect`** - Collect structures from many files into one trajectory
- **`mlconvert`** - Convert structures between ASE-supported file formats
- **`mlmetastable`** - Explore symmetry-mode metastable structures
- **`mlddb`** - Write ABINIT-style DDB files from phonopy and ML finite-difference workflows
- **`mlhist`** - Convert between ABINIT HIST.nc and ASE trajectory files
- **`mltraining`** - Generate MULTIBINIT training trajectories/artifacts and delegate training to pymultibinit

## Installation

```bash
uv sync
```

For editable installation with `pip`, use `pip install -e .` from the repository root.

## Quick Start

### Single Point Calculation
```bash
mlsinglepoint input.vasp --model chgnet --output_file results.yaml
```

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

### Generate Training Dataset
```bash
mlrattle input.vasp --stdev 0.05 --nstruct 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 --model chgnet --output_file relaxed.vasp
```

### Calculate Phonons
```bash
mlphonon input.vasp --model chgnet --ndim 2 2 2
```

### Write DDB From Phonopy
```bash
mlddb BaTiO3.vasp --phonopy-yaml phonon_save/phonopy_params.yaml --output BaTiO3.ddb --validate
```

### Write ABINIT HIST From Trajectory
```bash
mlhist training.traj training_HIST.nc --to hist
```

### Generate Training Trajectory
```bash
mltraining generate BaTiO3.vasp --sources md phonon_modes --model mace-r2scan --output training.traj
```

## 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
- [docs/md.md](docs/md.md) - Molecular dynamics
- [docs/multibinit.md](docs/multibinit.md) - MULTIBINIT calculator usage through pymultibinit
- [docs/ddb.md](docs/ddb.md) - ABINIT-style DDB writer
- [docs/hist_training.md](docs/hist_training.md) - ABINIT HIST and MULTIBINIT training artifacts

## Python API

All CLI tools have corresponding Python APIs for programmatic use:

```python
from ase.io import read
from atomchain import (
    calculate_single_point,
    calculate_trajectory_batch,
    calculate_neb,
    compare_trajectories,
    explore_metastable_states,
    generate_multibinit_training_artifacts,
    generate_rattle_dataset,
    generate_training_trajectory,
    init_calc,
    make_supercell_structure,
    phonon_with_ml,
    read_abinit_hist,
    relax_with_ml,
    write_ddb_from_finite_difference,
    write_ddb_from_phonopy,
    write_abinit_hist,
)

atoms = read("structure.vasp")

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

# Calculate phonons
phonon_with_ml(atoms, calc="chgnet", ndim=[[2, 0, 0], [0, 2, 0], [0, 0, 2]])

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

# Generate supercell
supercell = make_supercell_structure(atoms, 2)

# Generate dataset
generate_rattle_dataset(
    atoms,
    stdev=0.05,
    n_struct=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
initial = read("initial.vasp")
final = read("final.vasp")
calculate_neb(initial, final, calculator="chgnet")

# HIST conversion and training trajectory generation
frames = generate_training_trajectory(atoms, sources=["phonon_modes"], evaluate=False)
write_abinit_hist(frames, "training_HIST.nc", strict=False)
loaded_frames = read_abinit_hist("training_HIST.nc")
```

## Requirements

- Python 3.8+
- ASE (Atomic Simulation Environment)
- Phonopy
- Optional: CHGNet, M3GNet, matgl, MACE, DeePMD-kit, atomic_potential_xq, and pymultibinit depending on selected calculator/workflow

## License

BSD-2-Clause
