# hea-bench

> Open, interpretable calculator of the standard high-entropy-alloy (HEA)
> and high-entropy-oxide (HEO) thermodynamic and geometric descriptors
> plus the canonical empirical phase-prediction rules. Every quantity is a
> transparent closed-form expression over a curated element-property
> table — no fitted model, no black box. One calculation core ships as a
> Python library, a zero-install browser app, and a native desktop app;
> the browser core is parity-tested against the Python library.

`hea-bench` is composition-only and dependency-free in its core.
Use it to (1) compute HEA descriptors as features for downstream
models, (2) screen candidate alloys with the published empirical
rules, or (3) compute high-entropy-oxide (HEO) formability
descriptors via the `hea_bench.oxides` module. Currently shipping
version 2.3.1 under MIT.

## For AI agents reading this first

Read [AGENTS.md](AGENTS.md) for the full machine-oriented API
guide: the public surface, exact return units, the copy-pasteable
jumpstart that verifies your install against the canonical
Cantor-alloy sanity values, and the mistakes to avoid.

## Mental model

A composition is a plain `dict` mapping element symbol to amount.
Amounts do not need to sum to 1; they are normalised internally.

```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)
hb.phi_king(cantor)    # 3.533  (King 2016 proxy)
hb.phi_ye(cantor)      # 34.822 (Ye 2015 proxy)
```

## Descriptors

| Descriptor | Function | Unit |
|---|---|---|
| Mixing entropy ΔS_mix | `hb.smix(comp)` | J/(mol·K) |
| Atomic-size mismatch δ | `hb.delta(comp)` | percent |
| Valence electron concentration | `hb.vec(comp)` | electrons |
| Melting temperature T_m | `hb.melting_temperature(comp)` | K |
| Mixing enthalpy ΔH_mix | `hb.mixing_enthalpy(comp)` | kJ/mol |
| Yang-Zhang Ω | `hb.omega(comp)` | dimensionless |
| Mansoori excess entropy S_E | `hb.s_excess(comp)` | J/(mol·K) |
| Disordered SS Gibbs energy ΔG_ss | `hb.delta_g_ss(comp)` | kJ/mol |
| Most-negative pair enthalpy ΔG_max | `hb.delta_g_max(comp)` | kJ/mol |
| King capital Φ | `hb.phi_king(comp)` | dimensionless |
| Ye lowercase φ | `hb.phi_ye(comp)` | dimensionless |
| Electronegativity mismatch Δχ | `hb.delta_chi(comp)` | Pauling scale |
| Mean electronegativity χ̄ | `hb.mean_electronegativity(comp)` | Pauling scale |
| Singh Λ = ΔS/δ² | `hb.singh_lambda(comp)` | J/(mol·K·%²) |
| Wang solid-angle γ | `hb.wang_gamma(comp)` | dimensionless |
| Andreoli elastic-strain ΔH_el | `hb.h_elastic(comp)` | kJ/mol (None if data missing) |

## Rules

| Rule | Predicts | Default cutoff |
|---|---|---|
| `rules.yeh_smix` | HEA / MEA / dilute | descriptive |
| `rules.zhang_delta` | single-phase / multi-phase | δ < 6.5% |
| `rules.guo_vec` | FCC / BCC / mixed | VEC ≥ 8.0 / < 6.87 |
| `rules.yang_omega` | single-phase / multi-phase | Ω > 1.1 |
| `rules.king_phi` | solid_solution / intermetallic | Φ > 1.0 |
| `rules.ye_phi` | solid_solution / intermetallic | φ > 20.0 |
| `rules.senkov_kappa` | solid_solution / intermetallic at T | k₁ < k₁ᶜʳ(T), k₂ = 0.6 |
| `rules.tsai_sigma` | sigma_prone / sigma_unlikely / not_applicable | Cr/V and 6.88 ≤ VEC ≤ 7.84 |
| `rules.sheikh_ductility` | ductile / brittle / borderline | VEC < 4.5 / ≥ 4.6 (bcc RHEAs) |

The rules are weak, semi-empirical screens (calibrated on small
historical datasets); do not treat a single prediction as ground truth.
Note Ω diverges as ΔH_mix → 0, so it is parametrization-sensitive for
near-ideal alloys.

