# deepgraphlearning/gearnet architecture

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

- Interactive diagram: https://gitdiagram.com/deepgraphlearning/gearnet
- Repository: https://github.com/deepgraphlearning/gearnet

## Overview

GearNet is a PyTorch/TorchDrug protein-structure representation learning codebase. Users configure and launch pretraining or downstream experiments; datasets are constructed as protein graphs, encoded by geometric relational message passing, and trained/evaluated for protein-function or structure tasks. The graph captures documented pretraining objectives and benchmark families; configuration supports variants beyond the sampled implementation. Dataset and model details are sampled, while other TorchDrug-backed task and dataset wiring is documented or config-driven.

Main entry points: [`script/downstream.py`](https://github.com/deepgraphlearning/gearnet/blob/main/script/downstream.py) (Downstream runner), [`script/pretrain.py`](https://github.com/deepgraphlearning/gearnet/blob/main/script/pretrain.py) (Pretrain runner), [`gearnet/model.py`](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/model.py) (GearNet encoder), [`config/pretrain`](https://github.com/deepgraphlearning/gearnet/tree/main/config/pretrain) (Self-supervised objectives)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_experiment["Experiment runs"]
  node_pretrain_cli["Pretrain runner<br/>[pretrain.py]"]
  node_downstream_cli["Downstream runner<br/>[downstream.py]"]
  node_config["Experiment configs"]
  node_util["Experiment setup<br/>[util.py]"]
end

subgraph group_data["Protein data"]
  node_protein_data["Protein datasets<br/>[dataset.py]"]
  node_fold3d["Fold3D loader<br/>[dataset.py]"]
  node_protein_graph["Residue graphs<br/>[dataset.py]"]
  node_pretrain_data["Pretraining corpus"]
  node_benchmarks["Task benchmarks"]
end

subgraph group_encoding["Graph encoding"]
  node_gearnet["GearNet encoder<br/>[model.py]"]
  node_fusion["Sequence fusion<br/>[model.py]"]
  node_relational_conv["Relational convolution<br/>[layer.py]"]
  node_ieconv["IEConv<br/>[layer.py]"]
end

subgraph group_learning["Learning tasks"]
  node_pretrain_task["Self-supervised objectives"]
  node_multiview["Multiview contrast"]
  node_residue_type["Residue prediction"]
  node_geometry_tasks["Geometry prediction"]
  node_downstream_task["Task prediction"]
  node_checkpoint["Model checkpoints<br/>[pretrain.py]"]
  node_evaluation["Validation and test<br/>[downstream.py]"]
end

node_user(("Researcher"))
node_torchdrug["TorchDrug runtime"]

node_user -->|"launches"| node_pretrain_cli
node_user -->|"launches"| node_downstream_cli
node_pretrain_cli -->|"loads config"| node_config
node_downstream_cli -->|"loads config"| node_config
node_pretrain_cli -->|"sets up"| node_util
node_downstream_cli -->|"sets up"| node_util
node_pretrain_cli -->|"builds and trains"| node_torchdrug
node_downstream_cli -->|"builds solver"| node_torchdrug
node_util -->|"constructs engine"| node_torchdrug
node_pretrain_cli -->|"loads dataset config"| node_pretrain_data
node_downstream_cli -->|"loads task config"| node_benchmarks
node_torchdrug -->|"constructs dataset"| node_protein_data
node_fold3d -->|"builds graphs"| node_protein_graph
node_protein_data -->|"provides graphs"| node_protein_graph
node_protein_data -->|"splits samples"| node_torchdrug
node_torchdrug -->|"invokes encoder"| node_gearnet
node_gearnet -->|"applies layers"| node_relational_conv
node_gearnet -.->|"optionally applies"| node_ieconv
node_gearnet -.->|"used by"| node_fusion
node_torchdrug -->|"trains objective"| node_pretrain_task
node_pretrain_task -->|"configures"| node_multiview
node_pretrain_task -->|"configures"| node_residue_type
node_pretrain_task -->|"configures"| node_geometry_tasks
node_pretrain_cli -->|"saves weights"| node_checkpoint
node_downstream_cli -->|"trains task"| node_downstream_task
node_downstream_cli -->|"evaluates"| node_evaluation
node_downstream_task -->|"uses labels"| node_benchmarks
node_downstream_cli -.->|"loads weights"| node_checkpoint

click node_pretrain_cli "https://github.com/deepgraphlearning/gearnet/blob/main/script/pretrain.py"
click node_downstream_cli "https://github.com/deepgraphlearning/gearnet/blob/main/script/downstream.py"
click node_config "https://github.com/deepgraphlearning/gearnet/tree/main/config"
click node_util "https://github.com/deepgraphlearning/gearnet/blob/main/util.py"
click node_protein_data "https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/dataset.py"
click node_fold3d "https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/dataset.py"
click node_protein_graph "https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/dataset.py"
click node_pretrain_data "https://github.com/deepgraphlearning/gearnet/tree/main/config/pretrain"
click node_benchmarks "https://github.com/deepgraphlearning/gearnet/tree/main/config/downstream"
click node_gearnet "https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/model.py"
click node_fusion "https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/model.py"
click node_relational_conv "https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/layer.py"
click node_ieconv "https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/layer.py"
click node_pretrain_task "https://github.com/deepgraphlearning/gearnet/tree/main/config/pretrain"
click node_multiview "https://github.com/deepgraphlearning/gearnet/blob/main/config/pretrain/mc_gearnet_edge.yaml"
click node_residue_type "https://github.com/deepgraphlearning/gearnet/blob/main/config/pretrain/attr_gearnet_edge.yaml"
click node_geometry_tasks "https://github.com/deepgraphlearning/gearnet/tree/main/config/pretrain"
click node_downstream_task "https://github.com/deepgraphlearning/gearnet/tree/main/config/downstream"
click node_checkpoint "https://github.com/deepgraphlearning/gearnet/blob/main/script/pretrain.py"
click node_evaluation "https://github.com/deepgraphlearning/gearnet/blob/main/script/downstream.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_pretrain_cli,node_downstream_cli,node_config,node_util toneBlue
class node_protein_data,node_fold3d,node_protein_graph,node_pretrain_data,node_benchmarks toneAmber
class node_gearnet,node_fusion,node_relational_conv,node_ieconv toneMint
class node_pretrain_task,node_multiview,node_residue_type,node_geometry_tasks,node_downstream_task,node_checkpoint,node_evaluation toneRose
class node_user,node_torchdrug toneIndigo
```

## Components

### Experiment runs

- [Pretrain runner](https://github.com/deepgraphlearning/gearnet/blob/main/script/pretrain.py): `script/pretrain.py`
- [Downstream runner](https://github.com/deepgraphlearning/gearnet/blob/main/script/downstream.py): `script/downstream.py`
- [Experiment configs](https://github.com/deepgraphlearning/gearnet/tree/main/config): `config`
- [Experiment setup](https://github.com/deepgraphlearning/gearnet/blob/main/util.py): `util.py`

### Protein data

- [Protein datasets](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/dataset.py): `gearnet/dataset.py`
- [Fold3D loader](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/dataset.py): `gearnet/dataset.py`
- [Residue graphs](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/dataset.py): `gearnet/dataset.py`
- [Pretraining corpus](https://github.com/deepgraphlearning/gearnet/tree/main/config/pretrain): `config/pretrain`
- [Task benchmarks](https://github.com/deepgraphlearning/gearnet/tree/main/config/downstream): `config/downstream`

### Graph encoding

- [GearNet encoder](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/model.py): `gearnet/model.py`
- [Sequence fusion](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/model.py): `gearnet/model.py`
- [Relational convolution](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/layer.py): `gearnet/layer.py`
- [IEConv](https://github.com/deepgraphlearning/gearnet/blob/main/gearnet/layer.py): `gearnet/layer.py`

### Learning tasks

- [Self-supervised objectives](https://github.com/deepgraphlearning/gearnet/tree/main/config/pretrain): `config/pretrain`
- [Multiview contrast](https://github.com/deepgraphlearning/gearnet/blob/main/config/pretrain/mc_gearnet_edge.yaml): `config/pretrain/mc_gearnet_edge.yaml`
- [Residue prediction](https://github.com/deepgraphlearning/gearnet/blob/main/config/pretrain/attr_gearnet_edge.yaml): `config/pretrain/attr_gearnet_edge.yaml`
- [Geometry prediction](https://github.com/deepgraphlearning/gearnet/tree/main/config/pretrain): `config/pretrain`
- [Task prediction](https://github.com/deepgraphlearning/gearnet/tree/main/config/downstream): `config/downstream`
- [Model checkpoints](https://github.com/deepgraphlearning/gearnet/blob/main/script/pretrain.py): `script/pretrain.py`
- [Validation and test](https://github.com/deepgraphlearning/gearnet/blob/main/script/downstream.py): `script/downstream.py`

### Other components

- **Researcher**
- **TorchDrug runtime**

## Connections

- Researcher → Pretrain runner: launches
- Researcher → Downstream runner: launches
- Pretrain runner → Experiment configs: loads config
- Downstream runner → Experiment configs: loads config
- Pretrain runner → Experiment setup: sets up
- Downstream runner → Experiment setup: sets up
- Pretrain runner → TorchDrug runtime: builds and trains
- Downstream runner → TorchDrug runtime: builds solver
- Experiment setup → TorchDrug runtime: constructs engine
- Pretrain runner → Pretraining corpus: loads dataset config
- Downstream runner → Task benchmarks: loads task config
- TorchDrug runtime → Protein datasets: constructs dataset
- Fold3D loader → Residue graphs: builds graphs
- Protein datasets → Residue graphs: provides graphs
- Protein datasets → TorchDrug runtime: splits samples
- TorchDrug runtime → GearNet encoder: invokes encoder
- GearNet encoder → Relational convolution: applies layers
- GearNet encoder → IEConv: optionally applies
- GearNet encoder → Sequence fusion: used by
- TorchDrug runtime → Self-supervised objectives: trains objective
- Self-supervised objectives → Multiview contrast: configures
- Self-supervised objectives → Residue prediction: configures
- Self-supervised objectives → Geometry prediction: configures
- Pretrain runner → Model checkpoints: saves weights
- Downstream runner → Task prediction: trains task
- Downstream runner → Validation and test: evaluates
- Task prediction → Task benchmarks: uses labels
- Downstream runner → Model checkpoints: loads weights
