Metadata-Version: 2.5
Name: HEACalculator
Version: 2.2.0
Summary: A Python tool for calculating phenomenological parameters to predict solid solution formation in High Entropy Alloys (HEAs)
Project-URL: Home-page, https://github.com/dogusariturk/HEACalculator/
Project-URL: Issues, https://github.com/dogusariturk/HEACalculator/issues
Project-URL: Repository, https://github.com/dogusariturk/HEACalculator.git
Author-email: Doguhan Sariturk <dogu.sariturk@gmail.com>
License: GPL-3.0-or-later
License-File: LICENSE
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Requires-Dist: numpy>=1.23.4
Requires-Dist: pandas>=1.4.1
Requires-Dist: typer>=0.26.5
Provides-Extra: docs
Requires-Dist: mkdocs-material==9.7.7; extra == 'docs'
Requires-Dist: mkdocstrings[python]==1.0.6; extra == 'docs'
Provides-Extra: gui
Requires-Dist: pyqt6>=6.0.0; extra == 'gui'
Description-Content-Type: text/markdown

<div align="center">

<img src="https://user-images.githubusercontent.com/46679086/200971710-3ad2327e-6183-4ef9-b3b7-06a57f004e1a.png" alt="Logo" width="200" height="200">

# HEACalculator

[![License: GPL v3](https://img.shields.io/badge/License-GPLv3-blue.svg)](https://opensource.org/license/gpl-3-0)
![Python](https://img.shields.io/badge/python-3.10%2B-blue)
![Platforms](https://img.shields.io/badge/platform-linux%20%7C%20macos%20%7C%20windows-lightgrey)

[![Tests](https://github.com/dogusariturk/HEACalculator/actions/workflows/tests.yml/badge.svg)](https://github.com/dogusariturk/HEACalculator/actions/workflows/tests.yml)
[![Lint](https://github.com/dogusariturk/HEACalculator/actions/workflows/lint.yml/badge.svg)](https://github.com/dogusariturk/HEACalculator/actions/workflows/lint.yml)

[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.3590318.svg)](https://doi.org/10.5281/zenodo.3590318)
[![DOI](https://img.shields.io/badge/DOI-10.48550%2FarXiv.2606.19661-blue.svg)](https://doi.org/10.48550/arXiv.2606.19661)

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

<p>
  <a href="https://github.com/dogusariturk/HEACalculator/issues/new?labels=bug">Report a Bug</a> |
  <a href="https://github.com/dogusariturk/HEACalculator/issues/new?labels=enhancement">Request a Feature</a> |
  <a href="https://dogusariturk.github.io/HEACalculator">Documentation</a>
</p>

</div>

---

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

```sh
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:

```sh
uv tool install HEACalculator
HEACalculator --help
```

One-off run without installing permanently:

```sh
uvx HEACalculator search single FeCoCrNi
```

With GUI support:

```sh
uv tool install "HEACalculator[gui]"
HEACalculator gui
```
or
```sh
uvx --from "HEACalculator[gui]" HEACalculator gui
```

### Install with `pip`

Use this if you are not using `uv`.

```sh
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.

![HEACalculator](https://user-images.githubusercontent.com/46679086/205514909-ab4930cd-2f5b-4d9c-9598-750c661d44db.png)

---

#### Single Alloy Calculations

![HEACalculator_SearchSingle](https://user-images.githubusercontent.com/46679086/205514947-ca25fb25-c726-4de9-a79b-1cccf354b4e3.png)

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

```sh
HEACalculator search single FeCoCrNi
```

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

```sh
HEACalculator search single FeCoCrNi --json
```

---

#### Range Screening

![HEACalculator_SearchRange](https://user-images.githubusercontent.com/46679086/205514952-95dcb909-2147-4fcf-91df-4e0d1a1321dc.png)


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

```sh
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 `>`:

```sh
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]
> By default, 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.

```sh
HEACalculator search csv alloys.csv
```

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

```sh
HEACalculator search csv alloys.csv --column Alloy
```

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

```sh
HEACalculator search csv alloys.csv --json
```

### Graphical User Interface

```sh
HEACalculator gui
```

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

---

#### Parameters page (single alloy)

<img width="2342" height="1292" alt="HEACalculator_GUI-Parameters" src="https://github.com/user-attachments/assets/d13744ee-b60f-4922-a758-53b89876a7f5" />

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)

<img width="2342" height="1292" alt="HEACalculator_GUI-RangeSearch" src="https://github.com/user-attachments/assets/f829e67b-c069-4857-9b13-56068f63f816" />

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

```python
from HEACalculator import HEACalculator

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

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

```python
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`:

```python
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.

```python
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] [^18]
  - Miedema Mixing Enthalpy [^11]
  - Mixing Entropy
  - Formation Enthalpy [^2]
  - Valence Electron Concentration (VEC)
  - Hume-Rothery Electron-to-Atom Ratio (e/a) [^17]

- Parameters and predictions
  - Expected Microstructure [^3]
  - Delta Parameter (Atomic Size Difference) [^4] [^21]
  - Delta Parameter (CN12 Atomic Size Difference) [^4] [^22]
  - Electronegativity Difference (Allen CE scale) [^12] [^13]
  - Electronegativity Difference (Pauling scale) [^16]
  - Omega Parameter [^5]
  - Gamma Parameter [^6]
  - Lambda Parameter [^7]
  - Phi Parameter [^9] [^19] [^20]
  - Solid Solution Prediction Models
      - Model 1 [^5]
      - Model 2 [^8]
      - Model 3 [^6]
      - Model 4 [^7]
      - Model 5 [^9]
      - Model 6 [^2]
      - Model 7 [^10]
      - Model 8 [^11]

[^1]: Zhang, Y.; Zuo, T.T.; Tang, Z.; Gao, M.C.; Dahmen, K.A.; Liaw, P.K.; Lu, Z.P. Prog. Mater. Sci. 2014, 61, 1–93.
[^2]: Troparevsky, M.C.; Morris, J.R.; Kent, P.R.C.; Lupini, A.R.; Stocks, G.M. Phys. Rev. X 2015, 5(1), 011041.
[^3]: Guo, S.; Ng, C.; Lu, J.; Liu, C.T. J. Appl. Phys. 2011, 109, 103505.
[^4]: Fang, S.S.; Xiao, X.S.; Xia, L.; Li, W.H.; Dong, Y.D. J. Non-Cryst. Solids 2003, 321, 120–125.
[^5]: Yang, X.; Zhang, Y. Mater. Chem. Phys. 2012, 132, 233–238.
[^6]: Wang, Z.; Huang, Y.; Yang, Y.; Wang, J.; Liu, C.T. Scr. Mater. 2015, 94, 28–31.
[^7]: Singh, A.K.; Kumar, N.; Dwivedi, A.; Subramaniam, A. Intermetallics 2014, 53, 112–119.
[^8]: Guo, S.; Hu, Q.; Ng, C.; Liu, C.T. Intermetallics 2013, 41, 96–103.
[^9]: Ye, Y.F.; Wang, Q.; Lu, J.; Liu, C.T.; Yang, Y. Scr. Mater. 2015, 104, 53–55.
[^10]: Senkov, O.N.; Miracle, D.B. J. Alloys Compd. 2016, 658, 603–607.
[^11]: King, D.J.M.; Middleburgh, S.C.; McGregor, A.G.; Cortie, M.B. Acta Mater. 2016, 104, 172–179.
[^12]: Mann, J.B.; Meek, T.L.; Allen, L.C. J. Am. Chem. Soc. 2000, 122, 2780–2783.
[^13]: Mann, J.B.; Meek, T.L.; Knight, E.T.; Capitani, J.F.; Allen, L.C. J. Am. Chem. Soc. 2000, 122, 5132–5137.
[^16]: Haynes, W.M. CRC Handbook of Chemistry and Physics, 95th ed.; CRC Press: Boca Raton, FL, 2014. ISBN 9781482208689.
[^17]: Hume-Rothery, W.; Smallman, R.E.; Haworth, C.W. The Structure of Metals and Alloys, 5th ed.; Institute of Metals: London, 1969.
[^18]: Takeuchi, A.; Inoue, A. Mater. Trans. 2005, 46(12), 2817–2829.
[^19]: Ye, Y.F.; Wang, Q.; Lu, J.; Liu, C.T.; Yang, Y. Intermetallics 2015, 59, 75–80.
[^20]: Mansoori, G.A.; Carnahan, N.F.; Starling, K.E.; Leland, T.W., Jr. J. Chem. Phys. 1971, 54, 1523–1525.
[^21]: Guo, S.; Liu, C.T. Prog. Nat. Sci.: Mater. Int. 2011, 21, 433–446, Table 1.
[^22]: Kittel, C. Introduction to Solid State Physics, 8th ed.; Wiley, 2005; Chapter 3, Table 9.

---

## License

This project is licensed under the GNU GPLv3 License. See the [LICENSE](https://github.com/dogusariturk/HEACalculator/blob/master/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:

```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},
}
```
