# orbital-materials/orb-models architecture

> Architecture diagram of the GitHub repository orbital-materials/orb-models, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/orbital-materials/orb-models
- Repository: https://github.com/orbital-materials/orb-models

## Overview

##### Project Type and Purpose
- This is an open-source Python library (“orb-models”) providing pretrained neural network potentials for atomic simulations (energies, forces, stresses).
- It integrates with ASE (Atomic Simulation Environment) and PyTorch to build graph representations of atomic systems, load/compile pretrained models, run inference, and optionally fine-tune on new datasets.

##### High-Level Components
a. Library Code (orb_models package)
- dataset: wrappers around ASE SQLite databases and data augmentations
- forcefield: core ML components (graph regressor, conservative/direct models, featurizers, embedding, pairwise terms, loss functions)
– atomic_system: functions to convert ASE Atoms ↔ AtomGraphs
– calculator: ASE calculator interface (ORBCalculator)
– pretrained: model factory functions that load/compile pretrained v2/v3 models
- utils: shared utilities (IO, common tensor ops)
b. Entry-Points & Scripts
- finetune.py: CLI for fine-tuning pretrained models on custom ASE databases
- examples/ & aws, azure/: demonstration notebooks and input files
c. Configuration & Deployment
- pyproject.toml, Dockerfile: packaging and containerization
- CI workflows (.github/workflows): test & publish pipelines
d. Tests
- tests/: unit tests covering atomgraphs, forcefield modules, model back-compatibility

##### Component Interactions & Data Flow
1. User code (e.g. examples or external scripts) imports orb_models.forcefield.pretrained → selects a model variant → backend loads PyTorch weights and compiles the model
2. AtomicSystem builder (orb_models.forcefield.atomic_system) takes an ASE Atoms object, along with system_config (cutoffs, periodicity) → produces a message-passing graph representation on CPU/GPU; optionally accelerated by cuML for neighbor graph creation
3. The graph is batched (orb_models.forcefield.base.batch_graphs) and fed into the model’s .predict() method → outputs energy, force, stress tensors
4. If using ORBCalculator, the same graph-building + inference pipeline is wrapped in ASE’s calculator API, so standard ASE workflows (optimization, MD) can be performed
5. finetune.py reuses dataset modules to load a custom ASE SQLite DB → constructs DataLoader → trains a model variant via PyTorch, saving checkpoints in ckpts/

##### Architectural Patterns & Design Principles
- Modular Python package: clear separation between data ingestion, graph construction, model architecture, inference, and ASE integration
- Factory functions for pretrained models ensure decoupling of model configuration (v2 vs v3, direct vs conservative) from inference code
- Pluggable backend acceleration: pure-Python graph builder with optional cuML integration for GPU speedups
- Scriptable CLI for extensibility (fine-tuning)
- CI/CD pipelines enforce code quality, testing, and publishing to PyPI

## Diagram (Mermaid)

