hea-bench

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dfieser/hea-bench/main/docs/assets/banner-dark.png">
  <img src="https://raw.githubusercontent.com/dfieser/hea-bench/main/docs/assets/banner-light.png" alt="HEA-Bench: the standard descriptors for high-entropy alloys and oxides, with the work shown.">
</picture>

# hea-bench

<!-- mcp-name: io.github.dfieser/hea-bench -->

[![Paper](https://img.shields.io/badge/Materials-10.3390%2Fma19143075-2f7d3b)](https://doi.org/10.3390/ma19143075)
[![DOI](https://zenodo.org/badge/1246292321.svg)](https://doi.org/10.5281/zenodo.20346287)
[![PyPI](https://img.shields.io/pypi/v/hea-bench?color=8b3a2f)](https://pypi.org/project/hea-bench/)
[![Python](https://img.shields.io/pypi/pyversions/hea-bench)](https://pypi.org/project/hea-bench/)
[![CI](https://github.com/dfieser/hea-bench/actions/workflows/ci.yml/badge.svg)](https://github.com/dfieser/hea-bench/actions/workflows/ci.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](./LICENSE)

Open, interpretable tools for computing the standard **high-entropy-alloy
(HEA) and high-entropy-oxide (HEO) thermodynamic and geometric
descriptors** and the classic empirical **phase-prediction rules**, from
any composition. Every descriptor is a transparent closed-form expression
over a curated element-property table, validated against the primary
literature. The fitted predictions (hardness, phase prediction sets) carry
calibrated uncertainty and flag alloys unlike their training data.

**Try it now:** <https://dfieser.github.io/hea-bench/>. No install, it runs
entirely in your browser, and every library feature works there: the
calculator for alloys, oxides and ceramics with property and phase
predictions, the experimental dataset, alloy search and experiment
planning, and the benchmark.

<picture>
  <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/dfieser/hea-bench/main/docs/assets/screenshot-calculator-dark.png">
  <img src="https://raw.githubusercontent.com/dfieser/hea-bench/main/docs/assets/screenshot-calculator-light.png" alt="The HEA-Bench browser calculator showing the equimolar Cantor alloy CoCrFeMnNi, with the composition on the left and the computed descriptors on the right.">
</picture>

<sup>The equimolar Cantor alloy CoCrFeMnNi, as the browser app reports it.
The Python library, the desktop app and this page print the same digits, and
a parity suite keeps it that way.</sup>

> **Using an AI coding agent to integrate this?** See
> [AGENTS.md](./AGENTS.md) for a machine-oriented guide to the API,
> exact return types and units, the fastest path to each task, and the
> mistakes to avoid.

## What it computes

For any composition it reports:

- **Core descriptors:** mixing entropy ΔS<sub>mix</sub>, atomic-size
  mismatch δ, mean melting temperature T<sub>m</sub>, Miedema mixing
  enthalpy ΔH<sub>mix</sub>, valence-electron concentration VEC,
  Yang–Zhang Ω, Pauling electronegativity mismatch Δχ, Mansoori excess
  entropy S<sub>E</sub>, ΔG<sub>ss</sub>, ΔG<sub>max</sub>, King Φ, Ye φ.
- **Phase-prediction rules:** Yeh entropy, Zhang δ, Guo–Liu VEC,
  Yang–Zhang Ω, King Φ, Ye φ.
- **Miedema formation enthalpies** (browser/desktop apps): compound /
  solid-solution / amorphous, decomposed into chemical, elastic,
  structural, and topological terms.
- **High-entropy oxides** (`hea_bench.oxides` + the apps' Oxides mode):
  rock-salt, perovskite, fluorite, and pyrochlore formability
  descriptors over Shannon ionic radii with automatic charge-balance
  oxidation-state assignment: per-sublattice configurational entropy,
  cation size disorder, Goldschmidt t / octahedral μ / Bartel τ, the
  fluorite radius-dispersion rule, and the pyrochlore radius-ratio
  window.

Element coverage: 55 elements for alloys (Ag Al Au Be Bi Ca Ce Co Cr
Cu Dy Er Fe Ga Gd Ge Hf Ho In Ir La Li Lu Mg Mn Mo Nb Nd Ni Os Pb Pd
Pr Pt Re Rh Ru Sb Sc Si Sm Sn Sr Ta Tb Th Ti Tm U V W Y Yb Zn Zr,
covering the full experimentally active rare-earth HEA palette plus the
nuclear, solder, and HE-BMG corners); the Miedema pair table covers
75 (1484 of our 1485 pairs; the lone Th-U gap is reported, never
zeroed); the oxide module's Shannon table covers 94.

## How a number gets made

No fitted model sits anywhere in this chain. Each descriptor is a
closed-form expression over curated tables, and the report carries the
literature source of every input alongside the value.

```mermaid
flowchart LR
    A["Composition<br/>CoCrFeMnNi"] --> B["Curated element tables<br/>55 elements, 1484 Miedema pairs"]
    B --> C["Closed-form descriptors<br/>ΔS, δ, VEC, ΔH, Ω, Φ, φ, Λ, γ, κ"]
    C --> D["Empirical phase rules<br/>Yeh, Zhang, Guo-Liu, Yang-Zhang, King, Ye"]
    C --> E["Report<br/>per-value provenance, content-hashed result ID"]
    D --> E
```

## Four ways to run it

| Surface | Where | Status |
|---|---|---|
| **Python library + CLI** | `pip install hea-bench` | done, tested |
| **Zero-install browser app** | <https://dfieser.github.io/hea-bench/> · `web/index.html` | done, Python-parity-tested |
| **Native desktop app** | a single portable `.exe`, [download (no install)](https://github.com/dfieser/hea-bench/releases/latest/download/HEA-Bench.exe) (Tauri wrapper of the same page) | done, built from the same parity-tested core |
| **MCP server for AI agents** | `pip install "hea-bench[mcp]"`, then `hea-bench-mcp` | done, thirteen tools over the same core |

The three surfaces share **one calculation core**. The browser/desktop
core (`web/hea-calculator-core.js`) is a pure-JS port of the Python
library, and `tests/test_web_parity.py` guarantees the two match on all
1484 binary pairs and the canonical multi-element fixtures, while
`tests/test_web_oxides_parity.py` does the same for the oxide module,
down to identical warning messages. The app's Dataset, Design and
Benchmark tabs and its predictions panel run the Python package itself,
unchanged, inside the page (Pyodide, `web/hea-engine-worker.js`), and
`tests/test_web_engine.py` checks that it returns exactly what CPython
returns. `tests/test_app_parity.py` fails CI whenever a public library
feature has no working app surface, so the app never falls behind the
library.

## Quick start (Python)

```bash
pip install hea-bench
```

```python
import hea_bench as hb

cantor = {"Co": 0.2, "Cr": 0.2, "Fe": 0.2, "Mn": 0.2, "Ni": 0.2}

hb.smix(cantor)               # 13.381 J/(mol·K)  = R · ln 5
hb.delta(cantor)              # 3.164 % atomic-size mismatch
hb.vec(cantor)                # 8.0 valence electrons
hb.mixing_enthalpy(cantor)    # -4.16 kJ/mol  (Miedema)
hb.omega(cantor)              # 5.79  (Yang–Zhang)
hb.delta_chi(cantor)          # 0.138 Pauling electronegativity mismatch
hb.s_excess(cantor)           # 0.318 J/(mol·K)  (Mansoori excess entropy)
hb.delta_g_max(cantor)        # -8.00 kJ/mol  (most-negative Miedema pair)
hb.phi_king(cantor)           # 3.533 (King 2016 proxy)
hb.phi_ye(cantor)             # 34.82 (Ye 2015 proxy)

# Apply the canonical rules
from hea_bench.rules import guo_vec, king_phi, yang_omega, ye_phi, zhang_delta
zhang_delta.predict(cantor)          # 'single-phase'
yang_omega.predict(cantor)           # 'single-phase'
guo_vec.predict(cantor)              # 'FCC'
king_phi.predict(cantor)             # 'solid_solution'
ye_phi.predict(cantor)               # 'solid_solution'
```

These Cantor-alloy values are pinned in the test suite as the canonical
sanity check. The rules are simple empirical surrogates, fast screens
rather than predictions, so treat their output accordingly.

### Descriptor backends (optional interop)

Descriptors can also be computed through a pluggable backend. The
default (`native`) is this package's own stdlib implementation; with
`pip install "hea-bench[interop]"` the same interface drives an
installed [HEACalculator](https://github.com/dogusariturk/HEACalculator)
(GPLv3, installed at the user's choice), so a workflow standardized on
its numbers can keep them while using everything downstream here:

```python
from hea_bench.descriptors.backend import get_backend
get_backend("heacalculator").compute(cantor)   # same names, their reference data
```

```bash
hea-bench describe Al0.3CoCrFeNi --backend native
```

The two backends vendor different reference data (radius conventions
differ most), so same-named values legitimately differ; the measured,
per-descriptor comparison lives in
[docs/backend-agreement.md](docs/backend-agreement.md). Quantities
whose implementations differ structurally are deliberately not mapped
onto each other, and the benchmark's published baselines use the
native backend unchanged.

## Quick start (oxides)

```python
from hea_bench import oxides

# Rost 2015 "J14" entropy-stabilized rock salt
j14 = oxides.describe_rock_salt({"Mg": 1, "Co": 1, "Ni": 1, "Cu": 1, "Zn": 1})
j14["descriptors"]["s_config"]       # 13.382 J/(mol·K) = R·ln 5
j14["oxidation_states"]              # all 2+ by charge balance

# Jiang 2018 single-phase high-entropy perovskite
pvk = oxides.describe_perovskite({"Sr": 1}, {"Zr": 1, "Sn": 1, "Ti": 1, "Hf": 1, "Mn": 1})
pvk["descriptors"]["goldschmidt_t"]  # 0.979, inside the 0.92–1.04 window
pvk["verdicts"]["bartel"]            # 'perovskite' (τ = 3.72 < 4.18)
```

Each `describe_*` report carries the solved oxidation states, the
Shannon radii actually used, every descriptor, the formability
verdicts with their windows, and any warnings. See
[`examples/02_oxides_walkthrough.py`](./examples/02_oxides_walkthrough.py)
for the full tour, including the fluorite and pyrochlore screens and
oxidation-state overrides.

## Quick start (ceramics, experimental)

`hea_bench.ceramics` extends the calculator to rock-salt carbides and
nitrides and AlB2-type diborides, composition-only and honest about
what that buys:

```python
from hea_bench import ceramics

hec = ceramics.describe_rock_salt_carbide({"Ti": 1, "Zr": 1, "Hf": 1, "Nb": 1, "Ta": 1})
hec["ve