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 both a CLI (Typer) and GUI (PyQt6) interface.

Report a Bug | Request a Feature | Documentation

Installation

[!NOTE] GUI support requires PyQt6, which is an optional dependency. Install with the [gui] extra if needed.

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 / --json to redirect output to a file:

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.

[!IMPORTANT] The input CSV file must contain a column named composition. Each row in that column should be a valid alloy formula (e.g. FeCoCrNi). Any other columns in the file are ignored.

HEACalculator search csv alloys.csv

Append --json to get machine-readable JSON output instead of formatted text:

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

Features

• Property calculations

  • Density
  • Melting Temperature
  • Mixing Enthalpy ¹
  • 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) ⁶
  • Delta Parameter (CN12-corrected Atomic Size Difference) ⁶
  • Electronegativity Difference (Allen CE scale)
  • Electronegativity Difference (Pauling scale) ⁷
  • Omega Parameter ⁸
  • Gamma Parameter ⁹
  • Lambda Parameter ¹⁰
  • 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},
}