Metadata-Version: 2.4
Name: muse-xtal
Version: 0.2.0
Summary: Build amorphous solids and liquid mixtures from Materials Project structures using Packmol and machine learning interatomic potentials
Author-email: Yuan Chiang <cyrusyc@lbl.gov>
License: MIT License
        
        Copyright (c) 2023, Yuan Chiang
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/chiang-yuan/muse
Project-URL: Documentation, https://chiang-yuan.github.io/muse
Project-URL: Repository, https://github.com/chiang-yuan/muse
Project-URL: Issues, https://github.com/chiang-yuan/muse/issues
Keywords: materials-science,molecular-dynamics,amorphous-solids,liquid-mixtures,packmol,machine-learning-interatomic-potentials
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: ase>=3.22.0
Requires-Dist: matplotlib>=3.5
Requires-Dist: numpy>=1.22
Requires-Dist: scipy>=1.7
Requires-Dist: mp-api>=0.45.0
Requires-Dist: pymatgen>=2023.7.1
Requires-Dist: monty>=2023.5.8
Requires-Dist: matcalc>=0.0.4
Requires-Dist: python-dotenv
Provides-Extra: dev
Requires-Dist: ruff; extra == "dev"
Requires-Dist: pre-commit; extra == "dev"
Requires-Dist: pytest; extra == "dev"
Requires-Dist: pytest-cov; extra == "dev"
Provides-Extra: mace
Requires-Dist: mace-torch>=0.3.0; extra == "mace"
Provides-Extra: docs
Requires-Dist: jupyter-book; extra == "docs"
Requires-Dist: sphinx; extra == "docs"
Requires-Dist: sphinx-autodoc-typehints; extra == "docs"
Requires-Dist: ghp-import; extra == "docs"
Dynamic: license-file

# Muse

[![PyPI version](https://img.shields.io/pypi/v/muse-xtal.svg)](https://pypi.org/project/muse-xtal/)
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Build and Test](https://github.com/chiang-yuan/muse/actions/workflows/test.yml/badge.svg)](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.
