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 --no-dev               # CLI only
uv sync --no-dev --extra gui   # CLI + GUI (PyQt6)
uv sync                        # Development: CLI + GUI + dev tools (ruff, pytest, prek, ty)
uv sync --extra docs           # Development + documentation tools (mkdocs-material)

Each command sets up the whole environment, so run the one you need. Running a different one later replaces it rather than adding to it.

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 ────────────────────────────────────────────────────────────────────╮
│ --version             -V        Show the HEACalculator version and exit.     │
│ --install-completion            Install completion for the current shell.    │
│ --show-completion               Show completion for the current shell, to    │
│                                 copy it or customize the installation.       │
│ --help                -h        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 the pre-commit hooks with prek after cloning to enable automatic linting and formatting on every commit:

uv run prek 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.).