hea-bench 0.1.0__py3-none-any.whl

hea_bench/__init__.py

@@ -0,0 +1,37 @@
+"""hea-bench: an open benchmark suite for high-entropy alloy phase prediction.
+
+Top-level convenience imports for the most-used names; full surface
+documented in ``README.md``.
+
+Quick start::
+
+    from hea_bench import smix, delta, vec, mixing_enthalpy, omega
+    cantor = {"Co": 0.2, "Cr": 0.2, "Fe": 0.2, "Mn": 0.2, "Ni": 0.2}
+    print(smix(cantor), delta(cantor), vec(cantor),
+          mixing_enthalpy(cantor), omega(cantor))
+"""
+
+from .composition import Composition, normalize, parse_formula
+from .descriptors.entropy import smix
+from .descriptors.melting import melting_temperature
+from .descriptors.miedema import mixing_enthalpy
+from .descriptors.omega import omega
+from .descriptors.size import delta
+from .descriptors.vec import vec
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # core type + parsing
+    "Composition",
+    "parse_formula",
+    "normalize",
+    # descriptors
+    "smix",
+    "delta",
+    "vec",
+    "melting_temperature",
+    "mixing_enthalpy",
+    "omega",
+]

hea_bench/benchmark/__init__.py

@@ -0,0 +1,4 @@
+"""Dataset loaders, deduplication, and benchmark assembly.
+
+Phase 0: empty namespace. Populated in Phase 1.
+"""

hea_bench/benchmark/composition.py

@@ -0,0 +1,16 @@
+"""Re-export of composition primitives from the package root.
+
+`composition.py` was originally defined here; it moved to the package
+root so descriptor modules can consume it without depending on the
+benchmark subpackage. This shim preserves the historical import path
+for any external code that grew to depend on it.
+"""
+
+from ..composition import (
+    Composition,
+    from_element_columns,
+    normalize,
+    parse_formula,
+)
+
+__all__ = ["Composition", "from_element_columns", "normalize", "parse_formula"]

hea_bench/benchmark/consolidate.py

