pyece-mades 0.1.1

pyeCE is a pythonic tool to parameterize and deploy embedded cluster expansions for multicomponent alloys

embedded cluster expansions made easy

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.

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

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

pip install pyece-mades

From source (recommended for development)

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, 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.

# 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 for full guidelines on setting up the environment, code style, and the contribution workflow.

# 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:

@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) 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 for details.