Metadata-Version: 2.4
Name: pyece-mades
Version: 0.1.1
Summary: pyeCE is a pythonic tool to parameterize and deploy embedded cluster expansions for multicomponent alloys
License: MIT
License-File: LICENSE
Keywords: cluster expansion,alloy,multicomponent,machine learning,Monte Carlo,PyTorch
Author: Laboratory of materials design and simulation
Author-email: anirudh.natarajan@epfl.ch
Requires-Python: >=3.10,<4.0
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
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.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Chemistry
Classifier: Topic :: Scientific/Engineering :: Physics
Requires-Dist: matplotlib (>=3.7,<4.0)
Requires-Dist: monty (>=2025.1.9)
Requires-Dist: pymatgen (>=2025.2.18,<2026.0.0)
Requires-Dist: pyyaml (>=6.0,<7.0)
Requires-Dist: scikit-learn (>=1.5.1,<2.0.0)
Requires-Dist: spglib (>=2.5.0,<3.0.0)
Requires-Dist: statsmodels (>=0.14.4,<0.15.0)
Requires-Dist: tabulate (>=0.9,<0.10)
Requires-Dist: torch (>=2.4.0,<3.0.0)
Requires-Dist: tqdm (>=4.0,<5.0)
Project-URL: Documentation, https://pyece.readthedocs.io
Project-URL: Repository, https://github.com/epfl-mades/pyeCE
Description-Content-Type: text/markdown

<p align="center">
  <img src="docs/source/figures/pyece_logo_with_background.png" alt="pyeCE" width="450"/>
</p>

<h3 align="center"><em>embedded</em> cluster expansions made easy</h3>

<p align="center">
  <a href="https://github.com/epfl-mades/pyeCE/actions/workflows/test.yml"><img src="https://github.com/epfl-mades/pyeCE/actions/workflows/test.yml/badge.svg" alt="Tests"/></a>
  <a href="https://github.com/epfl-mades/pyeCE/actions/workflows/lint.yml"><img src="https://github.com/epfl-mades/pyeCE/actions/workflows/lint.yml/badge.svg" alt="Lint"/></a>
  <a href="https://pypi.org/project/pyece-mades/"><img src="https://img.shields.io/pypi/v/pyece-mades" alt="PyPI version"/></a>
  <img src="https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue" alt="Python versions"/>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"/></a>
</p>

## Overview

Cluster expansions serve as surrogate models that link the electronic structure of a multicomponent alloy to its finite-temperature thermodynamic properties. They map the energy of any decoration of chemical species over a lattice to an on-lattice effective Hamiltonian, enabling energy evaluation at a fraction of the cost of ab initio calculations. **pyeCE** implements the **embedded cluster expansion** (eCE) formalism, which extends the standard CE with trainable site-basis functions that adapt to the chemistry of the alloy and improve expressiveness across composition space.

pyeCE (pronounced like "piece") represents the eCE model as a PyTorch `nn.Module`, making it compatible with modern optimization algorithms, GPU acceleration, and standard machine learning training workflows. It supports the full eCE workflow through both a **command-line interface** (`ece`) and a **Python API**, covering database construction, model parameterization, and finite-temperature simulations.

## Features

- Builds a **symmetry-adapted eCE model** from the primitive cell using pymatgen and spglib, with support for multi-sublattice and multi-species systems
- Learns **trainable site-basis functions** with a per-sublattice chemical embedding that adapts to the alloy chemistry
- Trains a **neural network ECI** with a **ladder training** scheme that progressively expands the cluster basis for stable convergence
- Runs **Canonical and Semi-Grand Canonical Monte Carlo** simulations to compute finite-temperature thermodynamic properties

## Documentation

The latest documentation is available at [pyece.readthedocs.io](https://pyece.readthedocs.io).

To build the documentation locally, run the following from the repo root:

```bash
cd docs
pip install -r requirements.txt
make html
```

The built documentation will open from `docs/build/html/index.html`.

## Installation

**Requirements:** Python 3.10 or later, PyTorch 2.4 or later.

### With pip

```bash
pip install pyece-mades
```

### From source (recommended for development)

```bash
git clone https://github.com/epfl-mades/pyeCE.git
cd pyeCE
poetry install
```

### GPU support

PyTorch installs as a CPU-only build by default. To use GPU acceleration, install the appropriate CUDA-enabled PyTorch build first by following the instructions at [pytorch.org](https://pytorch.org/get-started/locally/), then install pyeCE.

## Quick Start

The typical pyeCE workflow runs sequentially through `build`, `data`, and `fit`, followed by `mcmc` or `predict`. Run `ece --help` or `ece <subcommand> --help` for full argument documentation.

```bash
# 1. Build an eCE model from a PRIM file
ece build -p PRIM -s settings.yaml -n model.pth

# 2. Map and process structures into a training database
ece data -m model.pth -b batch.txt -n database.pkl

# 3. Fit the model against the training database
ece fit -m model.pth -t database.pkl -n fitted_model.pth

# 4. Run Monte Carlo simulations
ece mcmc -m fitted_model.pth -e Canonical -i <increment> -p results.json

# 5. Predict properties on a dataset
ece predict -m fitted_model.pth -d database.pkl -n predictions.pkl

# Inspect the model at any stage
ece print -m model.pth -p -s -f
```

The `build`, `fit`, and `mcmc` subcommands accept a YAML settings file via `-s settings.yaml` to configure options without listing them individually on the command line.

## CLI Reference

| Subcommand    | Description                                                                               |
|---------------|-------------------------------------------------------------------------------------------|
| `ece build`   | Constructs an eCE model from a PRIM file and saves it to disk                             |
| `ece data`    | Maps structure files onto the primitive lattice and saves a training database             |
| `ece fit`     | Parameterizes the model against a training database and saves the fitted model            |
| `ece mcmc`    | Runs Canonical or Semi-Grand Canonical Monte Carlo simulations and writes results to JSON |
| `ece predict` | Evaluates a fitted model on a database and writes predicted properties to the output file |
| `ece print`   | Inspects model components, summarizes datasets, and plots convex hulls                    |

## Development

Contributions are welcome. See [CONTRIBUTING.md](CONTRIBUTING.md) for full guidelines on setting up the environment, code style, and the contribution workflow.

```bash
# Install all dependencies including dev tools
poetry install

# Run the test suite
poetry run pytest -v

# Lint and format
poetry run ruff check .
poetry run ruff format .

# Install pre-commit hooks (runs automatically on each commit)
poetry run pre-commit install
```

## Citation

If you use pyeCE in your research, please cite the following paper:

```bibtex
@article{muller2025constructing,
  title     = {Constructing multicomponent cluster expansions with machine-learning and chemical embedding},
  author    = {M{\"u}ller, Yann L. and Natarajan, Anirudh Raju},
  journal   = {npj Computational Materials},
  volume    = {11},
  number    = {1},
  pages     = {60},
  year      = {2025},
  doi       = {10.1038/s41524-025-01543-3},
  url       = {https://doi.org/10.1038/s41524-025-01543-3}
}
```

Additional papers describing extensions to the pyeCE methodology are in preparation.

## Acknowledgements

pyeCE is developed by the [Laboratory of Materials Design and Simulation (MADES)](https://epfl-mades.github.io/) at EPFL. We are grateful for funding from the Swiss National Science Foundation through NCCR MARVEL, a National Center of Competence in Research (grant number 205602), and through grant number 215178.

## License

MIT License. See [LICENSE](LICENSE) for details.

