Metadata-Version: 2.4
Name: macer
Version: 0.3.5
Summary: Machine-learning accelerated Atomic Computational Environment for automated Research workflows
Author-email: Soungmin Bae <soungminbae@gmail.com>
License: MIT
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: setuptools
Requires-Dist: numpy<2.3; python_version < "3.14"
Requires-Dist: numpy>=2.3; python_version >= "3.14"
Requires-Dist: matplotlib
Requires-Dist: ase
Requires-Dist: pymatgen
Requires-Dist: emmet-core
Requires-Dist: monty
Requires-Dist: phonopy==2.47.1
Requires-Dist: phono3py==3.24.0
Requires-Dist: vise==0.9.5
Requires-Dist: pydefect==0.9.11
Requires-Dist: scipy
Requires-Dist: tqdm
Requires-Dist: pyyaml
Requires-Dist: torch
Requires-Dist: torch_ema
Requires-Dist: typing-extensions
Requires-Dist: e3nn>=0.5.1
Requires-Dist: chgnet
Requires-Dist: matgl
Requires-Dist: mattersim
Requires-Dist: sevenn
Requires-Dist: fairchem-core; python_version < "3.14"
Requires-Dist: orb-models
Requires-Dist: nequip
Requires-Dist: huggingface_hub
Requires-Dist: pandas
Requires-Dist: plotly
Requires-Dist: kaleido
Dynamic: license-file

<p align="center">
  <img src="docs/macer_logo.png" alt="Macer logo" width="240">
</p>

# Macer

[![Version](https://img.shields.io/badge/version-0.3.5-blue.svg)](https://pypi.org/project/macer/)
[![Build wheels](https://github.com/soungmin-bae/macer/actions/workflows/wheels.yml/badge.svg)](https://github.com/soungmin-bae/macer/actions/workflows/wheels.yml)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

**Machine-learning accelerated Atomic Computational Environment for Research workflows**

Macer provides a unified command-line interface for crystal-structure
relaxation, molecular dynamics, path-integral molecular dynamics, lattice
dynamics, finite-temperature phonons, thermal conductivity, and point-defect
calculations using machine-learned force fields.

It combines native Macer workflows with adapters for Phonopy, phono3py,
DynaPhoPy, pydefect, and PIMD_python while keeping calculator selection,
configuration, and output handling consistent.

## Documentation

Installation details, configuration, production examples, complete command
usage, and output descriptions are maintained in the documentation:

### [Open the Macer User Guide →](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/README.md)

For the complete command-by-command manual, see the
[Complete Usage Guide](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md).

## Highlights

- Unified MLFF calculators: MatterSim, MACE, SevenNet, CHGNet, M3GNet,
  Allegro, Orb, FairChem, and native VASP MLFF.
- Structure relaxation with ASE optimizers and VASP-compatible `ISIF` modes.
- NVE, NVT, and NPT molecular dynamics plus PIMD and restart workflows.
- Harmonic phonons, DOS, irreducible representations, and Grüneisen analysis.
- Isotropic and anisotropic QHA with restartable random-displacement workflows.
- qSCAILD/SSCHA finite-temperature force constants with automated convergence
  control and independent validation.
- DynaPhoPy spectral analysis and phono3py thermal-conductivity workflows.
- Automated chemical-potential and point-defect calculations.

## Installation

Install the published package:

```bash
python -m pip install macer
```

Verify the command-line interface:

```bash
macer --help
```

For uv, Conda, editable, CUDA, compiler, HPC, and model setup, follow the
[installation and configuration guide](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/README.md#getting-started).

## Quick start

Relax a structure:

```bash
macer relax POSCAR --ff mattersim
```

Run molecular dynamics:

```bash
macer md POSCAR --ensemble nvt --temperature 300
```

Calculate a phonon dispersion:

```bash
macer phonopy pb POSCAR --ff mattersim
```

Run finite-temperature SSCHA with automatic convergence control:

```bash
macer phonopy sscha POSCAR \
  --temperature 300 \
  --dim 2 2 2 \
  --autopilot
```

## Workflow map

| Task | Main command | Documentation |
|---|---|---|
| Structure relaxation | `macer relax` | [Relaxation](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#relaxation-examples-macer-relax) |
| Molecular dynamics | `macer md` | [MD](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#molecular-dynamics-examples-macer-md) |
| Path-integral MD | `macer pimd` | [PIMD](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#path-integral-molecular-dynamics-examples-macer-pimd) |
| Phonons and QHA | `macer phonopy` | [Lattice dynamics](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#phonon--lattice-dynamics-examples-macer-phonopy) |
| Finite-temperature phonons | `macer phonopy sscha`, `macer dynaphopy` | [SSCHA and DynaPhoPy](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#qscaild-macer-phonopy-qscaild-alias-macer-phonopy-sscha) |
| Thermal conductivity | `macer phono3py` | [phono3py](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#lattice-thermal-conductivity-macer-phono3py-legacy-macer-phonopy-tc) |
| Point defects | `macer pydefect` | [Defect analysis](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#defect-analysis-examples-macer-pydefect) |
| Data, models, and plots | `macer util` | [Utilities](https://github.com/soungmin-bae/macer/blob/main/docs/user-guide/usage.md#utility-suite-macer-util) |

## Command help

The installed CLI is the authoritative option reference:

```bash
macer --help
macer relax --help
macer md --help
macer pimd --help
macer phonopy --help
macer phonopy pb --help
macer phonopy qha --help
macer phonopy sscha --help
macer dynaphopy --help
macer phono3py --help
macer pydefect --help
macer util --help
```

## Related projects

Macer integrates with or builds upon
[Phonopy](https://github.com/phonopy/phonopy),
[phono3py](https://github.com/phonopy/phono3py),
[qSCAILD](https://github.com/vanroeke/qscaild),
[DynaPhoPy](https://github.com/abelcarreras/DynaPhoPy),
[pydefect](https://github.com/kumagai-group/pydefect), and
[PIMD_python](https://github.com/kuwahatakazuaki/PIMD_python).

## License

Macer is distributed under the [MIT License](LICENSE).

## Author

- **Soungmin Bae** — [soungminbae@gmail.com](mailto:soungminbae@gmail.com), Yokohama City University

## Contributors

- **Yasuhide Mochizuki** — [ahntaeyoung1212@gmail.com](mailto:ahntaeyoung1212@gmail.com), Tokyo University of Science
- **Kuwahata Kazuaki** — [kuwahata0615@gmail.com](mailto:kuwahata0615@gmail.com), Institute of Science Tokyo