```mermaid
flowchart TB
  %% Input Data
  ASEAtoms["ASE Atoms"]:::data
  SQLiteDB["ASE SQLite DB"]:::data

  %% orb_models package
  subgraph "orb_models"
    subgraph "dataset" 
      A1["ase_sqlite_dataset.py"]:::data
      A2["augmentations.py"]:::data
      A3["base_datasets.py"]:::data
    end
    subgraph "forcefield"
      B1["atomic_system.py"]:::compute
      B2["base.py (batch_graphs)"]:::compute
      subgraph "featurization & embedding"
        C1["embedding.py"]:::compute
        C2["featurization_utilities.py"]:::compute
        C3["property_definitions.py"]:::compute
        C4["rbf.py"]:::compute
        C5["segment_ops.py"]:::compute
      end
      subgraph "pairwise terms"
        D1["pair_repulsion.py"]:::compute
        D2["angular.py"]:::compute
      end
      E1["loss.py"]:::compute
      subgraph "model heads & utils"
        F1["forcefield_heads.py"]:::compute
        F2["forcefield_utils.py"]:::compute
        F3["nn_util.py"]:::compute
      end
      G1["gns.py"]:::compute
      H1["conservative_regressor.py"]:::compute
      H2["direct_regressor.py"]:::compute
      I1["pretrained.py"]:::compute
      J1["calculator.py"]:::interface
    end
    U1["utils.py"]:::compute
  end

  %% Entry points and Scripts
  Finetune["finetune.py"]:::interface
  Examples["examples/ & notebooks"]:::external

  %% Packaging & Deployment
  Docker["Dockerfile"]:::external
  Pyproject["pyproject.toml"]:::external
  CI1[".github/workflows/test.yml"]:::external
  CI2[".github/workflows/publish.yml"]:::external
  PyPI["PyPI Publish"]:::external
  GitHubActions["GitHub Actions"]:::external

  %% Simulation Workflow
  Simulation["ASE Simulation\n(Optimizer/MD)"]:::external

  %% Data Flow
  ASEAtoms --> B1
  B1 --> B2
  B2 --> G1
  I1 --> G1
  G1 --> F1
  F1 --> Outputs["Energy, Forces, Stress"]:::compute
  Outputs --> J1
  J1 --> Simulation

  SQLiteDB --> A1
  A1 --> Finetune
  Finetune --> G1
  Finetune --> CKPTS["Checkpoints"]:::data

  Examples --> ASEAtoms
  Examples --> Finetune

  %% Packaging & CI
  Docker --> Simulation
  Pyproject --> Docker
  CI1 --> Pyproject
  CI2 --> Pyproject
  CI1 --> GitHubActions
  CI2 --> GitHubActions
  GitHubActions --> PyPI

  %% Click Events
  click A1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/dataset/ase_sqlite_dataset.py"
  click A2 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/dataset/augmentations.py"
  click A3 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/dataset/base_datasets.py"
  click B1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/atomic_system.py"
  click B2 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/base.py"
  click C1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/embedding.py"
  click C2 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/featurization_utilities.py"
  click C3 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/property_definitions.py"
  click C4 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/rbf.py"
  click C5 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/segment_ops.py"
  click D1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/pair_repulsion.py"
  click D2 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/angular.py"
  click E1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/loss.py"
  click F1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/forcefield_heads.py"
  click F2 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/forcefield_utils.py"
  click F3 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/nn_util.py"
  click G1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/gns.py"
  click H1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/conservative_regressor.py"
  click H2 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/direct_regressor.py"
  click I1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/pretrained.py"
  click J1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/forcefield/calculator.py"
  click U1 "https://github.com/orbital-materials/orb-models/blob/main/orb_models/utils.py"
  click Finetune "https://github.com/orbital-materials/orb-models/blob/main/finetune.py"
  click Examples "https://github.com/orbital-materials/orb-models/tree/main/examples/"
  click Docker "https://github.com/orbital-materials/orb-models/tree/main/Dockerfile"
  click Pyproject "https://github.com/orbital-materials/orb-models/blob/main/pyproject.toml"
  click CI1 "https://github.com/orbital-materials/orb-models/blob/main/.github/workflows/test.yml"
  click CI2 "https://github.com/orbital-materials/orb-models/blob/main/.github/workflows/publish.yml"

  %% Styles
  classDef data fill:#bbdefb,stroke:#1e88e5,color:#0d47a1
  classDef compute fill:#c8e6c9,stroke:#2e7d32,color:#1b5e20
  classDef interface fill:#ffe0b2,stroke:#ef6c00,color:#e65100
  classDef external fill:#e0e0e0,stroke:#757575,color:#424242
  class ASEAtoms,SQLiteDB,CKPTS data
  class Outputs compute
  class Simulation,Examples,Docker,Pyproject,CI1,CI2,PyPI,GitHubActions external
```