## Oxides module

`hea_bench.oxides` extends the calculator to high-entropy oxides:
four structure families (`describe_rock_salt`, `describe_perovskite`,
`describe_fluorite`, `describe_pyrochlore`), each returning one dict
with solved oxidation states (charge balance against the oxygen
sublattice), Shannon (1976) radii, per-sublattice configurational
entropy, size-disorder parameters, the perovskite tolerance factors
(Goldschmidt t, octahedral μ, Bartel τ < 4.18), the Spiridigliozzi
fluorite radius-dispersion rule (σ > 0.095 Å), the pyrochlore
radius-ratio window (1.46–1.78), and electronegativity statistics.
Same closed-form philosophy, 94 vendored elements, parity-tested in
the browser core, exposed as the Oxides mode in the apps. See
AGENTS.md for examples.

## Browser and desktop apps

An MCP server ships in the package: `pip install "hea-bench[mcp]"`,
then `hea-bench-mcp` exposes seven deterministic tools
(parse_composition, batch alloy_descriptors / alloy_rules,
omega_sensitivity, oxide_report, element_coverage, about) with units,
citation keys, and the library version stamped into every response.
Agents should call these instead of reimplementing formulas.

A self-contained HTML calculator (`web/index.html`) computes the
same descriptors and rules in client-side JavaScript with no install,
and additionally shows the Miedema formation-enthalpy decompositions.
Hosted at <https://dfieser.github.io/hea-bench/> (the page is the
calculator; link `index.html#theory`, `#equations`, `#refs` directly);
also wrapped as a single offline desktop executable via Tauri that loads
the same page. The JS core is regression-checked against
the Python library in CI (`tests/test_web_parity.py` and
`tests/test_web_oxides_parity.py`).

## Reference papers

- Yeh et al. 2004, *Adv. Eng. Mater.* 6, 299 — ΔS_mix rule.
- Cantor et al. 2004, *Mater. Sci. Eng. A* 375-377, 213 — Cantor alloy.
- Zhang et al. 2008, *Adv. Eng. Mater.* 10, 534 — δ rule.
- Guo & Liu 2011, *Prog. Nat. Sci.* 21, 433 — VEC rule.
- Yang & Zhang 2012, *Mater. Chem. Phys.* 132, 233 — Ω rule.
- King et al. 2016, *Acta Mater.* 104, 172 — Φ rule.
- Ye et al. 2015, *Scripta Mater.* 104, 53 — φ rule.
- de Boer et al. 1988, *Cohesion in Metals* — Miedema model parameters.
- Zhang R.F. et al. 2016, *Comput. Phys. Commun.* 209, 58 — Miedema formation enthalpies.
- Takeuchi & Inoue 2005, *Mater. Trans.* 46, 2817 — tabulated pair enthalpies.
- Mansoori et al. 1971, *J. Chem. Phys.* 54, 1523 — hard-sphere excess entropy.

## Citing

hea-bench is described in a Materials article; cite it when you use
the library:

```bibtex
@article{ma19143075,
  author         = {Fieser, David and Dewanjee, Unmanaa and Hu, Anming},
  title          = {{HEA-Bench}: An {AI}-Agent-Optimized Calculator of High-Entropy Alloy and Oxide Descriptors and Phase-Prediction Rules},
  journal        = {Materials},
  volume         = {19},
  year           = {2026},
  number         = {14},
  article-number = {3075},
  issn           = {1996-1944},
  doi            = {10.3390/ma19143075},
  url            = {https://www.mdpi.com/1996-1944/19/14/3075},
}
```

To reference the exact software version used, additionally cite the
archived software record:

```bibtex
@software{hea_bench,
  author  = {Fieser, David and Dewanjee, Unmanaa and Hu, Anming},
  title   = {hea-bench: An open calculator of high-entropy-alloy and high-entropy-oxide thermodynamic descriptors and empirical phase-prediction rules},
  version = {2.3.1},
  license = {MIT},
  doi     = {10.5281/zenodo.20346287},
  url     = {https://github.com/dfieser/hea-bench},
}
```
