hea-bench 0.1.0__tar.gz

hea_bench-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,39 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install package with dev extras
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev,data]"
+
+      - name: Lint with ruff
+        run: ruff check src tests
+
+      - name: Run test suite
+        run: pytest tests/ -q
+        # Tests that depend on the pointer-only Peivaste dataset skip
+        # automatically when that file is absent (it is not committed
+        # because the upstream repository declares no license). The
+        # Borg and Pei datasets are committed, so their loader tests
+        # and all benchmark-level tests run in CI.

hea_bench-0.1.0/.gitignore

@@ -0,0 +1,64 @@
+# Python build artifacts
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+*.egg
+build/
+/dist/
+.eggs/
+pip-wheel-metadata/
+
+# But DO commit the wheel served by the Pyodide frontend so the demo
+# "just works" after a clone. Rebuild this with:
+#   python -m pip wheel . --no-deps -w web/dist
+!web/dist/
+!web/dist/*.whl
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+.tox/
+.nox/
+coverage.xml
+
+# Linting / type-checking caches
+.ruff_cache/
+.mypy_cache/
+
+# IDE / editor cruft
+.vscode/
+.idea/
+*.swp
+.DS_Store
+Thumbs.db
+desktop.ini
+
+# Claude Code local settings
+.claude/
+
+# Working scratch
+.data-scratch/
+_scratch/
+data/raw/_scratch/
+
+# Per-source gitignores (only block sources whose upstream license forbids
+# redistribution — see data/raw/README.md). Sources released under CC-BY,
+# MIT, Apache, etc. are mirrored directly; not listed here.
+#
+# Peivaste (Iman-Peivaste/ML_HEAs_Phase_Dataset) — no upstream license declared
+data/raw/peivaste/*.csv
+data/raw/peivaste/*.xlsx
+data/raw/peivaste/*.ipynb
+
+# Built docs
+docs/_build/
+site/

hea_bench-0.1.0/AGENTS.md

@@ -0,0 +1,205 @@
+# 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.
+
+## What this library is
+
+`hea-bench` does two separate things:
+
+1. **Descriptors + rules** — pure functions that compute the six
+   canonical high-entropy-alloy (HEA) phase descriptors for a
+   composition, and the four canonical empirical phase-prediction
+   rules wrapped as classifiers.
+2. **A benchmark** — a versioned, deduplicated dataset of 7,784
+   experimentally characterized compositions with per-row provenance,
+   plus the machinery to score any rule or model against it with
+   diagnostic statistics.
+
+It is composition-only and dependency-free in its core. Use it to
+screen candidate alloys, to compute descriptors as features, or as a
+fixed reference benchmark to evaluate a new phase-prediction method.
+
+## Install and import
+
+```bash
+pip install hea-bench
+```
+
+```python
+import hea_bench as hb
+```
+
+Python >= 3.10. No required runtime dependencies for the core. The
+`[data]` and `[dev]` extras add pandas/matplotlib/pytest only.
+
+## The one mental model you need
+
+A **composition is a plain `dict`** mapping element symbol to amount:
+`{"Co": 0.2, "Cr": 0.2, "Fe": 0.2, "Mn": 0.2, "Ni": 0.2}`. Amounts do
+**not** need to sum to 1; they are normalized internally, so
+`{"Al": 1, "Co": 1, "Cr": 1}` is equiatomic AlCoCr. Every descriptor
+and rule accepts this dict directly. You rarely need anything else.
+
+## Descriptors (pure functions, exact units)
+
+All take a composition dict (or the result of `parse_formula`) and
+return a float.
+
+| Call | Returns | Unit | Notes |
+|---|---|---|---|
+| `hb.smix(comp)` | mixing entropy | J/(mol·K) | `-R Σ cᵢ ln cᵢ` |
+| `hb.delta(comp)` | atomic-size mismatch | **percent** (e.g. 3.164, not 0.03) | |
+| `hb.vec(comp)` | valence electron concentration | electrons | linear mean |
+| `hb.melting_temperature(comp)` | average melting point | K | rule-of-mixtures |
+| `hb.mixing_enthalpy(comp)` | Miedema mixing enthalpy | **kJ/mol** | semi-empirical estimate |
+| `hb.omega(comp)` | Yang-Zhang Ω | dimensionless | `Tm·ΔS / |ΔH|` |
+
+```python
+cantor = {"Co": 0.2, "Cr": 0.2, "Fe": 0.2, "Mn": 0.2, "Ni": 0.2}
+hb.smix(cantor)              # 13.381  (= R·ln 5)
+hb.delta(cantor)             # 3.164   (percent)
+hb.vec(cantor)               # 8.0
+hb.melting_temperature(cantor)  # 1801.2 (K)
+hb.mixing_enthalpy(cantor)   # -4.16   (kJ/mol)
+hb.omega(cantor)             # 5.794
+```
+
+These six values for the Cantor alloy are pinned in the regression
+suite; treat them as the canonical sanity check.
+
+## Parsing formula strings
+
+If you have a string rather than a dict, parse it first. The parser
+accepts compact formulas (`"CoCrFeMnNi"`), subscripted formulas
+(`"CuCoMn1.75NiFe0.25"`), and space-separated amounts.
+
+```python
+comp = hb.parse_formula("CoCrFeMnNi")   # dict-like Composition
+hb.normalize(comp)                      # explicit mole-fraction dict
+hb.smix(comp)                           # descriptors accept it directly
+```
+
+## Rules (classifiers)
+
+```python
+from hea_bench.rules import yeh_smix, zhang_delta, guo_vec, yang_omega
+```
+
+Each module exposes `predict(composition, ...)`, a `DESCRIPTION`
+string, and (for the tunable ones) a `DEFAULT_THRESHOLD`. Return
+values are strings:
+
+| Rule | Call | Returns one of | Threshold arg |
+|---|---|---|---|
+| Yeh ΔS_mix | `yeh_smix.predict(comp)` | `"HEA"` / `"MEA"` / `"dilute"` | fixed (descriptive) |
+| Zhang δ | `zhang_delta.predict(comp, threshold=6.5)` | `"single-phase"` / `"multi-phase"` | percent, default 6.5 |
+| Yang Ω | `yang_omega.predict(comp, threshold=1.1)` | `"single-phase"` / `"multi-phase"` | default 1.1 |
+| Guo-Liu VEC | `guo_vec.predict(comp)` | `"FCC"` / `"BCC"` / `"mixed"` | fixed bounds 8.0 / 6.87 |
+
+```python
+zhang_delta.predict(cantor)   # 'single-phase'
+guo_vec.predict(cantor)       # 'FCC'
+yeh_smix.predict(cantor)      # 'HEA'
+```
+
+**Important:** these rules are weak classifiers. On the consolidated
+benchmark both binary rules collapse to "predict single-phase almost
+always" (Youden's J of 0.075 and 0.032). Do not treat a rule's output
+as ground truth. If you need a confidence-aware answer, evaluate
+against the benchmark (below) rather than trusting a single predict().
+
+## Scoring against the benchmark
+
+```python
+from hea_bench.evaluate import build_report
+report = build_report()
+```
+
+`report` is a dict with keys `csv_path`, `n_rows_loaded`, and `rules`.
+`report["rules"]` has four entries: `zhang_delta_6_5`,
+`yang_omega_1_1`, `guo_vec_stratified`, `yeh_smix_descriptive`. Each
+entry is a dict of statistics:
+
+```python
+r = report["rules"]["zhang_delta_6_5"]
+r["accuracy"]      # 0.5670
+r["sensitivity"]   # 0.990
+r["specificity"]   # 0.085
+r["youden_j"]      # 0.075
+r["accuracy_ci95"] # (low, high) Wilson 95% interval
+r["confusion"]     # confusion matrix
+# also: n, n_positive_observed, n_negative_observed,
+#       true_positive, false_positive, true_negative, false_negative,
+#       positive_label
+```
+
+## Threshold sweeps / ROC
+
+```python
+from hea_bench.classifiers.diagnostic_stats import roc_sweep
+```
+
+Use this to find the accuracy-optimal or Youden-J-optimal threshold
+for a tunable rule. The shipped recalibration finding for the Zhang
+rule is J-optimal at δ < 2.5% (vs the canonical 6.5%); reproduce it
+rather than hard-coding it.
+
+## Command line
+
+```bash
+hea-bench --version
+python -m hea_bench.evaluate            # all four rules vs v0.1.0 benchmark
+python -m hea_bench.benchmark.coverage  # element-coverage analysis
+```
+
+On Windows set `PYTHONIOENCODING=utf-8` before these if the output
+contains Greek/math symbols, to avoid a cp1252 encode error.
+
+## Data layout
+
+- `data/consolidated/v0.1.0/consolidated.csv` — the benchmark, 7,784
+  rows. Join key is `composition_key`; `canonical_phase` is one of
+  BCC/FCC/HCP/multi-phase (blank when sources conflict); `sources` is
+  semicolon-separated provenance; `has_conflict` flags the 100
+  cross-source disagreements.
+- `data/consolidated/v0.1.0/{rule_baselines,coverage_report,manifest}.json`
+  — committed outputs, regenerated by the evaluate/coverage modules.
+- `data/raw/<source>/` — per-source provenance, licenses, SHA-256s.
+- `src/hea_bench/descriptors/data/` — vendored elemental table (24
+  elements) and the matminer Miedema pair table (75 elements).
+
+## Coverage limit (read before scaling up)
+
+The elemental data table covers **24 elements**, so 86.7% of the
+benchmark is scorable by every descriptor. Compositions containing
+elements outside the table (Mg, C, Zn, B, Sn, Re, and others) will
+not be fully scorable. Check coverage with
+`python -m hea_bench.benchmark.coverage` before assuming a dataset is
+fully evaluable.
+
+## Things not to do
+
+- **Do not edit the pinned numbers** in `tests/` to make a test pass.
+  Those values are derived from the data and code; a changed number
+  means real drift you should explain, not silence.
+- **Do not add elements to the elemental table** without a citable
+  source for the atomic radius, VEC, and melting point. Unsourced
+  values corrupt every descriptor that uses them.
+- **Do not treat `mixing_enthalpy` as a measured quantity.** It is a
+  semi-empirical Miedema estimate with known systematic error for
+  some pairs.
+- **Do not assume composition fixes phase.** The benchmark is
+  composition-only; the same composition can form different phases
+  depending on processing history.
+
+## Verifying your integration
+
+After wiring this in, confirm the Cantor sanity values
+(`smix=13.381`, `delta=3.164`, `vec=8.0`, `omega=5.794`) and run the
+test suite (`python -m pytest -q`, 155 tests). If those match, your
+environment is using the canonical implementation correctly.

hea_bench-0.1.0/CITATION.cff

@@ -0,0 +1,36 @@
+cff-version: 1.2.0
+title: "hea-bench: An open benchmark suite for high-entropy alloy phase prediction"
+message: >-
+  If you use this software, please cite it using the metadata from this file.
+type: software
+authors:
+  - given-names: David
+    family-names: Fieser
+    orcid: 'https://orcid.org/0009-0007-5754-4331'
+abstract: >-
+  hea-bench is a standardized, reproducible benchmark suite for high-entropy
+  alloy phase prediction. It consolidates published open HEA phase-label
+  datasets into a single curated benchmark, provides reference baseline
+  implementations of the canonical empirical descriptors and phase-prediction
+  rules treated as diagnostic classifiers, and ships a standardized evaluation
+  harness so any user-supplied model can be scored against the same dataset
+  and metrics.
+keywords:
+  - high-entropy alloys
+  - phase prediction
+  - materials informatics
+  - benchmark
+  - Miedema model
+  - thermodynamic descriptors
+license: MIT
+repository-code: 'https://github.com/dfieser/hea-bench'
+version: 0.1.0
+date-released: '2026-05-22'
+doi: 10.5281/zenodo.20346288
+identifiers:
+  - type: doi
+    value: 10.5281/zenodo.20346287
+    description: Concept DOI (resolves to all versions of hea-bench)
+  - type: doi
+    value: 10.5281/zenodo.20346288
+    description: Version DOI (this release, v0.1.0)

hea_bench-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,56 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation
+in our community a harassment-free experience for everyone, regardless
+of age, body size, visible or invisible disability, ethnicity, sex
+characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance,
+race, religion, or sexual identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open,
+welcoming, diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment
+include demonstrating empathy and kindness toward other people, being
+respectful of differing opinions and experiences, giving and
+gracefully accepting constructive feedback, accepting responsibility
+and apologizing to those affected by our mistakes, and focusing on
+what is best for the overall community.
+
+Examples of unacceptable behavior include the use of sexualized
+language or imagery and unwelcome sexual attention, trolling,
+insulting or derogatory comments, public or private harassment,
+publishing others' private information without explicit permission,
+and other conduct which could reasonably be considered inappropriate
+in a professional setting.
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing
+standards of acceptable behavior and will take appropriate and fair
+corrective action in response to any behavior that they deem
+inappropriate, threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies within all community spaces and also
+applies when an individual is officially representing the community
+in public spaces.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior
+may be reported to the maintainer responsible for enforcement at
+`davjfies@gmail.com`. All complaints will be reviewed and
+investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the
+[Contributor Covenant](https://www.contributor-covenant.org),
+version 2.1, available at
+https://www.contributor-covenant.org/version/2/1/code_of_conduct.html.

hea_bench-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,70 @@
+# Contributing to hea-bench
+
+Contributions are welcome, whether bug reports, new datasets, new
+descriptors or rules, additional elemental data, or documentation
+improvements.
+
+## Reporting issues and seeking support
+
+- **Bugs and feature requests:** open an issue on the GitHub issue
+  tracker. For a bug, please include the `hea-bench` version, your
+  Python version and operating system, a minimal composition or
+  command that reproduces the problem, and the full traceback.
+- **Questions and support:** open a GitHub issue with the
+  `question` label, or email the maintainer at `davjfies@gmail.com`.
+
+## Development setup
+
+```bash
+git clone https://github.com/dfieser/hea-bench
+cd hea-bench
+pip install -e ".[dev,data]"
+python -m pytest tests/ -q
+```
+
+The core package is dependency-free. The `dev` extra adds `pytest`,
+`pytest-cov`, and `ruff`. The `data` extra adds `pandas` for tabular
+work.
+
+## Tests
+
+Every numerical result reported in the documentation and in the
+paper is pinned in the test suite. When you change descriptor code,
+the consolidator, or the vendored data, run the suite and update the
+affected pinned values only after confirming the new number by an
+independent measurement. The repository convention is to measure
+first and assert second, never to write an expected value from
+memory.
+
+When adding a new descriptor, rule, or loader, add tests that cover
+at least one canonical reference case (the equiatomic Cantor alloy
+CoCrFeMnNi is the standard sanity check) plus the error paths.
+
+## Adding a dataset
+
+Per-source data lives under `data/raw/<source>/` with a README that
+records the citation, the license, the acquisition date, and a
+SHA-256 of the file. Datasets under permissive licenses (CC-BY, CC0,
+MIT, Apache, BSD) are mirrored directly. Datasets without a
+redistributable license are pointer-only: commit a `fetch.py` that
+downloads the file on request, and add the file pattern to
+`.gitignore`. See `data/raw/README.md` for the policy.
+
+## Adding elemental coverage
+
+To extend the elemental data table, add the element to the table in
+`src/hea_bench/descriptors/data/elemental.py` with a source comment
+for each property, then run the coverage analysis to confirm the
+benchmark coverage improved as expected.
+
+## Pull requests
+
+- Open PRs against the default branch.
+- Keep the test suite green. New functionality needs new tests.
+- Run `ruff` for linting before submitting.
+- Describe what changed and why in the PR description.
+
+## Code of conduct
+
+Participation in this project is governed by the
+[Code of Conduct](CODE_OF_CONDUCT.md).

hea_bench-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Fieser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to grant persons to whom the Software is furnished
+to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.