# radical-ai/torch-sim architecture

> Architecture diagram of the GitHub repository radical-ai/torch-sim, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/radical-ai/torch-sim
- Repository: https://github.com/radical-ai/torch-sim

## Overview

The TorchSim project is an open‐source atomistic simulation engine built on PyTorch that provides accelerated simulation capabilities (including molecular dynamics, structural optimization, and Monte Carlo workflows) by integrating both machine learning potentials (e.g., MACE, Fairchem, SevenNet, ORB, MatterSim, graph-pes, and metatensor) and classical potential models (like Lennard-Jones, Morse, and soft-sphere). It also offers automatic batching, GPU memory management, and an easy-to-use high-level API, with additional integration points (ASE, pymatgen, phonopy) to ease practical usage.

##### Main Components
- Core Simulation Engine: Represent the torch_sim package as the central hub that holds modules for integrators, optimizers, math, IO, and trajectory handling. Indicate that it is built with PyTorch at its core.
- Model Modules: Include components under torch_sim/models (and their unbatched counterparts) which provide the various simulation models—both MLIP based (MACE, Fairchem, etc.) and classical potentials (Lennard Jones, Morse, soft-sphere).
- Integrators & Optimizers: Show integrators (e.g., those for MD such as NVE, NVT, NPT schemes, and relaxation optimizers like FIRE) and optimization routines as key parts of the simulation workflow.
- Autobatching & GPU Management: A dedicated component that handles automatic batching of multiple systems for GPU execution. This is a critical performance enhancement in TorchSim.
- Workflows: Represent the workflow modules (e.g., torch_sim/workflows, tests/workflows) that encapsulate higher-level APIs (like a2c and other workflow patterns) and reporting mechanisms.
- External Integrations & High-Level API: Illustrate components that interact with external libraries (ASE, pymatgen, phonopy) and provide user-friendly interfaces demonstrated in the quick-start examples.

##### Relationships and Interactions
- Dependency Flow: Indicate that different simulation models plug into the engine through a consistent interface (see the torch_sim/models/interface.py) and how different integrators call on physical system state changes.
- I/O and Reporting: Demonstrate how trajectory reporters and IO components interact with simulation state during and after simulation runs.
- Testing and Documentation: Optionally note that tests and docs (as seen in the tests/ and docs/ directories) help verify and explain the interactions; include a side note that continuous integration (GitHub workflows) supports quality assurance.

##### Important Architectural Patterns and Design Principles
- Modular Design: The project is broken into clearly segmented modules (models, integrators, optimizers, workflows), facilitating independent development, testing, and plug-and-play extensions.
- Extensibility & Interfaces: Emphasize the plugin-type architecture in the models (e.g., different machine learning potentials all following a common interface) so that new models can integrate seamlessly.
- Separation of Core and Unbatched Implementations: Note the existence of both batched (for performance and GPU acceleration) and unbatched modules, which may be represented as parallel subcomponents for similar functionalities.
- Integration with Pytorch: Underline that all numerical operations leverage PyTorch primitives to enable GPU acceleration and automatic differentiation.

b. Branch out from the core to smaller components:
- “Models”: Containing MLIP (MACE, Fairchem, etc.) and classical potentials.
- “Integrators & Optimizers”: Managing MD integration schemes and optimization routines (FIRE, gradient descent, etc.).
- “Autobatching & GPU Manager”: Handling batching of multiple simulation systems.
- “I/O & Trajectory Manager”: Overseeing trajectory writing and state extraction.
c. “High-Level API” (with a note referring to the examples and tutorials) to the core engine showing that it receives user input and delivers simulation results.
e. A side node for “Workflows”, linking to both the core engine and the High-Level API (illustrating the specialized workflows like a2c, elastic, etc.)

##### Final Touches
- Components are labeled clearly.

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "TorchSim Core Engine"
        Core["TorchSim Core Engine (torch_sim)"]:::core
    end

    subgraph "Models"
        MLIP["MLIP & Classical Potentials"]:::models
        Unbatched["Unbatched Models"]:::models
    end

    subgraph "Integrators & Optimizers"
        IntB["Integrators (Batched)"]:::integrators
        OptB["Optimizers (Batched)"]:::integrators
        IntU["Integrators (Unbatched)"]:::integrators
        OptU["Optimizers (Unbatched)"]:::integrators
    end

    subgraph "Autobatching & GPU Manager"
        Auto["Autobatching & GPU Manager"]:::gpu
    end

    subgraph "I/O & Trajectory Manager"
        IO["I/O Module"]:::io
        Traj["Trajectory Module"]:::io
    end

    subgraph "High-Level API & Workflows"
        API["High-Level API & Workflows"]:::api
    end

    subgraph "External Integrations"
        Ext["External Integrations (ASE, pymatgen, phonopy)"]:::external
    end

    subgraph "Testing & Documentation"
        QA["Testing"]:::qa
        Doc["Documentation"]:::qa
    end

    API -->|"calls"| Core
    Core -->|"uses"| MLIP
    Core -->|"uses"| Unbatched
    Core -->|"calls"| IntB
    Core -->|"calls"| OptB
    Core -->|"calls"| IntU
    Core -->|"calls"| OptU
    Core -->|"manages"| Auto
    Core -->|"triggers"| IO
    Core -->|"triggers"| Traj
    API -->|"interfaces"| Ext
    QA ---|"validates"| Core
    QA ---|"validates"| IntB
    QA ---|"validates"| IntU
    Doc ---|"supports"| API

    click Core "https://github.com/radical-ai/torch-sim/tree/main/torch_sim/"
    click MLIP "https://github.com/radical-ai/torch-sim/tree/main/torch_sim/models/"
    click Unbatched "https://github.com/radical-ai/torch-sim/tree/main/torch_sim/unbatched/models/"
    click IntB "https://github.com/radical-ai/torch-sim/blob/main/torch_sim/integrators.py"
    click OptB "https://github.com/radical-ai/torch-sim/blob/main/torch_sim/optimizers.py"
    click IntU "https://github.com/radical-ai/torch-sim/blob/main/torch_sim/unbatched/unbatched_integrators.py"
    click OptU "https://github.com/radical-ai/torch-sim/blob/main/torch_sim/unbatched/unbatched_optimizers.py"
    click Auto "https://github.com/radical-ai/torch-sim/blob/main/torch_sim/autobatching.py"
    click IO "https://github.com/radical-ai/torch-sim/blob/main/torch_sim/io.py"
    click Traj "https://github.com/radical-ai/torch-sim/blob/main/torch_sim/trajectory.py"
    click API "https://github.com/radical-ai/torch-sim/tree/main/torch_sim/workflows/"
    click Ext "https://github.com/radical-ai/torch-sim/tree/main/examples/"
    click QA "https://github.com/radical-ai/torch-sim/tree/main/tests/"
    click Doc "https://github.com/radical-ai/torch-sim/tree/main/docs/"

    classDef core fill:#FFD700,stroke:#333,stroke-width:2px
    classDef models fill:#ADD8E6,stroke:#333,stroke-width:2px
    classDef integrators fill:#90EE90,stroke:#333,stroke-width:2px
    classDef gpu fill:#FFB6C1,stroke:#333,stroke-width:2px
    classDef io fill:#87CEFA,stroke:#333,stroke-width:2px
    classDef api fill:#FFE4B5,stroke:#333,stroke-width:2px
    classDef external fill:#FF9999,stroke:#333,stroke-width:2px
    classDef qa fill:#D3D3D3,stroke:#333,stroke-width:2px
```
