Provides deterministic tools for computing thermodynamic and geometric descriptors and phase-prediction rules for high-entropy alloys and oxides.
Also known as dfieser/hea-bench
- Stars
- 3
- Tools
- 24
- Downloads, 30 days
- 483
- Latest version
- 2.9.4
- Last commit
- Nov 8, 2026
- License
- MIT
What is HEA-Bench MCP?
HEA-Bench provides deterministic tools for computing thermodynamic and geometric descriptors and phase-prediction rules for high-entropy alloys and oxides. It exposes 24 tools, such as parse_composition, alloy_descriptors, alloy_rules.
Summary generated from the project's README
About HEA-Bench MCP server
HEA-Bench provides deterministic tools for calculating thermodynamic and geometric descriptors for high-entropy alloys and oxides. Designed for materials scientists and researchers, it offers transparent, closed-form expressions based on curated element-property tables. The server functions as an MCP server for AI agents, providing 24 tools to ground large language models in factual material science data rather than allowing them to hallucinate values.
Users can interact with the system through various interfaces including a Python library, a web application, a desktop executable, or an MCP client like Claude or Cursor. The server handles complex calculations such as mixing entropy, atomic-size mismatch, Miedema mixing enthalpy, and valence-electron concentration. It also includes specialized modules for high-entropy oxides, covering rock-salt, perovskite, fluorite, and pyrochlore formability using Shannon ionic radii and automatic charge-balance oxidation-state assignment.
What you can do with it
- 1Calculate alloy descriptorsAn AI agent can compute specific thermodynamic values like mixing entropy or atomic-size mismatch for a given chemical composition.
- 2Predict material phasesDevelopers can use the tool to apply empirical rules to determine if an alloy will form a single phase or a specific structure.
- 3Analyze high-entropy oxidesThe server can evaluate the formability of oxides like perovskites or fluorites using ionic radii and oxidation states.
- 4Ground AI hallucinationsThe MCP server provides a way to ensure AI coding agents use accurate, literature-validated material properties.
Written from the project's README. Every use case is checked against a quote from it.
How to install HEA-Bench MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall HEA-Bench MCP in Claude Code
$ claude mcp add hea-bench -- uvx --from 'hea-bench[mcp]' hea-bench-mcpInstall HEA-Bench MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"hea-bench": {
"command": "uvx",
"args": [
"--from",
"hea-bench[mcp]",
"hea-bench-mcp"
]
}
}
}Install HEA-Bench MCP in VS Code
.vscode/mcp.json
{
"servers": {
"hea-bench": {
"type": "stdio",
"command": "uvx",
"args": [
"--from",
"hea-bench[mcp]",
"hea-bench-mcp"
]
}
}
}Install HEA-Bench MCP in VS Code CLI
$ code --add-mcp '{"name":"hea-bench","type":"stdio","command":"uvx","args":["--from","hea-bench[mcp]","hea-bench-mcp"]}'Install HEA-Bench MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"hea-bench": {
"command": "uvx",
"args": [
"--from",
"hea-bench[mcp]",
"hea-bench-mcp"
]
}
}
}Install HEA-Bench MCP in Codex
$ codex mcp add hea-bench -- uvx --from 'hea-bench[mcp]' hea-bench-mcpInstall HEA-Bench MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.hea-bench] command = "uvx" args = ["--from", "hea-bench[mcp]", "hea-bench-mcp"]
Install HEA-Bench MCP in Gemini CLI
$ gemini mcp add -s user hea-bench uvx -- --from 'hea-bench[mcp]' hea-bench-mcpInstall HEA-Bench MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"hea-bench": {
"command": "uvx",
"args": [
"--from",
"hea-bench[mcp]",
"hea-bench-mcp"
]
}
}
}Started by HostedMCP on 16 Nov 2026
We ran this command for hea-bench 2.9.4 in an isolated container with no network and no keys. It answered and listed 24 tools.
HEA-Bench MCP tools 24
Read from the server with tools/listparse_compositionRead-onlyParse a chemical formula into normalized mole fractions. Accepts forms like ``CoCrFeMnNi`` (equimolar), ``Al0.3CoCrFeNi``, or ``Co20Cu20Fe5Mn35Ni20`` (percent-style amounts). Amounts are normalized to fractions that sum to 1.
alloy_descriptorsRead-onlyCompute every alloy descriptor for a batch of compositions. Each value is returned with its unit and the citation key of its parametrization (see ``about()`` for the key -> reference map). Compositions containing elements outside the curated 55-element table return ``null`` for the affected descriptors plus a warning, never a silent wrong number. ``miedema_enthalpies`` carries the compound, solid-solution and amorphous formation enthalpies of the Miedema model (37 elements). ``king_temperature`` (kelvin) optionally overrides the rule-of-mixtures melting temperature used by the King Phi proxy and the Senkov-Miracle kappa criterion. ``custom_elements`` and ``pair_enthalpies`` add elements and pair values for this call only, like the app's custom-element and pair editors.
alloy_rulesRead-onlyApply the nine canonical empirical phase-prediction rules to a batch. Each verdict comes with the descriptor value it was judged on and the published threshold, so the margin is auditable. These rules are weak empirical screens calibrated on small historical datasets. Treat verdicts as hints, never ground truth. A rule outside its domain says ``not_applicable``: Tsai without Cr or V, and Sheikh with any element beyond Ti, Zr, Hf, V, Nb, Ta, Cr, Mo and W. ``guo_vec`` carries a ``note`` when VEC sits within 0.2 of a Guo cutoff. ``senkov_kappa`` carries one when an element of the pair behind Senkov's ΔH_IM (``im_pair``) is under 10 at.%. The ``note`` is null when there is nothing to say. ``custom_elements`` and ``pair_enthalpies`` work as in ``alloy_descriptors``.
omega_sensitivityRead-onlyReport how sensitive Omega is to the choice of Miedema pair table. Omega diverges as the mixing enthalpy approaches zero, so for near-ideal alloys its value depends strongly on which published pair table supplies the enthalpies. This tool returns the per-pair contributions ``4 H_ij c_i c_j`` and identifies the element whose pairs dominate the enthalpy. It then recomputes Omega with that element's pair enthalpies shifted by +/- ``perturbation_kj_mol`` (default 2 kJ/mol, the typical spread between published Miedema compilations). A wide Omega range means the verdict, not the number, is what to trust.
oxide_reportRead-onlyFull formability report for a high-entropy oxide composition. ``family`` is one of ``rock_salt``, ``perovskite``, ``fluorite``, or ``pyrochlore``. ``cations`` is a formula-style string for the cation sublattice (the A site for perovskite/pyrochlore, which also require ``b_site_cations``). ``oxygen_per_formula_unit`` applies to fluorite only (default 2.0). ``spin`` selects high- or low-spin Shannon radii for the 3d cations where the tables distinguish them. The report contains the charge-balance oxidation states, the Shannon radii used, the sublattice entropy and size-disorder descriptors, the family's formability screens with their published windows, and every warning raised along the way. The screens are weak empirical criteria calibrated on small datasets, so treat verdicts as hints.
ceramic_reportRead-onlyComposition-only descriptors for a high-entropy carbide, nitride or diboride. ``structure`` is ``rock_salt_carbide``, ``rock_salt_nitride`` or ``diboride``, and ``metals`` is the metal-sublattice formula. The report gives the configurational entropy in every normalization that papers use. For the rock-salt structures it also gives the VEC per formula unit against the literature's reference points. It deliberately gives no formability verdict, because no single published window exists.
element_dataRead-onlyThe tabulated values behind every number, per element, with sources. Returns radius, melting point, valence, electronegativity, molar volume and moduli, each with its unit. The payload also names the radius source and where good sources disagree, which features each element supports, the cited references and the SHA-256 of every data file. Omitting ``elements`` returns all 55 elements.
element_coverageRead-onlyList which elements each data table covers. Use this before batch calls: compositions outside the alloy table produce warnings rather than numbers, and oxide cations outside the Shannon table raise structured errors.
corpus_buildActionBuild the corpus on this machine, once. Every corpus tool needs it. Every source dataset ships with the package, so the build needs no network. Builds every version by default. Rebuilding reproduces the same corpus, so calling it again is harmless.
corpus_queryRead-onlyFilter the consolidated experimental corpus and sample matching rows. Filters AND together: ``elements`` is an exact element-set match, ``contains``/``excludes`` are memberships, ``phase`` matches the consensus label, ``source`` the contributing dataset. Returns the match count plus a sample capped at 50 rows, each carrying full provenance (per-source canonical and verbatim labels, processing, DOI, upstream row ids). ``corpus_export`` writes the whole slice to a CSV file. The corpus is built on this machine rather than shipped, for the licensing reasons in the corpus card. ``corpus_build`` builds it once.
corpus_describeRead-onlySummary statistics for a filtered corpus slice. Counts by phase, element count, source, and family, plus the multi-source agreement rate (its complement is the conflict quarantine). Same filters as ``corpus_query``.
corpus_exportActionWrite a filtered corpus slice to a new CSV file, every column kept. Same filters as ``corpus_query``, in the consolidated-CSV schema the app's Download button produces. Refuses to overwrite an existing file.
Show all 24 toolsShow fewer tools
measured_propertiesRead-onlyMeasured hardness or density from Borg et al. (2020), with DOIs. Returns the measurements the hardness model trains on, or the densities the rule-of-mixtures estimate is checked against. ``contains`` keeps only alloys containing every one of its elements. The result gives the exact match count and a sample capped at 50 rows.
predict_propertiesRead-onlyPredict properties with uncertainty and domain flags, per composition. Tier A (density, melting_temperature, cost_per_kg) is closed-form over cited tables. Tier B (hardness) is a fitted surrogate and always carries a conformal interval, its training-domain flag, and its model card reference. Every entry's ``interval``, ``in_domain``, ``tier``, and ``warnings`` sit at the top level of that property's payload. Missing optional installs come back as a clear error naming the pip command.
predict_phase_setRead-onlyPhase prediction with a conformal prediction set, per composition. The model is a random forest on the 14 descriptors, trained on the corpus, with split-conformal calibration. The set contains the true label about ``1 - alpha`` of the time on alloys like the calibration set. A set with more than one label means the model cannot decide. Each entry carries class probabilities, the corpus ``in_domain`` flag and novelty measures, and plain-language warnings. The first call per task fits the model (several seconds).
check_applicabilityRead-onlyReport whether a composition sits inside what the corpus covers. Returns the orthogonal novelty components (exact family seen and how often, nearest-family Jaccard distance, descriptor-cloud distance, element coverage) plus the conservative combined ``in_domain`` flag. Needs a built corpus. The components describe how well this package's corpus covers your query, nothing else.
design_searchRead-onlyConstrained Pareto screening over a palette. The expensive call. Hard caps, enforced before any work: at most 10 palette elements, step at least 0.05, at most 20 returned candidates, and a fixed 50,000-point lattice budget. An oversized request is refused with the cap named, never silently truncated. Objectives are ``[direction, property]`` pairs, e.g. ``[["maximize", "hardness"], ["minimize", "cost_per_kg"]]``. Fitted objectives rank by the conservative interval end by default. Every candidate carries descriptors, all nine rule verdicts, property predictions with intervals, novelty, the domain flag, and ``phase``: its four-class phase prediction set (null without a built corpus). An element cap such as ``{"element": "Al", "max": 0.2}`` keeps hardness searches from drifting to aluminides. Results are a screening aid, not answers. See docs/design-recovery.md.
campaign_suggestRead-onlyNext-batch suggestions for a campaign, from a file or inline. The campaign is plain JSON, as the app's Campaign panel and ``hea_bench.design.campaign.Campaign.save`` write it: give its path as ``campaign_path`` or its contents as ``campaign``. This tool never writes the file. An inline call gets the canonical campaign back to save. Batch size is capped at 10. Suggestions carry the ensemble mean, a 90 percent conformal interval set from the forest's out-of-bag errors (coverage measured in docs/campaign-replay.md), and the domain flag. Below the 10-observation floor the loop refuses rather than guessing.
benchmark_summaryRead-onlyThe paired benchmark at a glance: splits, digests and the published table. Two frozen 5-fold schemes cover the same rows. Random folds measure interpolation within known alloy families, and family-grouped folds measure extrapolation to unseen element systems. Returns the class balance and family overlap of each scheme, whether both match their frozen SHA-256 digests, the baselines you can score live with ``benchmark_run``, and the published results table for v0.1.0.
benchmark_runRead-onlyScore one published baseline live under both split schemes. Fits and scores ``model`` on every fold of the random and the family-grouped scheme, on the same rows as the published table. It reports per-scheme metrics plus the ``gap`` (random minus grouped), which measures how much harder extrapolation is than interpolation. The fitted baselines take tens of seconds.
benchmark_foldsActionWrite every benchmark row with its fold under both schemes to a new CSV. The file for training your own model offline: ``composition_key``, ``family``, ``label``, ``grouped_fold``, ``random_fold``, ``n_elements`` and ``descriptors_finite``. Score the predictions with ``benchmark_score``. Refuses to overwrite an existing file.
benchmark_scoreRead-onlyScore your own model's predictions under both split schemes. ``predictions_path`` is a CSV with the columns ``composition_key``, ``grouped`` and ``random``. The ``grouped`` and ``random`` columns hold the label your model predicted for the row while it sat in that scheme's test fold. The folds come from ``benchmark_folds``. Returns the same report as ``benchmark_run``, including the ``gap``.
coverage_studyRead-onlyCheck the phase prediction sets' coverage on held-out alloy families. Reruns the conformal coverage study under the family-grouped scheme. It reports how often the prediction set contains the true label at several miscoverage levels, for all test alloys and separately for the in-domain and out-of-domain groups. Takes a minute or more.
aboutRead-onlyVersion, provenance, license, capability availability, citations.
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachabledfieser/hea-bench is public and reachablegithub.com/dfieser/hea-bench ↗Pass
- Package names this repository as its sourcehea-bench names dfieser/hea-bench as sourcepypi.org/project/hea-bench/ ↗Pass
- Build provenance (Sigstore attestation)Sigstore attestation for hea-benchpypi.org/project/hea-bench/ ↗Pass
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-11-08github.com/dfieser/hea-bench ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from hea-benchPass
- No critical advisory in the package or its dependencies1 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model0 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNot checked
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubhea-bench
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/. It needs no install, runs entirely in your browser, and has every library feature: the calculator for alloys, oxides and ceramics with property and phase predictions, the experimental dataset, alloy search and experiment planning, and the benchmark.
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.
Using an AI coding agent to integrate this? See 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 ΔSmix, atomic-size mismatch δ, mean melting temperature Tm, Miedema mixing enthalpy ΔHmix, valence-electron concentration VEC, Yang–Zhang Ω, Pauling electronegativity mismatch Δχ, Mansoori excess entropy SE, ΔGss, ΔGmax, King Φ, Ye φ.
- Phase-prediction rules: Yeh entropy, Zhang δ, Guo–Liu VEC, Yang–Zhang Ω, King Φ, Ye φ, Senkov–Miracle κ, the Tsai σ-phase window and Sheikh ductility.
- Miedema formation enthalpies: compound / solid-solution / amorphous, decomposed into chemical, elastic, structural, and topological terms.
- Your own elements and pair values: any descriptor or rule, for a composition with an element or pair enthalpy that is not tabulated.
- 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 elements and 1484 of our 1485 pairs. The one missing pair, Th-U, is reported, never zeroed. The oxide module's Shannon table covers 94 elements.
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.
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, each with every feature
| Part | Where | Best for |
|---|---|---|
| Web app | https://dfieser.github.io/hea-bench/ | anyone, no install |
| Desktop app | one portable .exe, download (no install), the same app in its own window, engine inside, works offline |
Windows users who want it local |
| Python library + CLI | pip install "hea-bench[all]" |
scripts and notebooks |
| MCP server for AI agents | pip install "hea-bench[mcp]", then hea-bench-mcp |
Claude, Cursor and other MCP clients, as 24 tools |
Every feature is in all four parts, so pick whichever suits you and you lose nothing. This parity is a standing project rule, and CI enforces it four ways:
tests/test_feature_parity.pyfails whenever a public feature lacks its library function, its MCP tool or a working app surface.- A headless browser uses every tab of the built site.
- The built desktop exe goes through the same steps before it is attached to a release.
- A freshly installed wheel answers every MCP tool.
pip install hea-bench alone has no dependencies and covers everything
except the fitted models and the MCP server. The [all] extra adds
scikit-learn and the MCP SDK for those.
All four share one calculation core. The browser/desktop
core (web/hea-calculator-core.js) is a pure-JS port of the Python
library. tests/test_web_parity.py guarantees the two match on all
1484 binary pairs and the canonical multi-element fixtures, and
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).
tests/test_web_engine.py checks that the in-page package returns
exactly what CPython returns.
Quick start (Python)
pip install hea-bench
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)
A pluggable backend can also compute the descriptors. The default
(native) is this package's own stdlib implementation. With
pip install "hea-bench[interop]", the same interface drives an
installed HEACalculator
(GPLv3, installed at the user's choice). A workflow standardized on
HEACalculator's numbers can then keep them while using everything
downstream here:
from hea_bench.descriptors.backend import get_backend
get_backend("heacalculator").compute(cantor) # same names, their reference data
hea-bench describe Al0.3CoCrFeNi --backend native
The two backends vendor different reference data (radius conventions differ most), so same-named values legitimately differ. docs/backend-agreement.md gives the measured comparison for each descriptor. Quantities whose implementations differ structurally are deliberately not mapped onto each other. The benchmark's published baselines use the native backend unchanged.
Quick start (oxides)
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
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:
from hea_bench import ceramics
hec = ceramics.describe_rock_salt_carbide({"Ti": 1, "Zr": 1, "Hf": 1, "Nb": 1, "Ta": 1})
hec["vec_per_formula_unit"] # 8.4, with annotated literature reference points
hec["entropy"] # all normalization conventions, labelled
Reports carry the metal-sublattice entropy in every published normalization convention, because papers switch between them without warning. They give VEC with annotated reference points rather than a verdict, since the literature marks points, not one window. They also state what is deferred. The size-mismatch descriptor waits because the field computes it from DFT binary-cell bond lengths, and adopting a cited table is real curation work. Entropy-forming-ability and DEED are DFT-ensemble quantities that this package cannot and does not claim to reproduce. Background, citations, and a license audit of candidate ceramics datasets: docs/ceramics.md.
Quick start (AI agents, MCP)
LLM agents hallucinate descriptor values. This server grounds them.
hea_bench.mcp_server exposes every feature of the package over the
Model Context Protocol as 24
deterministic tools. The calculator: parse_composition, batch
alloy_descriptors (with the Miedema enthalpies) and alloy_rules,
both taking custom elements and pair values, omega_sensitivity,
oxide_report, ceramic_report, element_data and
element_coverage. The dataset: corpus_build (once, to build the
corpus locally), corpus_query, corpus_describe, corpus_export and
measured_properties. Predictions: predict_properties with
intervals and predict_phase_set with prediction sets, both carrying
the domain flag, and check_applicability. Design:
design_search, with hard caps on palette, step and candidate count,
and campaign_suggest, on a campaign file or an inline campaign. The
benchmark: benchmark_summary, benchmark_run, benchmark_folds,
benchmark_score and coverage_study. And about. Every response
carries units or uncertainty fields, citation keys where a
parametrization is involved, and the library version. An agent's
reasoning trace then contains auditable receipts rather than bare
floats. The about() tool reports which capabilities are available in
the running environment, and a missing optional extra comes back as a
clear message naming the exact install.
pip install "hea-bench[mcp]"
Register it with any MCP client (Claude Desktop, Cursor, ...), for
example in claude_desktop_config.json:
{ "mcpServers": { "hea-bench": { "command": "hea-bench-mcp" } } }
The omega_sensitivity tool is worth singling out: it reports the
per-pair Miedema contributions and how far Ω moves when the dominant
element's pair enthalpies are shifted within the spread of published
compilations, so an agent can ask not just for a number but for how
much to trust it.
Quick start (browser, no install)
The app runs entirely client-side. Its tabs:
- Calculator. Every descriptor, all nine phase rules, the Miedema decompositions, the robustness of Ω to the pair table, density, cost, hardness with its interval, the phase prediction set and the domain flag. Oxides and Ceramics (carbides, nitrides, diborides) are modes of the same tab.
- Dataset. The consolidated experimental corpus with every source's label and paper, filters and CSV download, plus the measured hardness and density data.
- Design. Composition search with property limits, rule filters and the Pareto front, and experiment planning from your own measurements.
- Benchmark. The frozen random and family-grouped splits, live baseline reruns, scoring of your own predictions, and the coverage study.
Two ways to open it:
- Open the hosted site: https://dfieser.github.io/hea-bench/.
- Or clone the repo, run
python tools/build_web_engine.pyonce (assembles the pinned in-page engine, about 30 MB), thenpython -m http.server -d weband open http://localhost:8000. Openingweb/index.htmldirectly from disk also works for the calculator, but browsers block the engine onfile://pages, so the other tabs need the local server.
The calculator ships its own documentation: a Theory view deriving
every alloy and oxide formula with citations, a grouped, filterable
Equations reference, and a grouped References bibliography.
Deep links open a view directly (index.html#theory,
#equations, #refs). The parity-critical math lives in
web/hea-calculator-core.js and is regression-checked against Python
by the two parity test suites.
Paired evaluation: the phase-prediction benchmark (experimental)
Published HEA phase-prediction accuracies are mostly measured with
random train/test splits over corpora full of stoichiometric series, so
models are tested on close variants of alloys they trained on. That
largely measures interpolation within known systems.
hea_bench.benchmark ships frozen, family-grouped and random paired
splits over a consolidated experimental corpus (~7,700 alloys) and an
evaluator that reports both side by side:
from hea_bench.benchmark import evaluate, load_benchmark
print(evaluate(my_model, load_benchmark(task="phase4")).table())
A stock random forest over this package's own descriptors scores 0.941
balanced accuracy under the random split and 0.734 under the grouped
one. Neither number is wrong. They answer different questions (new
stoichiometries of known systems versus unseen element systems). The
gap between them quantifies how much of the random-split score
comes from testing on close relatives of training alloys. For this
interpolation-versus-extrapolation reading of grouped evaluation, see
Li et al., Commun. Mater. 6:9 (2025),
doi:10.1038/s43246-024-00731-w.
Baselines, split digests, and full provenance:
docs/benchmark-baselines.md.
Every source dataset ships with the package under CC BY 4.0 (see
data/raw/README.md), and the corpus is built
from them on your machine, once, with no download.
hea_bench.corpus.build_corpus() checks the largest source against its
pinned SHA-256 and builds every corpus version. The apps and the MCP
server's corpus_build tool do the same.
The corpus as a standalone product
The consolidated experimental corpus behind the benchmark is also addressable directly, with no task or split machinery involved:
from hea_bench.corpus import load_corpus
corpus = load_corpus() # v0.2.0 (10,290 alloys), every row, full provenance
corpus.describe() # counts, families, agreement rate
al_bcc = corpus.query(contains=["Al"], phase="BCC", descriptor_ready=True)
al_bcc.rows[0].raw_labels # each source's verbatim reported phase
al_bcc.to_csv("al-bcc.csv")
Every row carries per-source canonical and verbatim labels, Borg's
processing route and primary-literature DOI where available, and
upstream record identifiers, so a label can be audited without leaving
the package. Provenance chains, per-source license status,
harmonization rules, and known limitations are documented in the
corpus card. load_corpus() opens the largest
version, v0.2.0, which adds the LLM-extracted Chizhevskiy database.
load_corpus(version="0.1.0") is the hand-curated reference (7,783
alloys) that the benchmark, the phase predictions and the domain flag
always use, so every published number stays put.
Uncertainty and domain of applicability
hea_bench.uncertainty is the trust layer for anything fitted on the
corpus. Conformal prediction wraps any sklearn-style model with
sets or intervals carrying a distribution-free finite-sample coverage
guarantee, and a domain-of-applicability model says whether that
guarantee's exchangeability assumption plausibly holds for your query:
from hea_bench.corpus import load_corpus
from hea_bench.uncertainty import ConformalClassifier, fit_domain
domain = fit_domain(load_corpus(version="0.1.0"))
domain.novelty({"Hf": 0.2, "Nb": 0.2, "Ta": 0.2, "Ti": 0.2, "Zr": 0.2})
# {'element_set_seen': True, 'family_count': ..., 'nearest_family_distance': 0.0,
# 'descriptor_distance': ..., 'element_coverage': True, 'in_domain': True, ...}
The novelty output is several deliberately orthogonal signals plus one
conservative in_domain flag, because the signals fail differently and
a single scalar invites misreading. Empirical coverage of the conformal
sets on unseen alloy systems, in and out of domain and by element
count, is measured in
docs/uncertainty-coverage.md. The
released phase sets calibrate by cross-validation over whole alloy
systems, separately for alloys with fewer than four and with four or
more elements. Their 90 percent sets cover 0.900 of unseen-system
alloys on the single-phase task and 0.884 on the phase-structure task.
Read the flag together with the set size rather than either alone.
These tools describe this package's confidence about your composition
on this corpus, nothing else.
Property predictions, in explicit tiers
hea_bench.properties predicts what experimentalists ask about first,
with the data quality stated in the API rather than implied:
from hea_bench.properties import predict_property
predict_property({"Al": 0.2, "Co": 0.2, "Cr": 0.2, "Fe": 0.2, "Ni": 0.2}, "hardness")
# PropertyPrediction(prop='hardness', value=..., unit='HV',
# interval=(low, high), alpha=0.1, tier='B',
# in_domain=True, n_training=..., ...)
Tier A (density, melting_temperature, and an explicitly indicative
cost_per_kg over a date-stamped, per-element-sourced price table) is
closed-form arithmetic over cited tables, validated where experiment
exists (docs/property-tier-a.md).
Tier B (hardness, behind pip install "hea-bench[properties]") is a
seeded random forest over this package's descriptors wrapped in a
family-grouped conformal interval and a domain flag.
docs/property-hardness.md states its
held-out error, its interval calibration, and the decisions that error
does and does not support. Intervals are wide because the public data
is small and heterogeneous. The wide interval is the honest outcome,
shown rather than hidden. Properties whose public data
cannot support a defensible held-out error (yield strength across
uncontrolled test temperatures, ductility, corrosion) are deliberately
not shipped, and the model card says why.
Constrained composition search
hea_bench.design.search answers "what should I make" as a screening
aid: a deterministic composition lattice over your palette, filtered by
rule, property, composition, and domain constraints, returning a Pareto
front where every candidate carries its full receipt:
from hea_bench.design import Maximize, Minimize, PropertyConstraint, search
result = search(
elements=["Al", "Co", "Cr", "Fe", "Ni"],
n_elements=(4, 5),
constraints=(PropertyConstraint("density", max=8.0),),
objectives=(Maximize("hardness"), Minimize("cost_per_kg")),
step=0.05,
)
result.candidates[0].properties["hardness"].interval # every number has one
The domain constraint is on by default, because optimizers exploit
model error hardest where data runs out. Opting out is explicit.
optimize_bound="lower" ranks fitted objectives by the conservative
end of their intervals. The search is exhaustive within a hard budget
and refuses loudly rather than sampling silently, so a result is
reproducible by construction.
docs/design-recovery.md studies where
measured alloys land relative to a recovered front. The front is a
prioritization aid, not a set of answers.
Active-learning campaigns (bring your own measurements)
hea_bench.design.campaign.Campaign runs the active-learning loop:
observe your own measurements, get a ranked next batch, and keep
everything in a plain JSON file on your disk (no accounts, no server,
no telemetry):
from hea_bench.design.campaign import Campaign
campaign = Campaign("hardness", ["Al", "Co", "Cr", "Fe", "Ni"])
campaign.observe({"Al": 0.1, "Co": 0.25, "Cr": 0.2, "Fe": 0.25, "Ni": 0.2}, 430.0)
campaign.suggest(n=5) # each Suggestion prints its interval and domain flag
campaign.save("my-campaign.json")
The surrogate is a seeded random forest. Each suggestion carries a 90 percent conformal interval set from the forest's out-of-bag errors, so calibration costs none of your measurements. Acquisition is expected improvement or UCB, with batched picks via the believer heuristic. Hardness campaigns warm start from the Borg records inside your palette, so the loop is useful before your tenth sample. Below 10 informative rows it refuses rather than pretending. docs/campaign-replay.md has two replays on the Borg hardness record: the loop against random selection, with the intervals' coverage, and a year-ordered replay on Al-Co-Cr-Fe-Ni.
HEA-Bench MCP questions
How do I add HEA-Bench MCP to Claude Code?
Run claude mcp add hea-bench -- uvx --from 'hea-bench[mcp]' hea-bench-mcp in your terminal. Add --scope user to make it available in every project.
How do I add HEA-Bench MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does HEA-Bench MCP provide?
It exposes 24 tools, including parse_composition, alloy_descriptors, alloy_rules, omega_sensitivity, oxide_report.
How does the server ensure the accuracy of its calculations?
Every descriptor is a transparent closed-form expression over a curated element-property table, validated against primary literature, with no fitted models used in the calculation chain.
What kind of materials can I analyze?
The tool supports high-entropy alloys (HEA), high-entropy oxides (HEO), and certain ceramics like rock-salt carbides, nitrides, and AlB2-type diborides.
Can I use this with an AI agent?
Yes, the server exposes 24 deterministic tools via the Model Context Protocol to ground AI agents and prevent hallucinated descriptor values.