# msehabibur/wbg_defect_screening architecture

> Architecture diagram of the GitHub repository msehabibur/wbg_defect_screening, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-06-18). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/msehabibur/wbg_defect_screening
- Repository: https://github.com/msehabibur/wbg_defect_screening

## Overview

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: [`figure_scripts/make_fig3.py`](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig3.py) (Fig 3), [`figure_scripts/make_fig4.py`](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig4.py) (Fig 4), [`figure_scripts/make_figS3_finitesize.py`](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_figS3_finitesize.py) (Fig S3), [`figure_scripts/make_fig2.py`](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig2.py) (Fig 2)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g_release["Release artifacts"]
  node_n_figure_data["Figure inputs<br/>release bundle"]
  node_n_figures["Paper figures<br/>visual outputs"]
end

subgraph group_g_core["Core data model"]
  node_n_defect_records[("Defect table<br/>parquet data")]
  node_n_campaign_json["Campaign summary<br/>json summary"]
  node_n_consensus{{"Consensus screen<br/>ranking logic"}}
end

subgraph group_g_scripts["Figure scripts"]
  node_n_fig2["Fig 2<br/>plot script<br/>[make_fig2.py]"]
  node_n_fig3["Fig 3<br/>plot script<br/>[make_fig3.py]"]
  node_n_fig4["Fig 4<br/>plot script<br/>[make_fig4.py]"]
  node_n_fig5["Fig 5<br/>plot script<br/>[make_fig5.py]"]
  node_n_fig6["Fig 6<br/>plot script<br/>[make_fig6.py]"]
  node_n_figs2["Fig S2<br/>supplement plot"]
  node_n_figs3["Fig S3<br/>supplement plot"]
  node_n_binding["Binding energies<br/>analysis script<br/>[compute_binding.py]"]
  node_n_sensitivity["Sensitivity<br/>analysis script<br/>[sensitivity.py]"]
  node_n_family["Family reclass<br/>analysis script<br/>[family_reclass.py]"]
  node_n_qgan["Q GAN<br/>analysis script<br/>[q_gan.py]"]
end

subgraph group_g_models["ML force fields"]
  node_n_chgnet["CHGNet<br/>force field"]
  node_n_m3gnet["M3GNet<br/>force field"]
  node_n_mace["MACE<br/>force field"]
end

node_n_chgnet -->|"scores defects"| node_n_consensus
node_n_m3gnet -->|"scores defects"| node_n_consensus
node_n_mace -->|"scores defects"| node_n_consensus
node_n_consensus -->|"writes table"| node_n_defect_records
node_n_consensus -->|"summarizes"| node_n_campaign_json
node_n_defect_records -->|"rolls up"| node_n_campaign_json
node_n_figure_data -->|"inputs"| node_n_fig2
node_n_figure_data -->|"inputs"| node_n_fig3
node_n_figure_data -->|"inputs"| node_n_fig4
node_n_figure_data -->|"inputs"| node_n_fig5
node_n_figure_data -->|"inputs"| node_n_fig6
node_n_figure_data -->|"inputs"| node_n_figs2
node_n_figure_data -->|"inputs"| node_n_figs3
node_n_defect_records -->|"queries"| node_n_binding
node_n_defect_records -->|"queries"| node_n_sensitivity
node_n_defect_records -->|"queries"| node_n_qgan
node_n_campaign_json -->|"normalizes"| node_n_family
node_n_binding -->|"supports"| node_n_fig4
node_n_sensitivity -->|"supports"| node_n_figs3
node_n_family -->|"supports"| node_n_fig3
node_n_qgan -->|"refines"| node_n_campaign_json
node_n_fig2 -->|"renders"| node_n_figures
node_n_fig3 -->|"renders"| node_n_figures
node_n_fig4 -->|"renders"| node_n_figures
node_n_fig5 -->|"renders"| node_n_figures
node_n_fig6 -->|"renders"| node_n_figures
node_n_figs2 -->|"renders"| node_n_figures
node_n_figs3 -->|"renders"| node_n_figures

click node_n_fig2 "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig2.py"
click node_n_fig3 "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig3.py"
click node_n_fig4 "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig4.py"
click node_n_fig5 "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig5.py"
click node_n_fig6 "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig6.py"
click node_n_figs2 "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_figS2_ionicity.py"
click node_n_figs3 "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_figS3_finitesize.py"
click node_n_binding "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/compute_binding.py"
click node_n_sensitivity "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/sensitivity.py"
click node_n_family "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/family_reclass.py"
click node_n_qgan "https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/q_gan.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_n_figure_data,node_n_figures toneBlue
class node_n_defect_records,node_n_campaign_json,node_n_consensus toneAmber
class node_n_fig2,node_n_fig3,node_n_fig4,node_n_fig5,node_n_fig6,node_n_figs2,node_n_figs3,node_n_binding,node_n_sensitivity,node_n_family,node_n_qgan toneMint
class node_n_chgnet,node_n_m3gnet,node_n_mace toneRose
```

## Components

### Release artifacts

Large immutable data products downloaded from GitHub Releases.

- **Figure inputs**: release bundle · Extracted figure-specific inputs used by the plotting scripts.
- **Paper figures**: visual outputs · Rendered main-text and supplementary figures for the paper.

### Core data model

Canonical campaign tables and summary objects used by analysis scripts.

- **Defect table**: parquet data · Canonical row-per-defect-per-start dataset with host metadata, defect energetics, consensus values, and inline structures.
- **Campaign summary**: json summary · Campaign-level object with global metadata, host ranking, and nested per-host records.
- **Consensus screen**: ranking logic · 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](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig2.py): plot script · Main-text figure reproduction script. · `figure_scripts/make_fig2.py`
- [Fig 3](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig3.py): plot script · Main-text figure reproduction script. · `figure_scripts/make_fig3.py`
- [Fig 4](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig4.py): plot script · Main-text figure reproduction script. · `figure_scripts/make_fig4.py`
- [Fig 5](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig5.py): plot script · Main-text figure reproduction script. · `figure_scripts/make_fig5.py`
- [Fig 6](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_fig6.py): plot script · Main-text figure reproduction script. · `figure_scripts/make_fig6.py`
- [Fig S2](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_figS2_ionicity.py): supplement plot · Supplementary ionicity figure reproduction script. · `figure_scripts/make_figS2_ionicity.py`
- [Fig S3](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/make_figS3_finitesize.py): supplement plot · Supplementary finite-size figure reproduction script. · `figure_scripts/make_figS3_finitesize.py`
- [Binding energies](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/compute_binding.py): analysis script · Computes chemical-potential-free binding energies for figure analysis. · `figure_scripts/compute_binding.py`
- [Sensitivity](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/sensitivity.py): analysis script · Performs finite-size and constant-volume sensitivity calculations. · `figure_scripts/sensitivity.py`
- [Family reclass](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/family_reclass.py): analysis script · Reclassifies material families for analysis consistency. · `figure_scripts/family_reclass.py`
- [Q GAN](https://github.com/msehabibur/wbg_defect_screening/blob/main/figure_scripts/q_gan.py): analysis script · 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**: force field · One of the three foundation ML force fields in the screening consensus.
- **M3GNet**: force field · One of the three foundation ML force fields in the screening consensus.
- **MACE**: force field · One of the three foundation ML force fields in the screening consensus.

## Connections

- 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.