# jla-gardner/graph-pes architecture

> Architecture diagram of the GitHub repository jla-gardner/graph-pes, 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/jla-gardner/graph-pes
- Repository: https://github.com/jla-gardner/graph-pes

## Overview

##### Overall Project Purpose and Type
- This project is a framework for building machine-learned potential energy surface (PES) models that use graph representations of atomic structures. It is clearly designed for scientific machine learning and simulation, with components for model development, training, and integration with molecular dynamics tools like LAMMPS and ASE.
- The framework supports multiple architectural options (e.g., SchNet, NequIP, PaiNN, MACE, TensorNet) and provides a CLI (graph-pes-train) for configuring and running training sessions.

##### Primary Components
- Configuration & Input:
– Include the configs directory (with various YAML files for minimal, realistic, and kitchen sink configurations).
– Represent external user inputs via configuration files, which feed into the CLI.

- CLI Interface & Command Execution:
– Display the “graph-pes-train” CLI command (and associated scripts in src/graph_pes/scripts) which serves as the primary entry point for training and model execution.
– Illustrate its role in reading configuration files and triggering the downstream processes.

- Data Handling & Loading:
– Show the “data” module in both src/graph_pes/data and docs sections describing dataset handling.
– Include components for reading atomic structure graphs, dataset preparations, and integration with ASE databases.

- Model Architecture and Components:
– Identify the model core components in src/graph_pes/models, where different many-body models (SchNet, NequIP, PaiNN, MACE, TensorNet) and helper modules (like aggregation, distances, scaling) are defined.
– Highlight that models are built by extending a common base (GraphPESModel) and can be interchanged or extended.

- Training Engine:
– Include the training directory (src/graph_pes/training) showing callbacks, loss functions, optimizers, and training task orchestration.
– Illustrate integration with external libraries like TorchScript for model deployment and distributed training support (via files like distributed.py in utils).

- External Simulation & Interfaces:
– Represent the “interfaces” directory that contains integration modules (e.g., for MACE and MatterSim) along with the “pair_style” integration for LAMMPS.

- Utilities & Supporting Tools:
– Note the “utils” directory with analysis, logging, and miscellaneous helper functions.
– Also include scripts in the “scripts” directory for operations like building LAMMPS, training, testing, etc.

- Testing & Documentation:
– Mention the docs directory as a resource for further understanding of the architecture and usage scenarios.

##### Relationships and Data Flows
- Interaction between the training engine and model components—where data from the loader module is processed by the models, and loss/optimizers in the training module update model parameters.
- Interface points where simulations (via LAMMPS/ASE) make calls to the trained models using the pair_style implementation.
- That logging utilities and distributed training support are cross-cutting concerns, interfacing with both the training engine and model evaluation layers.

##### Architectural Patterns and Technologies
- That the framework is modular, making heavy use of object-oriented design (e.g., inheriting from a base model class) which supports extensibility.
- Use of configuration-driven training (YAML config files) and a CLI that orchestrates various modules.
- Specify touchpoints with torch.jit (TorchScript) for model deployment, which is relevant for performance-critical environments.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Configuration & Input
    subgraph "Configuration & Input"
        A("Configuration: YAML Files"):::config
        B("Configuration Modules"):::config
    end

    %% CLI Interface & Command Execution
    subgraph "CLI Interface"
        C("CLI Interface: graph-pes-train"):::cli
        D("CLI Entry Script"):::cli
    end

    %% Data Handling & Loading
    subgraph "Data Handling & Loading"
        E("Data Loader & Handling"):::data
    end

    %% Model Architecture and Components
    subgraph "Model Architecture"
        F("Model Core & Components"):::model
        G("Extended Models (E3NN)"):::model
    end

    %% Training Engine
    subgraph "Training Engine"
        H("Training Engine"):::training
    end

    %% External Simulation & Interfaces
    subgraph "External Simulation"
        I("External Interfaces"):::external
        J("Pair Style Integration"):::external
    end

    %% Utilities & Supporting Tools
    subgraph "Utilities & Supporting Tools"
        K("Utilities & Scripts"):::utils
    end

    %% Testing & Documentation
    subgraph "Testing & Documentation"
        L("Testing Suite"):::testing
        M("Documentation Resources"):::docs
    end

    %% Data Flow Connections
    A -->|"feeds"| C
    B -->|"feeds"| C
    C -->|"initiates"| D
    D -->|"triggers"| E
    E -->|"processes data for"| F
    F -->|"integrates with"| G
    G -->|"passed to"| H
    H -->|"calls"| I
    H -->|"calls"| J

    %% Cross-cutting Utilities
    K -.->|"supports"| E
    K -.->|"supports"| F
    K -.->|"supports"| H

    %% Documentation Links
    E -.->|"docs"| M
    F -.->|"docs"| M
    H -.->|"docs"| M
    I -.->|"docs"| M
    J -.->|"docs"| M

    %% Testing integration
    L -->|"verifies"| H
    L -->|"verifies"| I

    %% Click Events
    click A "https://github.com/jla-gardner/graph-pes/tree/main/configs"
    click B "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/config"
    click C "https://github.com/jla-gardner/graph-pes/tree/main/docs/source/cli/graph-pes-train"
    click D "https://github.com/jla-gardner/graph-pes/blob/main/src/graph_pes/scripts/train.py"
    click E "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/data"
    click F "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/models"
    click G "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/models/e3nn"
    click H "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/training"
    click I "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/interfaces"
    click J "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/pair_style"
    click K "https://github.com/jla-gardner/graph-pes/tree/main/src/graph_pes/utils"
    click L "https://github.com/jla-gardner/graph-pes/tree/main/tests"
    click M "https://github.com/jla-gardner/graph-pes/tree/main/docs"

    %% Styles
    classDef config fill:#FFCDD2,stroke:#E57373,stroke-width:2px;
    classDef cli fill:#BBDEFB,stroke:#64B5F6,stroke-width:2px;
    classDef data fill:#FFF9C4,stroke:#FBC02D,stroke-width:2px;
    classDef model fill:#C8E6C9,stroke:#81C784,stroke-width:2px;
    classDef training fill:#FFE0B2,stroke:#FFB74D,stroke-width:2px;
    classDef external fill:#E1BEE7,stroke:#BA68C8,stroke-width:2px;
    classDef utils fill:#D7CCC8,stroke:#8D6E63,stroke-width:2px;
    classDef testing fill:#CFD8DC,stroke:#90A4AE,stroke-width:2px;
    classDef docs fill:#F0F4C3,stroke:#DCE775,stroke-width:2px;
```
