# atomicarchitects/equiformer architecture

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

- Interactive diagram: https://gitdiagram.com/atomicarchitects/equiformer
- Repository: https://github.com/atomicarchitects/equiformer

## Overview

##### Main Components
- Data Sources and Preprocessing:
- Datasets folder (with subdirectories like datasets/pyg) where data for QM9, MD17, and OC20 reside.
- Automatic dataset download and symbolic links (such as for OC20) as part of the data ingestion layer.

- Model Architectures (Nets):
- “nets” directory as a core module, containing various transformer implementations (e.g., dp_attention_transformer, graph_attention_transformer) which include variants for different datasets (QM9, MD17, OC20).
- That many network files include components such as attention, normalization layers, activation functions, and radial functions that contribute to the equivariant nature.

- Training and Evaluation Pipelines:
- For each dataset, include separate entry points:
- QM9: main_qm9.py and its corresponding training scripts in scripts/train/qm9 (and dp_equiformer variants).
- MD17: main_md17.py and main_md17_dens.py for the standard and DeNS-enhanced training, with corresponding directory structures under md17/configs and scripts/train/md17.
- OC20: main_oc20.py and oc20/trainer with its configurations under oc20/configs.
- These components also integrate environment configuration (such as env/env_equiformer.yml) for reproducible setups.

- Configuration and Utility Components:
- Configuration files (YAML files in md17/configs and oc20/configs) that define model hyperparameters, training settings, and dataset specifics.
- Utility modules like engine.py, logger.py, and optim_factory.py that manage training loops, logging, and optimizer configurations.
- Scripts directory is also important as it provides shell scripts that kick off training experiments for different datasets and model variants.

##### Relationships and Interactions
- Training scripts (from scripts/) and main entry points (main_qm9.py, main_md17.py, main_oc20.py) to the “Model Architectures” defined in nets.
- How configurations (from md17/configs and oc20/configs) are loaded by these training programs.
- That training routines call utility functions (from engine.py, logger.py, etc.) and interact with external libraries like PyTorch, PyG, and e3nn (as noted in the acknowledgment section).
- For OC20 in particular, show additional components such as trainer modules (in oc20/trainer) that handle specialized training routines (like learning rate scheduling and weight decay adjustments).

##### Architectural Patterns and Design Principles
- The separation of data, model definitions, configurations, and training scripts suggests a modular design that facilitates testing and experimentation.
- Multi-experiment architecture: separate configurations and scripts for different tasks or settings (e.g., standard training vs. DeNS).
- That the project follows a “configuration over hardcoding” approach by using YAML config files to abstract hyperparameter settings.

