equilipy 0.3.1

A Gibbs energy minimization based on the CALPHAD approach

Equilipy

Equilipy is an open-source Python package for multicomponent-multiphase equilibrium calculations based on the CALPHAD (CALculation of PHAse Diagram) approach. Given a thermochemical database and input conditions (composition, pressure, and temperature), it computes the equilibrium phase configuration, amounts, compositions, and thermochemical properties. Equilipy uses the Gibbs energy descriptions furnished by THERMOCHIMICA with the modified Gibbs energy minimization algorithm inspired by Eriksson (1971) and de Capitani and Brown (1987). Check out the documentation for further description.

Requirements

Equilipy supports Python 3.10-3.14 on Linux, Windows, and macOS. A Fortran compiler is needed only when building from source.

Installation

Python package

Core package:

pip install equilipy

Desktop GUI (adds the equilipy.gui command):

pip install "equilipy[gui]"

MPI helpers for multi-node clusters:

pip install "equilipy[hpc]"

Graphical User Interface (GUI)

For standalone GUI installation, download the installer that matches your system:

• macOS Apple Silicon, macOS 15: Equilipy-macos-15-arm64.dmg
• macOS Apple Silicon, macOS 14: Equilipy-macos-14-arm64.dmg
• Windows 64-bit: Equilipy-windows-amd64.exe
• Linux 64-bit: Equilipy-linux-x86_64
• Linux ARM 64-bit: Equilipy-linux-arm64

Note (macOS): the installers are not yet notarized by Apple, so the first launch shows a warning that Equilipy could not be verified. Click Done (not Move to Trash), then use one of the following options:

1. System Settings → Privacy & Security → scroll down to "Equilipy" was blocked → Open Anyway
2. Remove the quarantine flag in a terminal: xattr -d com.apple.quarantine /Applications/Equilipy.app
3. Install through pip instead, which avoids this entirely: pip install "equilipy[gui]"

For users who installed Equilipy with GUI dependencies, the GUI can also be launched from the terminal:

equilipy.gui

[!NOTE] We recommend installing Equilipy in a dedicated conda or mamba environment to avoid dependency conflicts. Miniforge is a lightweight conda-forge based option: conda-forge/miniforge.

Quick start

Every script follows the same workflow: load a database, define the NPT condition, run a calculation, and post-process the result object.

import equilipy as eq

# 1. Load database
DB = eq.read_dat("database/AlCuMgSi_ORNL_FS83.dat")

# 2. NPT condition: temperature, pressure, and element amounts
NPT = {"T": 900, "P": 1, "Al": 0.75, "Cu": 0.05, "Mg": 0.10, "Si": 0.10}

# 3. Calculation: equilibrium here; solidification and batch variants
#    take the same database and condition
res = eq.equilib_single(DB, NPT)

# 4. Result classes: phases, properties, tables
print(res.stable_phases.names)        # ['LIQUID', 'HCP_A3']
print(res.G, res.H, res.S)            # system properties, J and J/K

See Python scripting for batch calculations, solidification, phase selection, and results handling, or GUI for the desktop application.

Features and Examples

The following features are currently available.

Feature	Examples
ChemSage/FactSage .dat database loading	Example01
FactSage 8.x/MQM oxide database loading and equilibrium canaries	Example01
Thermo-Calc style .tdb database loading (CEF, magnetic, order/disorder)	Example17
Single-condition equilibrium calculations	Example01
Equilibrium calculations with phase selection	Example02
Batch equilibrium calculations from table input	Example03, Example04
Scheil-Gulliver solidification	Example05, Example07
Scheil-Gulliver solidification with phase selection	Example06
NucleoScheil: nucleation-dependent Scheil-Gulliver solidification	Example08-Example15
Thermodynamic properties (G, H, S, Cp)	Example16
Result tables, CSV export, and Scheil constituent post-processing	Example15
Multi-node batch scaling with MPI	Example18

Equilipy also provides equilibrium cooling, transition-temperature search, TDB subsystem splitting and export (split_tdb/write_tdb), script-level result save/load helpers, and a standalone GUI with an AI-assist panel that sets up calculations from plain-language requests. For details, check out the example directory and the documentation.

Citing Equilipy

If you use Equilipy in your work, please cite the following paper. In addition, cite the current release or version used from Zenodo. If you use the NucleoScheil solidification model, please also cite Kwon et al., Acta Mater. (2026).

Contributing

We encourage you to contribute to Equilipy. Please see contributing guidelines.

Additional note

Equilipy installs polars (fast dataframe processing) and fastexcel (Excel reading with polars.read_excel, as in the batch examples) by default.

For very large datasets (> 4 billion rows), install:

pip install polars-u64-idx

If you are using old CPUs, install:

pip install polars-lts-cpu

For details, check out polars dependencies.