# 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 descriptor is a
> transparent closed-form expression over a curated element-property
> table — no fitted model, no black box. It also carries a
> provenance-tracked experimental phase corpus, a paired benchmark,
> hardness and phase predictions with calibrated uncertainty, and
> composition search. It ships as four parts, each with every feature:
> a Python library, an MCP server, a zero-install web app and a desktop
> app.

`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, (3) compute high-entropy-oxide (HEO) and ceramic formability
descriptors, or (4) browse the corpus, predict properties and phases,
search compositions and run the benchmark. Currently shipping
version 2.8.0 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, or a
formula string such as `"CoCrFeMnNi"` or `"(CoCrFeNi)95Al5"`.
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 / not_applicable | VEC < 4.5 / ≥ 4.6, only alloys of Ti, Zr, Hf, V, Nb, Ta, Cr, Mo, W |

The rules are weak, semi-empirical screens (calibrated on small
historical datasets); do not treat a single prediction as ground truth.
`rules.guo_vec.boundary_note` flags a VEC within 0.2 of either cutoff,
and the κ result names its strongest pair (`im_pair`) with a `note`
when that pair has an element under 10 at.%.
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.

## The four parts

Every feature is in all four, so use whichever fits.

The MCP server: `pip install "hea-bench[mcp]"`, then `hea-bench-mcp`
exposes 24 deterministic tools: parse_composition, batch
alloy_descriptors (with the Miedema enthalpies) and alloy_rules,
omega_sensitivity, oxide_report, ceramic_report, element_data,
element_coverage, corpus_build, corpus_query, corpus_describe,
corpus_export, measured_properties, predict_properties,
predict_phase_set, check_applicability, design_search,
campaign_suggest, benchmark_summary, benchmark_run, benchmark_folds,
benchmark_score, coverage_study and about. Units, citation keys and the
library version are stamped into every response. Agents should call
these instead of reimplementing formulas.

The Python library: `pip install "hea-bench[all]"` (the core alone has
no dependencies; the extra adds scikit-learn and the MCP SDK).

The web app at <https://dfieser.github.io/hea-bench/> runs entirely in
the browser: the calculator (alloys, oxides, ceramics, predictions),
the Dataset, Design and Benchmark tabs, and `#theory`, `#equations`,
`#refs` deep links. Its JS calculator core is regression-checked against
the Python library in CI (`tests/test_web_parity.py` and
`tests/test_web_oxides_parity.py`), and the other tabs run this package
itself in the page. The desktop app is the same app as one portable
Windows exe.

## 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.8.0},
  license = {MIT},
  doi     = {10.5281/zenodo.20346287},
  url     = {https://github.com/dfieser/hea-bench},
}
```
