landau.py

A library to calculate thermodynamic equilibria and plot phase diagrams of binary alloys in the (semi-)grand ensemble.

You supply a free energy model for each phase — analytic toy models, CALPHAD-style parametrizations, or interpolations of computed free energy data — and landau finds the stable phases, refines the phase boundaries and draws the diagram.

Installation

pip install landau

Quickstart

Phases are defined by their free energies. Two ideal solutions — a solid and a liquid — already give a full binary phase diagram:

import numpy as np
from landau import LinePhase, IdealSolution, plot_phase_diagram
from landau.calculate import calc_phase_diagram
from landau.phases import kB

solid = IdealSolution("solid",
    LinePhase("A",    fixed_concentration=0, line_energy=-2.0, line_entropy=1.0 * kB),
    LinePhase("B",    fixed_concentration=1, line_energy=-3.0, line_entropy=1.5 * kB))
liquid = IdealSolution("liquid",
    LinePhase("A(l)", fixed_concentration=0, line_energy=-1.9, line_entropy=2.5 * kB),
    LinePhase("B(l)", fixed_concentration=1, line_energy=-2.9, line_entropy=2.2 * kB))

df = calc_phase_diagram([solid, liquid], Ts=np.linspace(400, 1800, 100), mu=100)
plot_phase_diagram(df)

Concentration-temperature phase diagram of a solid and a liquid ideal solution

calc_phase_diagram returns a plain pandas dataframe of (T, mu, phase, c, phi) samples that the plotting functions consume, so intermediate results stay easy to inspect and post-process.

Real Systems

The same interface works with computed free energies. This Mg–Ca phase diagram is calculated from free energies of an Atomic Cluster Expansion potential, obtained by thermodynamic integration with calphy:

Mg-Ca phase diagram from machine learning potential data

The Mg–Ca worked example goes from raw free energy samples to this diagram.

Looking Under the Hood

plot_excess_free_energy shows the free energy curves behind a diagram, including metastable phases and the common tangent constructions that determine the stable regions:

Excess free energy curves with common tangent constructions at three temperatures

More Examples

The documentation walks through the full API, including the basic concepts, congruent and non-congruent melting, stoichiometric line compounds and point defects.

Citation

This code is part of a publication, please cite it accordingly if you use this package in your work

@article{poul2025automated,
    title = {Automated generation of structure datasets for machine learning potentials and alloys},
    journal = {npj Computational Materials},
    author = {Poul, Marvin and Huber, Liam and Neugebauer, J{\"o}rg},
    volume = {11},
    number = {1},
    pages = {174},
    year = {2025},
    doi = {10.1038/s41524-025-01669-4},
}

Release files for landau 1.12.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for landau 1.12.0
File	Size	Uploaded
landau-1.12.0.tar.gz	23.6 MB	Sep 2, 2026	Details

Release files / landau-1.12.0.tar.gz

Download URL	landau-1.12.0.tar.gz
Size	23.6 MB
Tags	Source
SHA-256 checksum How to use checksums	`447c3cbecfa894b4392076adb952ad7665923bf4999d9fe81a6ed47b3fc6e028`
BLAKE2b-256 checksum How to use checksums	`1cd860a0da37248664c6796896ec2a047e7b822066b9769eccbaa6ed36de5340`
Upload date	Sep 2, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/6.1.0 CPython/3.13.7`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.