https://github.com/chiang-yuan/muse
A python package for fast building amorphous solids and liquid mixtures from @materialsproject computed structures and machine learning interatomic potentials
https://github.com/chiang-yuan/muse
atomistic-simulations high-throughput interatomic-potentials machine-learning materials molecular-dynamics
Last synced: about 1 month ago
JSON representation
A python package for fast building amorphous solids and liquid mixtures from @materialsproject computed structures and machine learning interatomic potentials
- Host: GitHub
- URL: https://github.com/chiang-yuan/muse
- Owner: chiang-yuan
- License: mit
- Created: 2023-07-29T00:36:06.000Z (almost 3 years ago)
- Default Branch: main
- Last Pushed: 2026-04-18T23:43:44.000Z (about 1 month ago)
- Last Synced: 2026-04-19T00:39:27.391Z (about 1 month ago)
- Topics: atomistic-simulations, high-throughput, interatomic-potentials, machine-learning, materials, molecular-dynamics
- Language: Python
- Homepage: https://chiang-yuan.github.io/muse/
- Size: 1.42 MB
- Stars: 7
- Watchers: 1
- Forks: 0
- Open Issues: 1
-
Metadata Files:
- Readme: README.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Citation: CITATION.cff
Awesome Lists containing this project
- best-of-atomistic-machine-learning - GitHub
README
# Muse
[](https://pypi.org/project/muse-xtal/)
[](https://www.python.org/downloads/)
[](https://opensource.org/licenses/MIT)
[](https://github.com/chiang-yuan/muse/actions/workflows/test.yml)
**Muse** (**M**ixture b**u**ilder for **s**imulation **e**nvironments) is a Python package for rapidly building amorphous solids and liquid mixtures from relaxed solid-state structures on [Materials Project](https://materialsproject.org/). It uses [Packmol](http://m3g.iqm.unicamp.br/packmol/home.shtml) for packing molecules into simulation cells and supports density equilibration through molecular dynamics with machine learning interatomic potentials (MLIPs), especially universal interatomic potentials (UIPs) such as [MACE](https://github.com/ACEsuit/mace) and [CHGNet](https://github.com/CederGroupHub/chgnet).
## Features
- **Structure generation** — Build binary/multicomponent amorphous mixtures from Materials Project crystal structures via `mix_number` and `mix_cell`
- **Density equilibration** — Run NVT → NPT molecular dynamics workflows to compute equilibrium densities with `DensityCalc`
- **Thermodynamic analysis** — Plot binary mixing enthalpy (G–x), density–composition, and excess volume diagrams with Redlich–Kister fits
- **Trajectory I/O** — Convert pymatgen trajectories to extended XYZ format
- **HPC integration** — Submit SLURM batch jobs programmatically
## Installation
```bash
pip install muse-xtal
```
### Optional extras
```bash
# MACE calculator support
pip install "muse-xtal[mace]"
# Development tools (ruff, pytest)
pip install "muse-xtal[dev]"
# Documentation building
pip install "muse-xtal[docs]"
```
### Prerequisites
Muse requires [Packmol](http://m3g.iqm.unicamp.br/packmol/home.shtml) to be installed and available on your `PATH`. You can compile it from source:
```bash
bash scripts/install-packmol.sh
```
You also need a [Materials Project API key](https://materialsproject.org/api) set as the `MP_API_KEY` environment variable (or in a `.env` file).
## Quick Start
```python
from muse.transforms.mixture import mix_number
# Build a NaCl–KCl mixture (3:1 ratio, ~20 atoms)
atoms = mix_number(
recipe={"NaCl": 3, "KCl": 1},
tolerance=2.0,
scale=1.05,
seed=42,
)
print(atoms) # Atoms object ready for simulation
```
### Density equilibration with MACE
```python
import numpy as np
from ase import units
from mace.calculators import MACECalculator
from muse.calcs.density import DensityCalc
calc = MACECalculator(model_paths="path/to/model", device="cpu")
density_calc = DensityCalc(
calculator=calc,
optimizer="FIRE",
steps=500,
mask=np.eye(3),
rtol=1e-3,
atol=5e-4,
)
results = density_calc.calc(
atoms=atoms,
temperature=1100, # K
externalstress=0.0, # eV/ų
)
print(f"Density: {results['mass_density']:.4f} amu/ų")
```
## Documentation
Full documentation is available at [chiang-yuan.github.io/muse](https://chiang-yuan.github.io/muse).
## Citation
If you use Muse in your research, please cite:
```bibtex
@software{chiang2023muse,
author = {Chiang, Yuan},
title = {muse-xtal},
version = {0.2.0},
year = {2023},
doi = {10.5281/zenodo.10369245},
url = {https://github.com/chiang-yuan/muse}
}
```
## Contributing
Contributions are welcome! See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
## License
This project is licensed under the MIT License — see [LICENSE](LICENSE) for details.