Skip to content

Installation & Quick Start

Requirements

  • Python 3.10 or later
  • uv (recommended) or pip

Installing HEACalculator

Note: GUI support requires PyQt6, which is an optional dependency. Install with the [gui] extra only if you intend to use the graphical interface.

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          # CLI only
uv add "HEACalculator[gui]"   # with GUI support

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 run the GUI without installing permanently:

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

Installing from Source

If you don't have uv, install it first:

curl -LsSf https://astral.sh/uv/install.sh | sh

Then clone and sync:

git clone https://github.com/dogusariturk/HEACalculator.git
cd HEACalculator

uv sync                   # Core dependencies (CLI only)
uv sync --group dev       # Core + development tools (ruff, pytest, prek, ty)
uv sync --extra gui       # Core + GUI support (PyQt6)
uv sync --extra docs      # Core + documentation dependencies (mkdocs-material)

Alternatively with pip:

git clone https://github.com/dogusariturk/HEACalculator.git
cd HEACalculator
pip install .
pip install ".[gui]"      # with GUI support

Verifying the Installation

HEACalculator --help

Expected output:

Usage: HEACalculator [OPTIONS] COMMAND [ARGS]...

  A tool for calculating High-Entropy Alloy (HEA) specific parameters and
  solid-solution predictions.

Options:
  --help  Show this message and exit.

Commands:
  gui     Starts the HEACalculator Graphical User Interface (GUI).
  search  Parameter search commands

Quick Start

Calculate all parameters for FeCoCrNi:

HEACalculator search single FeCoCrNi

Screen a composition range for Al-Ti-V:

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

Run batch calculations from a CSV file:

HEACalculator search csv alloys.csv

Launch the GUI:

HEACalculator gui

Pre-commit Hooks (development)

Install pre-commit hooks after cloning to enable automatic linting and formatting on every commit:

uv run pre-commit install

Hooks run uv-lock (lockfile sync), ruff (linting and formatting), ty (type checking), and several file-hygiene checks (trailing whitespace, end-of-file, YAML/TOML validation, etc.).

Citation

If you use HEACalculator in your research, please cite:

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

BibTeX 
@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},
}