@@ -0,0 +1,296 @@
+"""Consolidate the three source datasets into one canonical benchmark.
+
+Walks each source loader, merges records on a *composition-only* join
+key (Borg's processing column is preserved as side-channel data but
+does **not** participate in the join), and produces:
+
+- ``data/consolidated/<version>/consolidated.csv``  — the benchmark
+- ``data/consolidated/<version>/manifest.json``     — provenance, dedup
+                                                       stats, SHA-256s
+
+Label conflict handling: when two or more sources contribute records for
+the same composition but disagree on the canonical phase class, the
+output row has ``canonical_phase`` blank and ``has_conflict=1``. The
+per-source labels are still recorded so users can resolve the conflict
+however they want.
+
+Run as a module to (re)build v0.1.0:
+
+    python -m hea_bench.benchmark.consolidate
+"""
+
+from __future__ import annotations
+
+import csv
+import datetime
+import hashlib
+import json
+import pathlib
+import sys
+from collections import defaultdict
+from collections.abc import Iterable
+from dataclasses import dataclass, field
+
+from .composition import Composition
+from .loaders import AlloyRecord, borg2020, pei2020, peivaste
+from .taxonomy import PhaseClass
+
+DEFAULT_VERSION = "0.1.0"
+
+# Repo-relative paths (repo root is 3 parents up from this file:
+# hea-bench/src/hea_bench/benchmark/consolidate.py → hea-bench/).
+_REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+_RAW_DIR = _REPO_ROOT / "data" / "raw"
+_CONSOLIDATED_DIR = _REPO_ROOT / "data" / "consolidated"
+
+
+def canonical_formula_key(composition: Composition, precision: int = 4) -> str:
+    """Stable string key for a normalized composition.
+
+    Elements sorted alphabetically; fractions formatted at fixed
+    precision. Two compositions differing only by float noise produce
+    the same key.
+
+    >>> canonical_formula_key({'Fe': 0.5, 'Co': 0.5})
+    'Co0.5000Fe0.5000'
+    >>> canonical_formula_key({'Co': 0.500000001, 'Fe': 0.499999999})
+    'Co0.5000Fe0.5000'
+    """
+    parts = []
+    for el in sorted(composition):
+        frac = round(composition[el], precision)
+        if frac > 0:
+            parts.append(f"{el}{frac:.{precision}f}")
+    return "".join(parts)
+
+
+@dataclass
+class ConsolidatedRow:
+    composition_key: str
+    composition: Composition
+    n_elements: int
+    sources: list[str]
+    canonical_phase: PhaseClass | None
+    has_conflict: bool
+    per_source_canonical: dict[str, PhaseClass]
+    per_source_raw_labels: dict[str, str]
+    borg_processing: str | None = None
+    borg_doi: str | None = None
+    source_row_ids: dict[str, str] = field(default_factory=dict)
+
+
+def consolidate(records: Iterable[AlloyRecord], precision: int = 4) -> list[ConsolidatedRow]:
+    """Merge records from any number of sources by composition-only key."""
+    by_key: dict[str, list[AlloyRecord]] = defaultdict(list)
+    for r in records:
+        by_key[canonical_formula_key(r.composition, precision)].append(r)
+
+    out: list[ConsolidatedRow] = []
+    for key, rs in by_key.items():
+        per_source_canonical: dict[str, PhaseClass] = {}
+        per_source_raw: dict[str, str] = {}
+        row_ids: dict[str, str] = {}
+        for r in rs:
+            # Within one source, a single (formula, processing) pair has
+            # already been deduped by the per-source loader. Multiple rs
+            # entries for the same source would only happen if two Borg
+            # processings of the same composition exist; keep the first.
+            per_source_canonical.setdefault(r.source, r.canonical_phase)
+            per_source_raw.setdefault(r.source, r.source_label)
+            row_ids.setdefault(r.source, r.source_row_id)
+
+        canonical_set = set(per_source_canonical.values())
+        has_conflict = len(canonical_set) > 1
+        canonical = next(iter(canonical_set)) if not has_conflict else None
+
+        borg_rec = next((r for r in rs if r.source == "borg2020"), None)
+
+        out.append(
+            ConsolidatedRow(
+                composition_key=key,
+                composition=rs[0].composition,
+                n_elements=sum(1 for v in rs[0].composition.values() if v > 0),
+                sources=sorted(per_source_canonical),
+                canonical_phase=canonical,
+                has_conflict=has_conflict,
+                per_source_canonical=per_source_canonical,
+                per_source_raw_labels=per_source_raw,
+                borg_processing=borg_rec.processing if borg_rec else None,
+                borg_doi=borg_rec.source_doi if borg_rec else None,
+                source_row_ids=row_ids,
+            )
+        )
+    return out
+
+
+# ---- Output writers -------------------------------------------------------
+
+_CSV_COLUMNS = [
+    "composition_key",
+    "n_elements",
+    "sources",
+    "canonical_phase",
+    "has_conflict",
+    "borg_label",
+    "pei_label",
+    "peivaste_label",
+    "borg_raw_label",
+    "pei_raw_label",
+    "peivaste_raw_label",
+    "borg_processing",
+    "borg_doi",
+    "source_row_ids",
+]
+
+
+def _row_to_csv(row: ConsolidatedRow) -> list[str]:
+    def lbl(src: str) -> str:
+        v = row.per_source_canonical.get(src)
+        return v.value if v else ""
+
+    return [
+        row.composition_key,
+        str(row.n_elements),
+        ";".join(row.sources),
+        row.canonical_phase.value if row.canonical_phase else "",
+        "1" if row.has_conflict else "0",
+        lbl("borg2020"),
+        lbl("pei2020"),
+        lbl("peivaste"),
+        row.per_source_raw_labels.get("borg2020", ""),
+        row.per_source_raw_labels.get("pei2020", ""),
+        row.per_source_raw_labels.get("peivaste", ""),
+        row.borg_processing or "",
+        row.borg_doi or "",
+        ";".join(f"{s}:{rid}" for s, rid in sorted(row.source_row_ids.items())),
+    ]
+
+
+def write_consolidated_csv(rows: Iterable[ConsolidatedRow], path: pathlib.Path) -> int:
+    """Write rows in alphabetical composition_key order. Returns row count."""
+    rows = sorted(rows, key=lambda r: r.composition_key)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("w", newline="", encoding="utf-8") as f:
+        w = csv.writer(f)
+        w.writerow(_CSV_COLUMNS)
+        for r in rows:
+            w.writerow(_row_to_csv(r))
+    return len(rows)
+
+
+def _sha256(p: pathlib.Path) -> str:
+    return hashlib.sha256(p.read_bytes()).hexdigest() if p.exists() else ""
+
+
+def build_manifest(
+    rows: list[ConsolidatedRow],
+    source_counts: dict[str, int],
+    source_paths: dict[str, pathlib.Path],
+    version: str,
+) -> dict:
+    canonical_dist = {p.value: 0 for p in PhaseClass}
+    canonical_dist["conflict"] = 0
+    for r in rows:
+        if r.has_conflict:
+            canonical_dist["conflict"] += 1
+        elif r.canonical_phase:
+            canonical_dist[r.canonical_phase.value] += 1
+
+    overlap = {"single_source": 0, "two_sources": 0, "three_sources": 0}
+    for r in rows:
+        n = len(r.sources)
+        if n == 1:
+            overlap["single_source"] += 1
+        elif n == 2:
+            overlap["two_sources"] += 1
+        elif n >= 3:
+            overlap["three_sources"] += 1
+
+    src_meta_table = {
+        "borg2020":  {"license": "CC-BY-4.0",     "doi": "10.1038/s41597-020-00768-9"},
+        "pei2020":   {"license": "CC-BY-4.0",     "doi": "10.1038/s41524-020-0308-7"},
+        "peivaste":  {"license": "none-declared", "url": "https://github.com/Iman-Peivaste/ML_HEAs_Phase_Dataset"},
+    }
+
+    sources_section = []
+    for name in ("borg2020", "pei2020", "peivaste"):
+        meta = src_meta_table[name]
+        sources_section.append(
+            {
+                "name": name,
+                **meta,
+                "rows_yielded": source_counts.get(name, 0),
+                "sha256": _sha256(source_paths.get(name, pathlib.Path())),
+            }
+        )
+
+    return {
+        "version": version,
+        "created": datetime.datetime.now(datetime.timezone.utc).isoformat(timespec="seconds"),
+        "schema": {
+            "composition_key": (
+                "Stable hash of normalized composition: alphabetically sorted "
+                "elements at 4-decimal mole-fraction precision."
+            ),
+            "canonical_phase": (
+                "One of BCC, FCC, HCP, multi-phase. Empty when sources disagree."
+            ),
+            "has_conflict": (
+                "1 if any pair of contributing sources gave different canonical labels."
+            ),
+            "borg_processing": "Preserved side-channel from Borg only. Not part of join key.",
+        },
+        "sources": sources_section,
+        "totals": {
+            "unique_compositions": len(rows),
+            "by_source_overlap": overlap,
+            "canonical_distribution": canonical_dist,
+        },
+        "consolidation_rules": {
+            "join_key": "composition_only, 4-decimal mole-fraction precision",
+            "label_policy": "agreement → canonical; disagreement → has_conflict=1, canonical_phase blank",
+            "borg_processing": "Preserved as side-channel; not part of join key",
+            "per_source_dedup": "Each loader deduplicates internally before consolidation",
+        },
+    }
+
+
+def build(version: str = DEFAULT_VERSION, out_dir: pathlib.Path | None = None) -> dict:
+    """Run all three loaders, consolidate, write the v<version> release.
+
+    Returns the manifest dict (also written to disk).
+    """
+    out_dir = out_dir or (_CONSOLIDATED_DIR / f"v{version}")
+    out_dir.mkdir(parents=True, exist_ok=True)
+
+    source_paths = {
+        "borg2020": _RAW_DIR / "borg2020" / "MPEA_dataset.csv",
+        "pei2020":  _RAW_DIR / "pei2020"  / "pei2020_alloys_phases.csv",
+        "peivaste": _RAW_DIR / "peivaste" / "dataset11252_79.csv",
+    }
+    borg_rows     = list(borg2020.load(source_paths["borg2020"]))
+    pei_rows      = list(pei2020.load(source_paths["pei2020"]))
+    peivaste_rows = list(peivaste.load(source_paths["peivaste"]))
+    source_counts = {"borg2020": len(borg_rows), "pei2020": len(pei_rows), "peivaste": len(peivaste_rows)}
+
+    consolidated = consolidate([*borg_rows, *pei_rows, *peivaste_rows])
+    write_consolidated_csv(consolidated, out_dir / "consolidated.csv")
+
+    manifest = build_manifest(consolidated, source_counts, source_paths, version)
+    (out_dir / "manifest.json").write_text(json.dumps(manifest, indent=2))
+    return manifest
+
+
+def main() -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    m = build()
+    print(f"=== v{m['version']} built {m['created']} ===")
+    print(f"unique compositions: {m['totals']['unique_compositions']}")
+    print(f"by_source_overlap:   {m['totals']['by_source_overlap']}")
+    print(f"canonical:           {m['totals']['canonical_distribution']}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hea_bench/benchmark/coverage.py

@@ -0,0 +1,169 @@
+"""Coverage analysis of the consolidated benchmark against the
+descriptor data tables.
+
+For each composition in ``data/consolidated/v<version>/consolidated.csv``,
+checks whether all of its elements are present in:
+
+(a) :data:`hea_bench.descriptors.data.elemental.ELEMENTAL_DATA`
+    — needed for δ, VEC, T_m (the "basic" descriptor set)
+(b) the Miedema pair table at
+    :mod:`hea_bench.descriptors.data.pair_enthalpies`
+    — needed for ΔH_mix and Ω
+
+Outputs:
+
+- per-composition counts (in_basic_only / in_miedema_only / in_both / no_coverage)
+- ranked list of elements missing from each table, by alloy frequency
+- the "next-best-add" candidates — elements present in the pair table
+  but missing from ELEMENTAL_DATA, sorted by how many alloys they'd
+  unlock if added
+
+Run as a module to score the released v0.1.0:
+
+    python -m hea_bench.benchmark.coverage
+"""
+
+from __future__ import annotations
+
+import csv
+import json
+import pathlib
+import sys
+from collections import Counter
+from collections.abc import Iterable
+
+from ..composition import parse_formula
+from ..descriptors.data.elemental import covered_elements as _elemental_covered
+from ..descriptors.data.pair_enthalpies import covered_elements as _pair_covered
+
+_REPO_ROOT = pathlib.Path(__file__).resolve().parents[3]
+_DEFAULT_CSV = _REPO_ROOT / "data" / "consolidated" / "v0.1.0" / "consolidated.csv"
+
+
+def analyze(csv_path: pathlib.Path = _DEFAULT_CSV) -> dict:
+    """Compute coverage of the consolidated benchmark.
+
+    Returns a dict with:
+
+    - ``total`` : total compositions in the CSV
+    - ``in_basic``, ``in_miedema``, ``in_both``, ``in_neither`` : counts
+    - ``missing_from_basic`` : ``Counter`` of element → alloy frequency
+      for elements that appear in compositions but are absent from
+      ELEMENTAL_DATA
+    - ``missing_from_miedema`` : same for the pair table
+    - ``next_best_adds`` : list of (element, n_alloys_unlocked,
+      already_in_pair_table) tuples, sorted descending — these are
+      the highest-leverage elements to add to ELEMENTAL_DATA next
+    """
+    basic = _elemental_covered()
+    miedema = _pair_covered()
+
+    total = 0
+    in_basic = 0
+    in_miedema = 0
+    in_both = 0
+    in_neither = 0
+    missing_from_basic: Counter[str] = Counter()
+    missing_from_miedema: Counter[str] = Counter()
+
+    # For "next-best-add": map each currently-uncovered element to the
+    # number of compositions whose ONLY missing element(s) are inside
+    # the set that would be unlocked by adding it. Simpler proxy:
+    # count how many compositions contain each uncovered element.
+    per_element_alloys: Counter[str] = Counter()
+
+    with csv_path.open(newline="", encoding="utf-8") as f:
+        for row in csv.DictReader(f):
+            total += 1
+            try:
+                comp = parse_formula(row["composition_key"])
+            except (KeyError, ValueError):
+                continue
+            elems = set(comp)
+            miss_b = elems - basic
+            miss_m = elems - miedema
+
+            if not miss_b:
+                in_basic += 1
+            if not miss_m:
+                in_miedema += 1
+            if not miss_b and not miss_m:
+                in_both += 1
+            if miss_b and miss_m:
+                in_neither += 1
+
+            for e in miss_b:
+                missing_from_basic[e] += 1
+            for e in miss_m:
+                missing_from_miedema[e] += 1
+            for e in elems - basic:
+                per_element_alloys[e] += 1
+
+    # Next-best-add ranking: elements outside ELEMENTAL_DATA, by alloy
+    # count, with a flag indicating whether they're already in the
+    # pair table (low-effort wins) vs. need full sourcing.
+    next_best: list[tuple[str, int, bool]] = []
+    for el, cnt in per_element_alloys.most_common():
+        next_best.append((el, cnt, el in miedema))
+
+    return {
+        "csv_path": str(csv_path),
+        "total": total,
+        "in_basic": in_basic,
+        "in_miedema": in_miedema,
+        "in_both": in_both,
+        "in_neither": in_neither,
+        "missing_from_basic": dict(missing_from_basic),
+        "missing_from_miedema": dict(missing_from_miedema),
+        "next_best_adds": next_best,
+    }
+
+
+def format_report(report: dict) -> str:
+    """Render `analyze()` output as a human-readable text report."""
+    out: list[str] = []
+    total = report["total"]
+
+    def pct(n: int) -> str:
+        return f"{n / total * 100:.1f}%" if total else "0.0%"
+
+    out.append(f"=== Coverage report: {report['csv_path']} ===")
+    out.append("")
+    out.append(f"total compositions:       {total:>5}")
+    out.append("")
+    out.append("Coverage by descriptor data table:")
+    out.append(f"  ELEMENTAL_DATA (δ/VEC/T_m):  {report['in_basic']:>5} / {total}  ({pct(report['in_basic'])})")
+    out.append(f"  Miedema pair table (ΔH/Ω):   {report['in_miedema']:>5} / {total}  ({pct(report['in_miedema'])})")
+    out.append(f"  both (all 6 descriptors):    {report['in_both']:>5} / {total}  ({pct(report['in_both'])})")
+    out.append(f"  neither (cannot score):      {report['in_neither']:>5} / {total}  ({pct(report['in_neither'])})")
+    out.append("")
+    out.append("Top 15 elements missing from ELEMENTAL_DATA (basic descriptors):")
+    items = sorted(report["missing_from_basic"].items(), key=lambda kv: -kv[1])[:15]
+    for el, cnt in items:
+        out.append(f"  {el:>3}  appears in {cnt:>5} alloys  ({pct(cnt)})")
+    out.append("")
+    out.append("Next-best-add ranking (elements outside ELEMENTAL_DATA, by alloy count):")
+    out.append("  symbol  alloys-unlocked  already-in-pair-table")
+    for el, cnt, in_pair in report["next_best_adds"][:15]:
+        flag = "YES (low-effort win)" if in_pair else "no  (needs full sourcing)"
+        out.append(f"  {el:>3}     {cnt:>5}            {flag}")
+    return "\n".join(out)
+
+
+def main(argv: Iterable[str] | None = None) -> int:
+    if hasattr(sys.stdout, "reconfigure"):
+        sys.stdout.reconfigure(encoding="utf-8", errors="replace")
+    report = analyze()
+    print(format_report(report))
+    # Persist machine-readable form alongside the v0.1.0 release.
+    out_json = pathlib.Path(report["csv_path"]).parent / "coverage_report.json"
+    out_json.write_text(json.dumps(
+        {k: (dict(v) if isinstance(v, Counter) else v) for k, v in report.items()},
+        indent=2,
+    ))
+    print(f"\nwrote {out_json}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

hea_bench/benchmark/loaders/__init__.py

@@ -0,0 +1,54 @@
+"""Per-source dataset loaders.
+
+Each loader returns an iterable of `AlloyRecord` rows in a canonical
+schema, hiding the upstream column conventions, formula syntax, and
+phase-label vocabulary from the consolidator.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ..composition import Composition
+from ..taxonomy import PhaseClass
+
+
+@dataclass(frozen=True)
+class AlloyRecord:
+    """One row in the consolidated benchmark schema.
+
+    Attributes
+    ----------
+    source
+        Identifier of the upstream source (e.g., ``"borg2020"``,
+        ``"pei2020"``, ``"peivaste"``).
+    source_row_id
+        Stable identifier from the upstream row — index, Reference ID,
+        whatever the source uses to point back to its own records.
+    formula_raw
+        The composition string as it appeared in the upstream CSV,
+        verbatim. Useful for traceability.
+    composition
+        Normalized mole-fraction dict (sums to 1.0).
+    canonical_phase
+        One of the `PhaseClass` values: ``BCC``, ``FCC``, ``HCP``, or
+        ``multi-phase``.
+    source_label
+        The upstream phase label string, preserved verbatim for users
+        who want finer granularity than the canonical 4-class.
+    processing
+        Processing route, if the upstream source records it (Borg only).
+        ``None`` for sources that don't.
+    source_doi
+        DOI of the primary-literature paper this alloy was reported in,
+        if the upstream source records it (Borg only).
+    """
+
+    source: str
+    source_row_id: str
+    formula_raw: str
+    composition: Composition
+    canonical_phase: PhaseClass
+    source_label: str
+    processing: str | None = None
+    source_doi: str | None = None

hea_bench/benchmark/loaders/borg2020.py

@@ -0,0 +1,85 @@
+"""Loader for the Borg et al. 2020 MPEA dataset.
+
+Source: ``data/raw/borg2020/MPEA_dataset.csv`` (CC-BY-4.0, mirrored
+verbatim from figshare 10.6084/m9.figshare.12642953 v9).
+
+Schema, dedup behaviour, and label-normalization decisions are
+documented inline below; see ``data/raw/borg2020/README.md`` for the
+full source-level context.
+"""
+
+from __future__ import annotations
+
+import csv
+import pathlib
+from collections.abc import Iterator
+
+from ..composition import parse_formula
+from ..taxonomy import BORG_SIMPLE_MAP
+from . import AlloyRecord
+
+SOURCE_NAME = "borg2020"
+
+# Column names — Borg's upstream headers, verbatim (including raw LaTeX).
+_COL_REF_ID         = "IDENTIFIER: Reference ID"
+_COL_FORMULA        = "FORMULA"
+_COL_MICROSTRUCTURE = "PROPERTY: Microstructure"
+_COL_PROCESSING     = "PROPERTY: Processing method"
+_COL_SIMPLE_PHASE   = "PROPERTY: BCC/FCC/other"
+_COL_DOI            = "REFERENCE: doi"
+
+
+def load(csv_path: pathlib.Path) -> Iterator[AlloyRecord]:
+    """Yield one `AlloyRecord` per unique ``(formula, processing)`` alloy.
+
+    Borg has 1,545 measurement rows for 740 unique ``(formula, processing)``
+    alloys — the duplicates come from multiple mechanical tests at
+    different temperatures/test types on the same alloy. Phase is a
+    property of the alloy and its processing, not the test, so we
+    deduplicate here.
+
+    When duplicate ``(formula, processing)`` rows disagree on the phase
+    label, the first row encountered wins. (Borg's data is internally
+    consistent on this point — duplicate rows from the same source paper
+    always carry the same phase label — but the loader is defensive.)
+
+    Rows missing a parseable formula or a simplified phase label are
+    skipped silently. Caller can compare yielded count to file row count
+    if a count of skipped rows is needed.
+    """
+    seen: set[tuple[str, str]] = set()
+
+    with csv_path.open(newline="", encoding="utf-8-sig") as f:
+        for raw in csv.DictReader(f):
+            formula = (raw.get(_COL_FORMULA) or "").strip()
+            processing = (raw.get(_COL_PROCESSING) or "").strip()
+            source_label = (raw.get(_COL_SIMPLE_PHASE) or "").strip()
+            full_microstructure = (raw.get(_COL_MICROSTRUCTURE) or "").strip()
+
+            if not formula or not source_label:
+                continue
+
+            key = (formula, processing)
+            if key in seen:
+                continue
+
+            try:
+                composition = parse_formula(formula)
+            except ValueError:
+                continue
+
+            canonical = BORG_SIMPLE_MAP.get(source_label)
+            if canonical is None:
+                continue
+
+            seen.add(key)
+            yield AlloyRecord(
+                source=SOURCE_NAME,
+                source_row_id=(raw.get(_COL_REF_ID) or "").strip(),
+                formula_raw=formula,
+                composition=composition,
+                canonical_phase=canonical,
+                source_label=full_microstructure or source_label,
+                processing=processing or None,
+                source_doi=(raw.get(_COL_DOI) or "").strip() or None,
+            )