HEACalculator

HEACalculator is a Python tool for calculating phenomenological parameters based on thermodynamics and physics to predict the formation of solid solutions in High Entropy Alloys (HEAs). It provides a CLI (Typer), a GUI (PyQt6), and a Python API.

Report a Bug | Request a Feature | Documentation

Installation

Choose the workflow that matches how you want to use HEACalculator.

Add to a Project with uv

Use this when HEACalculator should be installed inside a project's environment.

uv add HEACalculator
uv add "HEACalculator[gui]"

Use as a Standalone Tool with uv

Use this when you want uv to manage HEACalculator as a CLI tool rather than a project dependency.

Persistent install:

uv tool install HEACalculator
HEACalculator --help

One-off run without installing permanently:

uvx HEACalculator search single FeCoCrNi

With GUI support:

uv tool install "HEACalculator[gui]"
HEACalculator gui

or

uvx --from "HEACalculator[gui]" HEACalculator gui

Install with pip

Use this if you are not using uv.

pip install HEACalculator          # CLI only
pip install "HEACalculator[gui]"   # with GUI support

Usage

Command Line Interface

Run HEACalculator without arguments to display the help text.

Single Alloy Calculations

HEACalculator search single <ALLOY> calculates all parameters and predictions for the given alloy and prints results to stdout.

HEACalculator search single FeCoCrNi

Append --json to get a machine-readable JSON output with raw numeric values instead of formatted text:

HEACalculator search single FeCoCrNi --json

Range Screening

HEACalculator search range calculates all parameters and predictions for a composition range over a set of elements. Compositions are evaluated in parallel across all available CPU cores, so large screens complete significantly faster.

HEACalculator search range --elements "Al Ti V" --start 0 --end 100 --step 5

Append --csv or --json to get CSV or newline-delimited JSON instead of formatted text, and redirect it to a file with >:

HEACalculator search range --elements "Al Ti V" --start 0 --end 100 --step 5 --csv > results.csv
HEACalculator search range --elements "Al Ti V" --start 0 --end 100 --step 5 --json > results.ndjson

CSV Batch Calculations

HEACalculator search csv <FILE> calculates all parameters and predictions for every alloy listed in a CSV file.

HEACalculator search csv alloys.csv

If your CSV uses a different column name, override it with --column/-c:

HEACalculator search csv alloys.csv --column Alloy

Append --json to get newline-delimited JSON (one object per alloy) instead of CSV rows:

HEACalculator search csv alloys.csv --json

Graphical User Interface

HEACalculator gui

The GUI has two pages, switched via the navigation buttons on the left:

Parameters page (single alloy)

1. Select elements from the periodic table (percentages are distributed equally by default)
2. Adjust the at% values in the composition table as needed
3. Click Calculate
4. Click Save to export results as CSV

Batch Calculations page (range screening)

Equivalent to search range.

1. Select elements from the periodic table
2. Set the composition range and step size
3. Click Search
4. Click Save to export results as CSV

Python API

HEACalculator can also be imported as a library. The CLI and GUI both use the same HEACalculator class.

Single Alloy Calculations

HEACalculator(<ALLOY>) calculates all parameters and predictions for the given alloy. Printing it gives the same report as search single.

from HEACalculator import HEACalculator

hea = HEACalculator("FeCoCrNi")
print(hea)

Individual properties are available through hea.thermo, and solid solution predictions through hea.predictor:

hea.thermo.mixing_enthalpy                 # -3.75 kJ/mol
hea.thermo.mixing_entropy                  # 11.53 J/K.mol
hea.thermo.valence_electron_concentration  # 8.25
hea.thermo.omega                           # 5.75
hea.thermo.omega_at(800)                   # Omega at 800 K

hea.predictor.microstructure               # "FCC"
hea.predictor.model_1                      # "Solid Solution"
hea.predictor.model_7()                    # method, accepts optional parameters

Use get_dict() to get raw numeric values, the same data as --json. NaN values are returned as None:

import json

json.dumps(hea.get_dict())

Range Screening

HEACalculator.screen calculates many alloys in parallel. It takes a list of formulas or the output of find_all_comps, which generates the same compositions as search range. By default it uses all CPU cores; set n_workers to limit this. It yields fully calculated HEACalculator objects in input order.

import pandas as pd

from HEACalculator import HEACalculator
from HEACalculator.utils import find_all_comps

if __name__ == "__main__":  # required by multiprocessing on macOS and Windows
    compositions = find_all_comps("Al Ti V", start=0, end=100, step=5)
    results = pd.DataFrame(calc.get_dict() for calc in HEACalculator.screen(compositions, n_workers=4))

Features

• Property calculations

  • Density
  • Melting Temperature
  • Mixing Enthalpy ^{1 2}
  • Miedema Mixing Enthalpy ³
  • Mixing Entropy
  • Formation Enthalpy ⁴
  • Valence Electron Concentration (VEC)
  • Hume-Rothery Electron-to-Atom Ratio (e/a) ⁵

• Parameters and predictions

  • Expected Microstructure ⁶
  • Delta Parameter (Atomic Size Difference) ^{7 8}
  • Delta Parameter (CN12 Atomic Size Difference) ^{7 9}
  • Electronegativity Difference (Allen CE scale) ^{10 11}
  • Electronegativity Difference (Pauling scale) ¹²
  • Omega Parameter ¹³
  • Gamma Parameter ¹⁴
  • Lambda Parameter ¹⁵
  • Phi Parameter ^{16 17 18}
  • Solid Solution Prediction Models
    • Model 1 ¹³
    • Model 2 ¹⁹
    • Model 3 ¹⁴
    • Model 4 ¹⁵
    • Model 5 ¹⁶
    • Model 6 ⁴
    • Model 7 ²⁰
    • Model 8 ³

License

This project is licensed under the GNU GPLv3 License. See the LICENSE file for details.

Citation

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

Sarıtürk, D., Kalay, Y. E., & Arróyave, R. (2026). HEACalculator: An Open-Source Python Tool for Thermodynamic Property Calculation and Solid Solution Prediction in High-Entropy Alloys. arXiv. https://doi.org/10.48550/arXiv.2606.19661

Sarıtürk, D. (2019). HEACalculator. Zenodo. https://doi.org/10.5281/zenodo.3590318

BibTeX:

@misc{sariturk_2026_arxiv,
  author    = {Sarıtürk, Doğuhan and Kalay, Yunus Eren and Arróyave, Raymundo},
  title     = {{HEACalculator}: An Open-Source {Python} Tool for Thermodynamic Property Calculation and Solid Solution Prediction in High-Entropy Alloys},
  year      = 2026,
  publisher = {arXiv},
  doi       = {10.48550/arXiv.2606.19661},
  url       = {https://doi.org/10.48550/arXiv.2606.19661},
}

@software{sariturk_2019_3590318,
  author    = {Sarıtürk, Doğuhan},
  title     = {HEACalculator},
  year      = 2019,
  publisher = {Zenodo},
  doi       = {10.5281/zenodo.3590318},
  url       = {https://doi.org/10.5281/zenodo.3590318},
}