# raza786r/dpt-gnn architecture

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

- Interactive diagram: https://gitdiagram.com/raza786r/dpt-gnn
- Repository: https://github.com/raza786r/dpt-gnn

## Overview

DPT-GNN is a research pipeline for predicting lithium-ion cathode gravimetric capacity from paired charged/discharged crystal structures and eight numeric descriptors. The documented workflow loads the canonical data splits, encodes both structures with a shared graph Transformer, models their transition, fuses numeric features, and trains/evaluates capacity regression. The README describes these stages and capabilities, but notebook source was not sampled, so arrows reflect documented behavior; exact internal call wiring is not verified. CIF inputs and trained weights are not included in the tree.

Main entry points: [`DPT_GNN_Model.ipynb`](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb) (Pipeline notebook), [`data`](https://github.com/raza786r/dpt-gnn/tree/main/data) (Processed splits), [`reproducibility/features.json`](https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/features.json) (Feature definitions), [`reproducibility/training_history.csv`](https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/training_history.csv) (Training history)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_inputs["Inputs"]
  node_split_data["Processed splits"]
  node_cif_inputs["Paired CIF structures"]
  node_features["Feature definitions<br/>[features.json]"]
end

subgraph group_encoding["Representation"]
  node_shared_encoder["Shared graph encoder"]
  node_relation_block["Phase relation block"]
  node_numeric_branch["Numeric feature branch"]
end

subgraph group_prediction["Prediction"]
  node_capacity_head["Capacity predictor"]
end

subgraph group_evaluation["Training &amp; Evaluation"]
  node_notebook["Pipeline notebook"]
  node_composite_loss["Huber-Pearson loss"]
  node_training["Model training"]
  node_metrics["Regression metrics"]
  node_training_history["Training history"]
  node_checkpoint_hash["Checkpoint hash"]
end

node_researcher(("Researcher"))
node_materials_project(("Materials Project"))

node_researcher -->|"runs"| node_notebook
node_researcher -.->|"retrieves CIFs"| node_materials_project
node_materials_project -.->|"provides structures"| node_cif_inputs
node_researcher -->|"provides data"| node_split_data
node_researcher -->|"provides structures"| node_cif_inputs
node_researcher -->|"configures features"| node_features
node_notebook -->|"loads splits"| node_split_data
node_notebook -->|"uses paired structures"| node_cif_inputs
node_notebook -->|"uses feature list"| node_features
node_notebook -->|"encodes both phases"| node_shared_encoder
node_shared_encoder -->|"passes embeddings"| node_relation_block
node_notebook -->|"encodes descriptors"| node_numeric_branch
node_notebook -->|"fuses representations"| node_capacity_head
node_relation_block -->|"provides transition features"| node_capacity_head
node_numeric_branch -->|"provides numeric features"| node_capacity_head
node_notebook -->|"trains model"| node_training
node_training -->|"optimizes predictions"| node_capacity_head
node_training -->|"computes objective"| node_composite_loss
node_training -->|"records epochs"| node_training_history
node_notebook -->|"evaluates predictions"| node_metrics
node_notebook -.->|"verifies checkpoint"| node_checkpoint_hash

click node_split_data "https://github.com/raza786r/dpt-gnn/tree/main/data"
click node_notebook "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_shared_encoder "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_relation_block "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_numeric_branch "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_capacity_head "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_composite_loss "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_training "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_metrics "https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb"
click node_training_history "https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/training_history.csv"
click node_features "https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/features.json"
click node_checkpoint_hash "https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/checkpoint_hash.txt"

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_split_data,node_cif_inputs,node_features toneBlue
class node_shared_encoder,node_relation_block,node_numeric_branch toneAmber
class node_capacity_head toneMint
class node_notebook,node_composite_loss,node_training,node_metrics,node_training_history,node_checkpoint_hash toneRose
class node_researcher,node_materials_project toneIndigo
```

## Components

### Inputs

- [Processed splits](https://github.com/raza786r/dpt-gnn/tree/main/data): `data`
- **Paired CIF structures**
- [Feature definitions](https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/features.json): `reproducibility/features.json`

### Representation

- [Shared graph encoder](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`
- [Phase relation block](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`
- [Numeric feature branch](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`

### Prediction

- [Capacity predictor](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`

### Training & Evaluation

- [Pipeline notebook](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`
- [Huber-Pearson loss](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`
- [Model training](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`
- [Regression metrics](https://github.com/raza786r/dpt-gnn/blob/main/DPT_GNN_Model.ipynb): `DPT_GNN_Model.ipynb`
- [Training history](https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/training_history.csv): `reproducibility/training_history.csv`
- [Checkpoint hash](https://github.com/raza786r/dpt-gnn/blob/main/reproducibility/checkpoint_hash.txt): `reproducibility/checkpoint_hash.txt`

### Other components

- **Researcher**
- **Materials Project**

## Connections

- Researcher → Pipeline notebook: runs
- Researcher → Materials Project: retrieves CIFs
- Materials Project → Paired CIF structures: provides structures
- Researcher → Processed splits: provides data
- Researcher → Paired CIF structures: provides structures
- Researcher → Feature definitions: configures features
- Pipeline notebook → Processed splits: loads splits
- Pipeline notebook → Paired CIF structures: uses paired structures
- Pipeline notebook → Feature definitions: uses feature list
- Pipeline notebook → Shared graph encoder: encodes both phases
- Shared graph encoder → Phase relation block: passes embeddings
- Pipeline notebook → Numeric feature branch: encodes descriptors
- Pipeline notebook → Capacity predictor: fuses representations
- Phase relation block → Capacity predictor: provides transition features
- Numeric feature branch → Capacity predictor: provides numeric features
- Pipeline notebook → Model training: trains model
- Model training → Capacity predictor: optimizes predictions
- Model training → Huber-Pearson loss: computes objective
- Model training → Training history: records epochs
- Pipeline notebook → Regression metrics: evaluates predictions
- Pipeline notebook → Checkpoint hash: verifies checkpoint