##### Relevant Technologies and Frameworks
- PyTorch as the main deep learning framework.
- Dependencies like PyG (PyTorch Geometric), e3nn (for equivariant networks), and timm (PyTorch Image Models) which are referenced in the acknowledgments.
- External dataset specifications (like linking to OC20 data) and the use of environment files (env/env_equiformer.yml).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Data Sources and Preprocessing
    subgraph "Data Sources & Preprocessing"
        DS["Datasets Folder"]:::data
        PYG["PyG Data Directory"]:::data
        QM9_DS["QM9 Data Script"]:::data
        MD17_DS["MD17 Data Script"]:::data
    end

    %% Model Architectures (Nets)
    subgraph "Model Architectures"
        NETS["Nets"]:::nets
        DP["DP Attention Transformer"]:::nets
        GAT["Graph Attention Transformer"]:::nets
    end

    %% Training and Evaluation Pipelines
    subgraph "Training & Evaluation Pipelines"
        subgraph "QM9 Training"
            QM9_MAIN["main_qm9.py"]:::train
            QM9_SCRIPTS["QM9 Train Scripts"]:::train
        end
        subgraph "MD17 Training"
            MD17_MAIN["main_md17.py"]:::train
            MD17_DENS["main_md17_dens.py"]:::train
            MD17_SCRIPTS["MD17 Train Scripts"]:::train
        end
        subgraph "OC20 Training"
            OC20_MAIN["main_oc20.py"]:::train
            OC20_SCRIPTS["OC20 Train Scripts"]:::train
            OC20_TRAINER["OC20 Trainer Modules"]:::train
        end
    end

    %% Configuration and Utility Components
    subgraph "Configuration & Utility Components"
        MD17_CONFIG["MD17 Configs"]:::config
        MD17_EQ["EquiformerDens Configs"]:::config
        OC20_CONFIG["OC20 Configs"]:::config
        ENV_CONF["Env Config"]:::config
        UTIL["Utilities<br/>(engine.py, logger.py, optim_factory.py)"]:::config
    end

    %% External Dependencies
    EXT["External Libraries<br/>(PyTorch, PyG, e3nn, timm)"]:::external

    %% Relationships and Data Flow
    %% Data Sources to Training Scripts
    DS -->|"provides raw data"| QM9_SCRIPTS
    DS --> MD17_SCRIPTS
    PYG -->|"structured data"| QM9_DS
    PYG --> MD17_DS
    QM9_DS --> QM9_SCRIPTS
    MD17_DS --> MD17_SCRIPTS

    %% Training Pipeline internal flows
    QM9_SCRIPTS -->|"launches"| QM9_MAIN
    MD17_SCRIPTS -->|"launches"| MD17_MAIN
    MD17_SCRIPTS -->|"launches"| MD17_DENS
    OC20_SCRIPTS -->|"launches"| OC20_MAIN
    OC20_SCRIPTS -->|"incorporates"| OC20_TRAINER

    %% Training Scripts call Model Architectures and Configurations
    QM9_MAIN -->|"invokes"| NETS
    MD17_MAIN --> NETS
    MD17_DENS --> NETS
    OC20_MAIN --> NETS

    QM9_MAIN -->|"loads"| MD17_CONFIG
    MD17_MAIN --> MD17_CONFIG
    MD17_DENS --> MD17_EQ
    OC20_MAIN --> OC20_CONFIG
    OC20_MAIN --> ENV_CONF
    QM9_MAIN --> UTIL
    MD17_MAIN --> UTIL
    MD17_DENS --> UTIL
    OC20_MAIN --> UTIL

    %% External Libraries support both Training and Networks
    EXT --- NETS
    EXT --- QM9_MAIN
    EXT --- MD17_MAIN
    EXT --- MD17_DENS
    EXT --- OC20_MAIN

    %% Click Events for Data Sources and Preprocessing
    click DS "https://github.com/atomicarchitects/equiformer/tree/master/datasets"
    click PYG "https://github.com/atomicarchitects/equiformer/tree/master/datasets/pyg"
    click QM9_DS "https://github.com/atomicarchitects/equiformer/blob/master/datasets/pyg/qm9.py"
    click MD17_DS "https://github.com/atomicarchitects/equiformer/blob/master/datasets/pyg/md17.py"

    %% Click Events for Model Architectures
    click NETS "https://github.com/atomicarchitects/equiformer/tree/master/nets"
    click DP "https://github.com/atomicarchitects/equiformer/blob/master/nets/dp_attention_transformer.py"
    click GAT "https://github.com/atomicarchitects/equiformer/blob/master/nets/graph_attention_transformer.py"

    %% Click Events for Training and Evaluation Pipelines
    click QM9_MAIN "https://github.com/atomicarchitects/equiformer/blob/master/main_qm9.py"
    click QM9_SCRIPTS "https://github.com/atomicarchitects/equiformer/tree/master/scripts/train/qm9"
    click MD17_MAIN "https://github.com/atomicarchitects/equiformer/blob/master/main_md17.py"
    click MD17_DENS "https://github.com/atomicarchitects/equiformer/blob/master/main_md17_dens.py"
    click MD17_SCRIPTS "https://github.com/atomicarchitects/equiformer/tree/master/scripts/train/md17"
    click OC20_MAIN "https://github.com/atomicarchitects/equiformer/blob/master/main_oc20.py"
    click OC20_SCRIPTS "https://github.com/atomicarchitects/equiformer/tree/master/scripts/train/oc20"
    click OC20_TRAINER "https://github.com/atomicarchitects/equiformer/tree/master/oc20/trainer"

    %% Click Events for Configuration and Utility Components
    click MD17_CONFIG "https://github.com/atomicarchitects/equiformer/tree/master/md17/configs"
    click MD17_EQ "https://github.com/atomicarchitects/equiformer/tree/master/md17/configs/equiformer_dens"
    click OC20_CONFIG "https://github.com/atomicarchitects/equiformer/tree/master/oc20/configs"
    click ENV_CONF "https://github.com/atomicarchitects/equiformer/blob/master/env/env_equiformer.yml"
    click UTIL "https://github.com/atomicarchitects/equiformer/blob/master/engine.py"
    click UTIL "https://github.com/atomicarchitects/equiformer/blob/master/logger.py"
    click UTIL "https://github.com/atomicarchitects/equiformer/blob/master/optim_factory.py"

    %% Styles
    classDef data fill:#B3E5FC,stroke:#0277BD,stroke-width:2px;
    classDef nets fill:#C8E6C9,stroke:#2E7D32,stroke-width:2px;
    classDef train fill:#FFF9C4,stroke:#F9A825,stroke-width:2px;
    classDef config fill:#FFCCBC,stroke:#D84315,stroke-width:2px;
    classDef external fill:#E1BEE7,stroke:#6A1B9A,stroke-width:2px;
```
