hea-bench AGENTS.md

AGENTS.md

Machine-oriented usage guide for hea-bench. If you are an AI coding agent integrating this library into another project, read this first. It tells you the public API, exact return types and units, the fastest path to each common task, and the mistakes to avoid. Every snippet here is copy-pasteable and was checked against the shipped code.

Editing this repo's own docs (or this file)? Follow the writing rule in CONTRIBUTING.md: minimize jargon and explain any necessary term inline in plain language, and always state what a number is and its units. Don't defer to a glossary.

What this is

hea-bench is an open, interpretable calculator of the standard high-entropy-alloy (HEA) 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, three surfaces:

1. Python library + CLI — this package (pip install hea-bench).
2. Zero-install browser app — web/index.html (hosted at https://dfieser.github.io/hea-bench/; the page is the calculator).
3. Native desktop app — a single offline executable that wraps the browser app via Tauri.
4. MCP server — pip install "hea-bench[mcp]" then run hea-bench-mcp (stdio). Thirteen deterministic tools over this same library: parse_composition, batch alloy_descriptors / alloy_rules, omega_sensitivity (pair-table robustness check), oxide_report, element_coverage, corpus_query / corpus_describe (the provenance-tracked corpus; needs the locally built data), predict_properties (intervals and domain flags at payload top level), check_applicability, design_search (hard caps enforced), campaign_suggest (operates on a user-supplied campaign file), and about, which reports per-capability availability. Every response carries units or uncertainty fields, a citation key where a parametrization is involved, and the library version. If you are an agent with MCP support, prefer those tools over reimplementing the formulas below; if not, the Python API is identical.