# pyg-team/pytorch_geometric architecture

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

- Interactive diagram: https://gitdiagram.com/pyg-team/pytorch_geometric
- Repository: https://github.com/pyg-team/pytorch_geometric

## Overview

PyTorch Geometric is a graph and geometric deep-learning library. Its primary user workflow is to obtain graph data, represent and batch it, optionally transform or sample it, run graph neural network operators and models, then train or explain the results. It also supports heterogeneous and large-scale/distributed graph workflows, graph transformations, benchmark datasets, and GraphGym experiment orchestration. The README documents the workflow; sampled entry-point code confirms GraphGym orchestration. Other subsystem links are limited to explicit imports or documented relationships, since much of the runtime was not sampled.

Main entry points: [`torch_geometric/data/data.py`](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/data.py) (Graph Data), [`graphgym/main.py`](https://github.com/pyg-team/pytorch_geometric/blob/master/graphgym/main.py) (GraphGym CLI), [`torch_geometric/nn/conv`](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/nn/conv) (GNN Operators), [`torch_geometric/graphgym/loader.py`](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/loader.py) (GraphGym Data)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Graph Data"]
  node_datasets["Datasets"]
  node_graphdata["Graph Data<br/>[data.py]"]
  node_heterodata["Heterogeneous Data<br/>[hetero_data.py]"]
  node_batching["Batching<br/>[batch.py]"]
  node_transforms["Graph Transforms"]
  node_loaders["Mini-batch Loaders"]
end

subgraph group_compute["GNN Compute"]
  node_operators["GNN Operators"]
  node_models["GNN Models"]
  node_heteroconvert["Hetero Conversion"]
end

subgraph group_workflow["Learning Workflows"]
  node_training["GraphGym Training<br/>[train.py]"]
  node_graphgymloader["GraphGym Data<br/>[loader.py]"]
  node_graphgymconfig["GraphGym Config<br/>[config.py]"]
  node_registry["Component Registry<br/>[register.py]"]
  node_explain["GNN Explanations<br/>[config.py]"]
  node_metrics["Link Metrics<br/>[link_pred.py]"]
  node_graphgym["GraphGym CLI<br/>[main.py]"]
end

subgraph group_scale["Scale and Storage"]
  node_graphstore[("Graph Store<br/>[graph_store.py]")]
  node_featurestore[("Feature Store<br/>[feature_store.py]")]
  node_samplers["Neighbor Sampling"]
  node_distributed["Distributed Runtime"]
  node_database[("Data Database<br/>[database.py]")]
end

subgraph group_platform["Core Platform"]
  node_edgeindex["Edge Index<br/>[edge_index.py]"]
  node_utilities["Graph Utilities"]
  node_typing["Backend Typing<br/>[typing.py]"]
  node_logging["Logging<br/>[logging.py]"]
  node_warnings["Warnings<br/>[warnings.py]"]
end

node_user(("Library User"))

node_user -->|"loads data"| node_datasets
node_user -->|"builds model"| node_operators
node_datasets -->|"provides graphs"| node_graphdata
node_graphdata -->|"batches graphs"| node_batching
node_graphdata -->|"transforms graph"| node_transforms
node_graphdata -->|"feeds loader"| node_loaders
node_loaders -.->|"samples neighbors"| node_samplers
node_graphdata -->|"represents graph data"| node_heterodata
node_graphdata -->|"exposes store API"| node_graphstore
node_graphdata -->|"exposes store API"| node_featurestore
node_graphdata -->|"exposes database API"| node_database
node_operators -.->|"operates on edges"| node_edgeindex
node_operators -->|"builds models"| node_models
node_models -->|"produces predictions"| node_user
node_heterodata -.->|"supports conversion"| node_heteroconvert
node_user -.->|"configures explanations"| node_explain
node_user -.->|"evaluates links"| node_metrics
node_user -.->|"runs at scale"| node_distributed
node_user -->|"runs experiment"| node_graphgym
node_graphgym -->|"loads configuration"| node_graphgymconfig
node_graphgym -->|"creates data module"| node_graphgymloader
node_graphgym -->|"creates model"| node_models
node_graphgym -->|"starts training"| node_training
node_graphgym -->|"sets printing"| node_logging
node_graphgymconfig -->|"uses registry"| node_registry
node_graphgymloader -->|"reads config"| node_graphgymconfig
node_graphgymloader -->|"uses registry"| node_registry
node_graphdata -->|"uses graph operations"| node_utilities
node_samplers -->|"reads graph store"| node_graphstore
node_graphdata -->|"uses backend types"| node_typing
node_database -->|"emits warnings"| node_warnings

click node_datasets "https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/datasets"
click node_graphdata "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/data.py"
click node_heterodata "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/hetero_data.py"
click node_graphstore "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/graph_store.py"
click node_featurestore "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/feature_store.py"
click node_batching "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/batch.py"
click node_transforms "https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/transforms"
click node_loaders "https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/loader"
click node_samplers "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/sampler/neighbor_sampler.py"
click node_edgeindex "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/edge_index.py"
click node_operators "https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/nn/conv"
click node_models "https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/nn/models"
click node_heteroconvert "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/nn/to_hetero_with_bases_transformer.py"
click node_training "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/train.py"
click node_graphgymloader "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/loader.py"
click node_graphgymconfig "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/config.py"
click node_registry "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/register.py"
click node_explain "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/explain/config.py"
click node_metrics "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/metrics/link_pred.py"
click node_distributed "https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/distributed"
click node_utilities "https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/utils"
click node_typing "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/typing.py"
click node_logging "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/logging.py"
click node_warnings "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/warnings.py"
click node_database "https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/database.py"
click node_graphgym "https://github.com/pyg-team/pytorch_geometric/blob/master/graphgym/main.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_datasets,node_graphdata,node_heterodata,node_batching,node_transforms,node_loaders,node_user toneBlue
class node_operators,node_models,node_heteroconvert toneAmber
class node_training,node_graphgymloader,node_graphgymconfig,node_registry,node_explain,node_metrics,node_graphgym toneMint
class node_graphstore,node_featurestore,node_samplers,node_distributed,node_database toneRose
class node_edgeindex,node_utilities,node_typing,node_logging,node_warnings toneIndigo
```

## Components

### Graph Data

- [Datasets](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/datasets): `torch_geometric/datasets`
- [Graph Data](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/data.py): `torch_geometric/data/data.py`
- [Heterogeneous Data](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/hetero_data.py): `torch_geometric/data/hetero_data.py`
- [Batching](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/batch.py): `torch_geometric/data/batch.py`
- [Graph Transforms](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/transforms): `torch_geometric/transforms`
- [Mini-batch Loaders](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/loader): `torch_geometric/loader`

### GNN Compute

- [GNN Operators](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/nn/conv): `torch_geometric/nn/conv`
- [GNN Models](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/nn/models): `torch_geometric/nn/models`
- [Hetero Conversion](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/nn/to_hetero_with_bases_transformer.py): `torch_geometric/nn/to_hetero_with_bases_transformer.py`

### Learning Workflows

- [GraphGym Training](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/train.py): `torch_geometric/graphgym/train.py`
- [GraphGym Data](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/loader.py): `torch_geometric/graphgym/loader.py`
- [GraphGym Config](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/config.py): `torch_geometric/graphgym/config.py`
- [Component Registry](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/graphgym/register.py): `torch_geometric/graphgym/register.py`
- [GNN Explanations](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/explain/config.py): `torch_geometric/explain/config.py`
- [Link Metrics](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/metrics/link_pred.py): `torch_geometric/metrics/link_pred.py`
- [GraphGym CLI](https://github.com/pyg-team/pytorch_geometric/blob/master/graphgym/main.py): `graphgym/main.py`

### Scale and Storage

- [Graph Store](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/graph_store.py): `torch_geometric/data/graph_store.py`
- [Feature Store](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/feature_store.py): `torch_geometric/data/feature_store.py`
- [Neighbor Sampling](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/sampler/neighbor_sampler.py): `torch_geometric/sampler/neighbor_sampler.py`
- [Distributed Runtime](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/distributed): `torch_geometric/distributed`
- [Data Database](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/data/database.py): `torch_geometric/data/database.py`

### Core Platform

- [Edge Index](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/edge_index.py): `torch_geometric/edge_index.py`
- [Graph Utilities](https://github.com/pyg-team/pytorch_geometric/tree/master/torch_geometric/utils): `torch_geometric/utils`
- [Backend Typing](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/typing.py): `torch_geometric/typing.py`
- [Logging](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/logging.py): `torch_geometric/logging.py`
- [Warnings](https://github.com/pyg-team/pytorch_geometric/blob/master/torch_geometric/warnings.py): `torch_geometric/warnings.py`

### Other components

- **Library User**

## Connections

- Library User → Datasets: loads data
- Library User → GNN Operators: builds model
- Datasets → Graph Data: provides graphs
- Graph Data → Batching: batches graphs
- Graph Data → Graph Transforms: transforms graph
- Graph Data → Mini-batch Loaders: feeds loader
- Mini-batch Loaders → Neighbor Sampling: samples neighbors
- Graph Data → Heterogeneous Data: represents graph data (evidence: `torch_geometric/data/__init__.py`)
- Graph Data → Graph Store: exposes store API (evidence: `torch_geometric/data/__init__.py`)
- Graph Data → Feature Store: exposes store API (evidence: `torch_geometric/data/__init__.py`)
- Graph Data → Data Database: exposes database API (evidence: `torch_geometric/data/__init__.py`)
- GNN Operators → Edge Index: operates on edges
- GNN Operators → GNN Models: builds models
- GNN Models → Library User: produces predictions
- Heterogeneous Data → Hetero Conversion: supports conversion
- Library User → GNN Explanations: configures explanations
- Library User → Link Metrics: evaluates links
- Library User → Distributed Runtime: runs at scale
- Library User → GraphGym CLI: runs experiment (evidence: `graphgym/main.py`)
- GraphGym CLI → GraphGym Config: loads configuration (evidence: `graphgym/main.py`)
- GraphGym CLI → GraphGym Data: creates data module (evidence: `graphgym/main.py`)
- GraphGym CLI → GNN Models: creates model (evidence: `graphgym/main.py`)
- GraphGym CLI → GraphGym Training: starts training (evidence: `graphgym/main.py`)
- GraphGym CLI → Logging: sets printing (evidence: `graphgym/main.py`)
- GraphGym Config → Component Registry: uses registry (evidence: `torch_geometric/graphgym/config.py`)
- GraphGym Data → GraphGym Config: reads config (evidence: `torch_geometric/graphgym/loader.py`)
- GraphGym Data → Component Registry: uses registry (evidence: `torch_geometric/graphgym/loader.py`)
- Graph Data → Graph Utilities: uses graph operations
- Neighbor Sampling → Graph Store: reads graph store (evidence: `torch_geometric/sampler/neighbor_sampler.py`)
- Graph Data → Backend Typing: uses backend types
- Data Database → Warnings: emits warnings (evidence: `torch_geometric/data/database.py`)
