# 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.0.4 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 |

## 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 |

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

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