How msehabibur/wbg_defect_screening works
1. Project type and scope
This repository is not an application server or library; it is a research reproducibility repo for a materials-science paper. The code in-tree is almost entirely figure-reconstruction and analysis glue, while the heavy outputs live in GitHub Releases as large data artifacts.
2. Primary architectural boundary: code vs. data
The repo is split into:
- small, versioned Python scripts in figure_scripts/
- large immutable data products downloaded from Releases:
- defect_records.parquet
- wbg_campaign_final.json
- figure_data.zip
The scripts do not appear to generate the full dataset from scratch; they consume precomputed release artifacts.
3. Core scientific pipeline
The underlying workflow is a defect-screening campaign over wide-bandgap semiconductors:
- 364 candidate hosts
- roughly 220 intrinsic defects per host
- 2 initial geometries per defect (symmetric and rattled)
- 3 foundation ML force fields: CHGNet, M3GNet, MACE
This yields the main data product: a large table of defect energetics and relaxed structures.
4. Main data model
defect_records.parquet is the most important architectural object. It is a row-per-defect-per-start table that stores:
- host metadata (host_id, mp_id, formula, polymorph, family)
- defect identity and class
- per-model formation energies
- consensus energy across the three MLFFs
- best-of-two-start selection
- inline structural payloads as CIF text for unrelaxed and relaxed cells
This file is effectively the canonical normalized dataset for downstream analysis.
5. Campaign-level aggregation
wbg_campaign_final.json is a higher-level summary object containing:
- global metadata
- the 364-host tolerance ranking
- nested per-host records
It acts as the campaign summary layer above the defect table, likely used for ranking, reporting, and figure generation.
6. Figure-generation subsystem
Everything under figure_scripts/ is organized around reproducing the paper’s figures from the release data:
- make_fig2.py through make_fig6.py for main-text figures
- make_figS2_ionicity.py and make_figS3_finitesize.py for supplementary figures
These scripts are the presentation layer: they read extracted figure inputs and produce the paper visuals.
7. Specialized analysis helpers
A few scripts support figure-specific derivations rather than general plotting:
- compute_binding.py computes chemical-potential-free binding energies for Fig. 4
- sensitivity.py performs finite-size / constant-volume sensitivity calculations
- family_reclass.py appears to reclassify material families for analysis consistency
- q_gan.py is another analysis helper, likely related to a defect/host labeling or ranking workflow
These are analysis transforms sitting between raw data and figures.
8. Data flow across the repo
The practical flow is:
- released campaign outputs are downloaded
- figure-specific JSON inputs are extracted from figure_data.zip
- figure scripts consume those inputs and generate plots
- the large parquet table is used for direct querying, ranking, and tabular validation
The repo does not show a build system or long pipeline orchestration; instead it relies on precomputed artifacts plus lightweight reproducible analysis scripts.
9. Model-consensus boundary
A key conceptual boundary in the architecture is the three-model consensus:
- each defect is evaluated independently by CHGNet, M3GNet, and MACE
- the final reported defect energetics are consensus values
- the “best-of-two-starts” rule reduces sensitivity to initial geometry
This consensus layer is central to the scientific claim and is reflected in the stored columns and ranking outputs.
10. Physics/chemistry boundary conditions
The dataset and analyses are explicitly scoped to:
- constant-volume relaxations
- charge-neutral formation energies
- PBE-anchored reference scheme
- stability-polygon vertex minimization over chemical potentials
These constraints define the domain boundary for all downstream figures and rankings.
11. External dependencies that matter architecturally
The repo depends on materials-science tooling rather than general web or ML stack components:
- chgnet, matgl, mace_torch for force-field inference
- pymatgen, doped, ase for materials structure handling and defect construction
- pandas, pyarrow for tabular/parquet analytics
This indicates an analysis pipeline built around materials objects and parquet/JSON data interchange.
12. What an architecture diagram should emphasize
The diagram should show:
- Release artifacts as the source of truth
- Figure scripts as the only in-repo executable layer
- Defect table and campaign summary JSON as the two main data hubs
- MLFF consensus screening as the scientific computation layer
- Figure outputs as the end product
In short: this is a data-centric reproducibility repository for a precomputed screening campaign, not a computational pipeline that regenerates the entire dataset from source.
Main entry points: make_fig3.py Fig 3 · make_fig4.py Fig 4 · make_figS3_finitesize.py Fig S3 · make_fig2.py Fig 2
Components 19
Release artifacts
Large immutable data products downloaded from GitHub Releases.
- Figure inputs · Extracted figure-specific inputs used by the plotting scripts.
- Paper figures · Rendered main-text and supplementary figures for the paper.
Core data model
Canonical campaign tables and summary objects used by analysis scripts.
- Defect table · Canonical row-per-defect-per-start dataset with host metadata, defect energetics, consensus values, and inline structures.
- Campaign summary · Campaign-level object with global metadata, host ranking, and nested per-host records.
- Consensus screen · Three-model consensus with best-of-two-start selection and stability-polygon minimization.
Figure scripts
In-repo reproducibility scripts for figures and derived analyses.
- Fig 2 · Main-text figure reproduction script.
figure_scripts/make_fig2.py - Fig 3 · Main-text figure reproduction script.
figure_scripts/make_fig3.py - Fig 4 · Main-text figure reproduction script.
figure_scripts/make_fig4.py - Fig 5 · Main-text figure reproduction script.
figure_scripts/make_fig5.py - Fig 6 · Main-text figure reproduction script.
figure_scripts/make_fig6.py - Fig S2 · Supplementary ionicity figure reproduction script.
figure_scripts/make_figS2_ionicity.py - Fig S3 · Supplementary finite-size figure reproduction script.
figure_scripts/make_figS3_finitesize.py - Binding energies · Computes chemical-potential-free binding energies for figure analysis.
figure_scripts/compute_binding.py - Sensitivity · Performs finite-size and constant-volume sensitivity calculations.
figure_scripts/sensitivity.py - Family reclass · Reclassifies material families for analysis consistency.
figure_scripts/family_reclass.py - Q GAN · Auxiliary analysis helper for defect or host labeling and ranking.
figure_scripts/q_gan.py
ML force fields
Three-model consensus screening layer used to generate the defect dataset.
- CHGNet · One of the three foundation ML force fields in the screening consensus.
- M3GNet · One of the three foundation ML force fields in the screening consensus.
- MACE · One of the three foundation ML force fields in the screening consensus.
Connections 28
- CHGNet → Consensus screen: scores defects · Predicts defect energetics for one branch of the consensus screening.
- M3GNet → Consensus screen: scores defects · Predicts defect energetics for one branch of the consensus screening.
- MACE → Consensus screen: scores defects · Predicts defect energetics for one branch of the consensus screening.
- Consensus screen → Defect table: writes table · Stores per-defect consensus energies, start selection, and structural payloads.
- Consensus screen → Campaign summary: summarizes · Produces campaign-level host ranking and per-host records.
- Defect table → Campaign summary: rolls up · Provides the normalized defect data used in the higher-level summary object.
- Figure inputs → Fig 2: inputs · Figure-specific extracted inputs consumed by the plotting script.
- Figure inputs → Fig 3: inputs · Figure-specific extracted inputs consumed by the plotting script.
- Figure inputs → Fig 4: inputs · Figure-specific extracted inputs consumed by the plotting script.
- Figure inputs → Fig 5: inputs · Figure-specific extracted inputs consumed by the plotting script.
- Figure inputs → Fig 6: inputs · Figure-specific extracted inputs consumed by the plotting script.
- Figure inputs → Fig S2: inputs · Figure-specific extracted inputs consumed by the plotting script.
- Figure inputs → Fig S3: inputs · Figure-specific extracted inputs consumed by the plotting script.
- Defect table → Binding energies: queries · Provides defect energetics for binding-energy derivations.
- Defect table → Sensitivity: queries · Provides structures and energies for sensitivity calculations.
- Defect table → Q GAN: queries · Provides host/defect records for auxiliary ranking or labeling logic.
- Campaign summary → Family reclass: normalizes · Supplies campaign metadata for family-level analysis consistency.
- Binding energies → Fig 4: supports · Provides derived quantities for the Fig. 4 workflow.
- Sensitivity → Fig S3: supports · Provides finite-size derivations for the supplementary figure.
- Family reclass → Fig 3: supports · Feeds family-consistent analysis inputs into the figure workflow.
- Q GAN → Campaign summary: refines · Feeds auxiliary ranking or labeling results back into campaign-level summaries.
- Fig 2 → Paper figures: renders · Produces paper-ready visual output.
- Fig 3 → Paper figures: renders · Produces paper-ready visual output.
- Fig 4 → Paper figures: renders · Produces paper-ready visual output.
- Fig 5 → Paper figures: renders · Produces paper-ready visual output.
- Fig 6 → Paper figures: renders · Produces paper-ready visual output.
- Fig S2 → Paper figures: renders · Produces supplementary visual output.
- Fig S3 → Paper figures: renders · Produces supplementary visual output.