change TL;DR to MP non-endorsement disclaimer

add module doc strings
fix wbm_computed_structure_entries desc on /contribute page

Author: janosh

.pre-commit-config.yaml

@@ -8,7 +8,7 @@ default_install_hook_types: [pre-commit, commit-msg]
 
 repos:
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.3.7
+    rev: v0.4.2
     hooks:
       - id: ruff
         args: [--fix]
@@ -31,7 +31,7 @@ repos:
       - id: trailing-whitespace
 
   - repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.9.0
+    rev: v1.10.0
     hooks:
       - id: mypy
         additional_dependencies: [types-pyyaml, types-requests]
@@ -57,7 +57,7 @@ repos:
         exclude: ^(site/src/figs/.+\.svelte|data/wbm/20.+\..+|site/src/(routes|figs).+\.(yaml|json)|changelog.md)$
 
   - repo: https://github.com/pre-commit/mirrors-eslint
-    rev: v9.0.0
+    rev: v9.1.1
     hooks:
       - id: eslint
         types: [file]
@@ -79,7 +79,7 @@ repos:
       - id: check-github-actions
 
   - repo: https://github.com/RobertCraigie/pyright-python
-    rev: v1.1.358
+    rev: v1.1.360
     hooks:
       - id: pyright
         args: [--level, error]

data/mp/get_mp_energies.py

@@ -1,3 +1,9 @@
+"""Download all MP formation and above hull energies on 2023-01-10.
+
+Related EDA of MP formation energies:
+https://github.com/janosh/pymatviz/blob/-/examples/mp_bimodal_e_form.ipynb
+"""
+
 # %%
 import os
 
@@ -12,13 +18,6 @@
 from matbench_discovery.data import DATA_FILES
 from matbench_discovery.enums import Key
 
-"""
-Download all MP formation and above hull energies on 2023-01-10.
-
-Related EDA of MP formation energies:
-https://github.com/janosh/pymatviz/blob/-/examples/mp_bimodal_e_form.ipynb
-"""
-
 __author__ = "Janosh Riebesell"
 __date__ = "2023-01-10"
 

data/wbm/compare_cse_vs_ce_mp_2020_corrections.py

@@ -1,3 +1,8 @@
+"""NOTE MaterialsProject2020Compatibility takes structural information into account when
+correcting energies (for oxides and sulfides only). Always use
+ComputedStructureEntry, not ComputedEntry when applying energy corrections.
+"""
+
 # %%
 import gzip
 import json
@@ -16,13 +21,6 @@
 from matbench_discovery.enums import Key
 from matbench_discovery.plots import plt
 
-"""
-NOTE MaterialsProject2020Compatibility takes structural information into account when
-correcting energies (for certain oxides and sulfides). Always use
-ComputedStructureEntry, not ComputedEntry when applying corrections.
-"""
-
-
 df_cse = pd.read_json(DATA_FILES.wbm_computed_structure_entries).set_index(Key.mat_id)
 
 cses = [ComputedStructureEntry.from_dict(dct) for dct in tqdm(df_cse[Key.cse])]

data/wbm/compile_wbm_test_set.py

@@ -1,3 +1,8 @@
+"""Download, process and clean the DFT dataset published in Wang et al. 2021.
+
+https://nature.com/articles/s41524-020-00481-6
+"""
+
 # %%
 import gzip
 import os
@@ -33,11 +38,6 @@
     )
     raise
 
-"""
-Dataset generated with DFT and published in Jan 2021 as
-"Predicting stable crystalline compounds using chemical similarity"
-https://nature.com/articles/s41524-020-00481-6
-"""
 
 # %% links to google drive files received via email from 1st author Hai-Chen Wang
 # on 2021-06-15 containing initial and relaxed structures

data/wbm/eda_wbm.py

@@ -1,3 +1,7 @@
+"""WBM exploratory data analysis (EDA).
+Start with comparing MP and WBM elemental prevalence.
+"""
+
 # %%
 import os
 
@@ -26,11 +30,6 @@
 __author__ = "Janosh Riebesell"
 __date__ = "2023-03-30"
 
-"""
-WBM exploratory data analysis (EDA).
-Start with comparing MP and WBM elemental prevalence.
-"""
-
 module_dir = os.path.dirname(__file__)
 data_page = f"{ROOT}/site/src/routes/data"
 

matbench_discovery/data.py

@@ -1,3 +1,8 @@
+"""Download, cache and hydrate data files from the Matbench Discovery Figshare article.
+
+https://figshare.com/articles/dataset/22715158
+"""
+
 import gzip
 import json
 import os

matbench_discovery/energy.py

@@ -1,3 +1,7 @@
+"""Functions to compute formation and elemental reference energies from
+pymatgen EntryLikes.
+"""
+
 import itertools
 from collections.abc import Sequence
 

matbench_discovery/enums.py

@@ -1,3 +1,5 @@
+"""Enums used as keys/accessors for dicts and dataframes across Matbench Discovery."""
+
 from enum import StrEnum, unique
 from typing import Self
 

matbench_discovery/models.py

@@ -1,3 +1,5 @@
+"""Initializes global variable MODEL_METADATA."""
+
 from glob import glob
 from typing import Any
 
@@ -20,11 +22,7 @@
             continue
         # make sure all required keys are non-empty
         with open(md_file) as yml_file:
