Add materials discovery evaluation metrics

docs/source/user_guide/benchmarks/bulk_crystal.rst

@@ -2,6 +2,31 @@
 Bulk Crystals
 =============
 
+Materials discovery evaluation
+==============================
+
+The materials-discovery evaluator computes Matbench Discovery classification and
+regression metrics from local tables. The reference table is indexed by
+``material_id`` and contains DFT hull distance, DFT formation energy, and a
+unique-prototype flag. The prediction table contains ``e_form_per_atom``.
+
+Results are reported for the full test set, unique prototypes, and the 10,000
+unique prototypes with the lowest predicted hull distances. They include F1,
+discovery acceleration factor (DAF), precision, recall, accuracy, class rates and
+counts, MAE, RMSE, R², and missing-prediction counts. Predictions with
+formation-energy errors above 5 eV/atom are masked before rounding to three decimal
+places. Leaderboard evaluation uses the fraction of unique prototypes with an
+unrounded hull distance at or below 0 eV/atom as prevalence, preventing rounding
+from changing DAF. Pass this value with ``canonical=True`` and
+``uniq_proto_prevalence=...``. Synthetic mode derives prevalence from the rounded
+reference values. ``calc_discovery_metrics`` and ``discovery_subset_indices`` apply
+the same masking and rounding as ``evaluate_discovery``.
+
+See ``ml_peg.analysis.bulk_crystal.materials_discovery``. WBM reference and
+prediction artifacts are not included. JSON results include schema and source
+framework versions.
+
+
 Lattice constants
 =================
 

ml_peg/analysis/bulk_crystal/materials_discovery/__init__.py

@@ -0,0 +1,69 @@
+"""Materials-discovery schemas, metrics, and evaluation."""
+
+from __future__ import annotations
+
+from ml_peg.analysis.bulk_crystal.materials_discovery.evaluation import (
+    EVALUATION_DECIMALS,
+    MAX_E_FORM_ERROR_THRESHOLD,
+    MISSING_PREDICTIONS_KEY,
+    RESULT_SCHEMA_VERSION,
+    DiscoveryResults,
+    DiscoverySubsetResults,
+    SourceMetadata,
+    calc_discovery_metrics,
+    discovery_subset_indices,
+    evaluate_discovery,
+    evaluate_discovery_paths,
+    prepare_discovery_inputs,
+    write_discovery_metrics_json,
+)
+from ml_peg.analysis.bulk_crystal.materials_discovery.metrics import (
+    MOST_STABLE_COUNT,
+    STABILITY_THRESHOLD,
+    MetricValue,
+    align_predictions,
+    classify_stable,
+    stable_metrics,
+)
+from ml_peg.analysis.bulk_crystal.materials_discovery.schema import (
+    E_ABOVE_HULL,
+    MATERIAL_ID,
+    PREDICTED_FORMATION_ENERGY,
+    REFERENCE_COLUMNS,
+    REFERENCE_FORMATION_ENERGY,
+    UNIQUE_PROTOTYPE,
+    DiscoverySubset,
+    validate_prediction_frame,
+    validate_reference_frame,
+)
+
+__all__ = [
+    "EVALUATION_DECIMALS",
+    "MAX_E_FORM_ERROR_THRESHOLD",
+    "MISSING_PREDICTIONS_KEY",
+    "MOST_STABLE_COUNT",
+    "RESULT_SCHEMA_VERSION",
+    "STABILITY_THRESHOLD",
+    "DiscoveryResults",
+    "DiscoverySubset",
+    "DiscoverySubsetResults",
+    "MetricValue",
+    "SourceMetadata",
+    "align_predictions",
+    "calc_discovery_metrics",
+    "classify_stable",
+    "discovery_subset_indices",
+    "evaluate_discovery",
+    "evaluate_discovery_paths",
+    "prepare_discovery_inputs",
+    "stable_metrics",
+    "validate_prediction_frame",
+    "validate_reference_frame",
+    "write_discovery_metrics_json",
+    "E_ABOVE_HULL",
+    "MATERIAL_ID",
+    "PREDICTED_FORMATION_ENERGY",
+    "REFERENCE_COLUMNS",
+    "REFERENCE_FORMATION_ENERGY",
+    "UNIQUE_PROTOTYPE",
+]