-            models = yaml.full_load(yml_file)
+            model_data = yaml.full_load(yml_file)
 
-        # some metadata files contain a single model, some have multiple
-        if not isinstance(models, list):
-            models = [models]
-        for model in models:
-            model["model_dir"] = model_dir
-            MODEL_METADATA[model["model_name"]] = model
+        model_data["model_dir"] = model_dir
+        MODEL_METADATA[model_data["model_name"]] = model_data

matbench_discovery/preds.py

@@ -1,3 +1,5 @@
+"""Centralize data-loading and computing metrics for plotting scripts."""
+
 from collections.abc import Sequence
 from typing import Any, Literal
 
@@ -10,8 +12,6 @@
 from matbench_discovery.metrics import stable_metrics
 from matbench_discovery.plots import plotly_colors, plotly_line_styles, plotly_markers
 
-"""Centralize data-loading and computing metrics for plotting scripts"""
-
 __author__ = "Janosh Riebesell"
 __date__ = "2023-02-04"
 

matbench_discovery/slurm.py

@@ -1,3 +1,5 @@
+"""Slurm job submission helper function."""
+
 import os
 import subprocess
 import sys

matbench_discovery/structure.py

@@ -1,3 +1,8 @@
+"""Perturb atomic coordinates of a pymatgen structure.
+
+Used for CGCNN+P training set augmentation.
+"""
+
 import numpy as np
 from pymatgen.core import Structure
 

readme.md

@@ -13,7 +13,7 @@
 
 </h4>
 
-> TL;DR: We benchmark ML models on crystal stability prediction from unrelaxed structures finding universal interatomic potentials (UIP) like [MACE](https://github.com/ACEsuit/mace), [CHGNet](https://github.com/CederGroupHub/chgnet) and [M3GNet](https://github.com/materialsvirtuallab/m3gnet) to be highly accurate, robust across chemistries and ready for production use in high-throughput materials discovery.
+> Disclaimer: We evaluate how accurately ML models predict solid-state thermodynamic stability. Although this is an important aspect of high-throughput materials discovery, the ranking cannot give a complete picture of a model's general applicability to materials. A high ranking does not constitute endorsement by the Materials Project.
 
 Matbench Discovery is an [interactive leaderboard](https://janosh.github.io/matbench-discovery/models) and associated [PyPI package](https://pypi.org/project/matbench-discovery) which together make it easy to rank ML energy models on a task designed to simulate a high-throughput discovery campaign for new stable inorganic crystals.
 

site/src/lib/model-schema.d.ts

@@ -1,4 +1,3 @@
-/* eslint-disable */
 /**
  * This file was automatically generated by json-schema-to-typescript.
  * DO NOT MODIFY IT BY HAND. Instead, modify the source JSONSchema file,

site/src/routes/contribute/+page.md

@@ -6,20 +6,19 @@
   const ppd_doc_url = `https://github.com/materialsproject/pymatgen/blob/v2023.5.10/pymatgen/analysis/phase_diagram.py#L1480-L1814`
   const ppd_link = `<a href=${ppd_doc_url}>PatchedPhaseDiagram</a>`
   const cse_doc_url = `https://github.com/materialsproject/pymatgen/blob/v2023.5.10/pymatgen/entries/computed_entries.py#L579-L722`
-  const cse_link = `<a href=${cse_doc_url}>ComputedStructureEntry</a>`
 
   const mp_trj_link = `<a href="https://figshare.com/articles/dataset/23713842">MPtrj</a>`
   const descriptions = {
     alignn_checkpoint: `ALIGNN model trained on <code>mp_computed_structure_entries</code>`,
     mp_computed_structure_entries:
-      `JSON-Serialized MP ${cse_link} objects containing relaxed structures and DFT final energies`,
+      `JSON-Serialized MP <a href=${cse_doc_url}>ComputedStructureEntries</a> containing DFT relaxed structures and corresponding final energies`,
     mp_elemental_ref_entries: `Minimum energy ComputedEntry for each element in MP`,
     mp_energies: `Materials Project formation energies and energies above convex hull`,
     mp_patched_phase_diagram:
       `${ppd_link} constructed from all MP ComputedStructureEntries`,
-    wbm_computed_structure_entries: `Materials Project computed structure entries`,
+    wbm_computed_structure_entries: `WBM <a href=${cse_doc_url}>ComputedStructureEntries</a> containing DFT relaxed structures and corresponding final energies`,
     wbm_initial_structures: `Unrelaxed WBM structures`,
-    wbm_cses_plus_init_structs: `Both unrelaxed and DFT-relaxed WBM structures, the latter stored with their final VASP energies as ${cse_link}`,
+    wbm_cses_plus_init_structs: `Both unrelaxed and DFT-relaxed WBM structures, the latter stored with their final VASP energies as <a href=${cse_doc_url}>ComputedStructureEntry</a>`,
     wbm_summary:
       `Computed material properties only, no structures. Available properties are VASP energy, formation energy, energy above the convex hull, volume, band gap, number of sites per unit cell, and more.`,
     mp_trj_extxyz_by_yuan: `${mp_trj_link} converted to <code>ase</code>-compatible extended XYZ format and compressed (11.3 to 1.6 GB) by Yuan Chiang`,