# autoatml/autoplex architecture

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

- Interactive diagram: https://gitdiagram.com/autoatml/autoplex
- Repository: https://github.com/autoatml/autoplex

## Overview

Autoplex automates construction and benchmarking of machine-learning interatomic potentials. Users configure and launch either random-structure-search (RSS) or phonon workflows; these orchestrate structure generation or phonon data production, reference calculations, data preparation, and potential fitting. The fitting layer supports multiple MLIP families, with shared configuration and regularization. The README documents these workflow capabilities; some subsystem links below rely on the SOURCE INDEX rather than inspected implementations, so those links are marked unverified.

Main entry points: [`src/autoplex/auto/rss/jobs.py`](https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/rss/jobs.py) (RSS iteration jobs), [`src/autoplex/fitting/common/flows.py`](https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/common/flows.py) (Fitting workflows), [`src/autoplex/auto/phonons/flows.py`](https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/phonons/flows.py) (Phonon workflows), [`src/autoplex/data/common/jobs.py`](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/common/jobs.py) (Data collection)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_orchestration["Workflow orchestration"]
  node_rss_flow["RSS workflows<br/>[flows.py]"]
  node_rss_jobs["RSS iteration jobs<br/>[jobs.py]"]
  node_phonon_flow["Phonon workflows<br/>[flows.py]"]
  node_phonon_jobs["Phonon workflow jobs<br/>[jobs.py]"]
end

subgraph group_data["Training data"]
  node_rss_generation["RSS structure generation<br/>[jobs.py]"]
  node_rss_data["RSS data jobs<br/>[flows.py]"]
  node_rss_data_jobs["RSS data processing<br/>[jobs.py]"]
  node_phonon_data["Phonon data flows<br/>[flows.py]"]
  node_phonon_data_jobs["Phonon data jobs<br/>[jobs.py]"]
  node_common_data["Shared data flows<br/>[flows.py]"]
  node_common_data_jobs["Data collection<br/>[jobs.py]"]
  node_nmr_data["NMR data jobs<br/>[jobs.py]"]
end

subgraph group_fitting["Potential fitting"]
  node_fit_flow["Fitting workflows<br/>[flows.py]"]
  node_fit_jobs["MLIP fitting<br/>[jobs.py]"]
  node_regularization["Data regularization<br/>[regularization.py]"]
  node_mlip_configs["MLIP hyperparameters<br/>[_gap_hypers.py]"]
end

subgraph group_compute["Compute integration"]
  node_settings["Workflow settings<br/>[settings.py]"]
  node_castep_jobs["CASTEP jobs<br/>[jobs.py]"]
  node_castep_flow["CASTEP flows<br/>[flows.py]"]
end

node_researcher(("Researcher"))

node_researcher -->|"configures and launches"| node_rss_flow
node_researcher -->|"configures and launches"| node_phonon_flow
node_rss_flow -->|"dispatches"| node_rss_jobs
node_rss_jobs -->|"generates structures"| node_rss_generation
node_rss_jobs -->|"collects data"| node_rss_data
node_rss_data -.->|"uses data jobs"| node_rss_data_jobs
node_rss_jobs -->|"requests fitting"| node_fit_flow
node_phonon_flow -->|"dispatches"| node_phonon_jobs
node_phonon_flow -->|"requests data generation"| node_phonon_data
node_phonon_data -->|"uses phonon jobs"| node_phonon_data_jobs
node_phonon_data -->|"uses shared jobs"| node_common_data_jobs
node_phonon_flow -->|"requests fitting"| node_fit_flow
node_common_data -->|"dispatches"| node_common_data_jobs
node_common_data_jobs -->|"uses regularization"| node_regularization
node_nmr_data -->|"uses shared jobs"| node_common_data_jobs
node_fit_flow -->|"dispatches fitting"| node_fit_jobs
node_fit_flow -->|"applies regularization"| node_regularization
node_fit_flow -.->|"selects hyperparameters"| node_mlip_configs
node_fit_jobs -->|"loads model settings"| node_mlip_configs
node_rss_flow -->|"reads settings"| node_settings
node_castep_flow -->|"dispatches jobs"| node_castep_jobs
node_rss_jobs -->|"uses CASTEP jobs"| node_castep_jobs
node_castep_jobs -->|"reads configuration"| node_settings

click node_rss_flow "https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/rss/flows.py"
click node_rss_jobs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/rss/jobs.py"
click node_phonon_flow "https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/phonons/flows.py"
click node_phonon_jobs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/phonons/jobs.py"
click node_rss_generation "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/rss/jobs.py"
click node_rss_data "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/rss/flows.py"
click node_rss_data_jobs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/rss/jobs.py"
click node_phonon_data "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/phonons/flows.py"
click node_phonon_data_jobs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/phonons/jobs.py"
click node_common_data "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/common/flows.py"
click node_common_data_jobs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/common/jobs.py"
click node_nmr_data "https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/nmr/jobs.py"
click node_fit_flow "https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/common/flows.py"
click node_fit_jobs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/common/jobs.py"
click node_regularization "https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/common/regularization.py"
click node_mlip_configs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/mlip_hypers/_gap_hypers.py"
click node_settings "https://github.com/autoatml/autoplex/blob/main/src/autoplex/settings.py"
click node_castep_jobs "https://github.com/autoatml/autoplex/blob/main/src/autoplex/misc/castep/jobs.py"
click node_castep_flow "https://github.com/autoatml/autoplex/blob/main/src/autoplex/misc/castep/flows.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_rss_flow,node_rss_jobs,node_phonon_flow,node_phonon_jobs toneBlue
class node_rss_generation,node_rss_data,node_rss_data_jobs,node_phonon_data,node_phonon_data_jobs,node_common_data,node_common_data_jobs,node_nmr_data toneAmber
class node_fit_flow,node_fit_jobs,node_regularization,node_mlip_configs toneMint
class node_settings,node_castep_jobs,node_castep_flow toneRose
class node_researcher toneIndigo
```

## Components

### Workflow orchestration

- [RSS workflows](https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/rss/flows.py): `src/autoplex/auto/rss/flows.py`
- [RSS iteration jobs](https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/rss/jobs.py): `src/autoplex/auto/rss/jobs.py`
- [Phonon workflows](https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/phonons/flows.py): `src/autoplex/auto/phonons/flows.py`
- [Phonon workflow jobs](https://github.com/autoatml/autoplex/blob/main/src/autoplex/auto/phonons/jobs.py): `src/autoplex/auto/phonons/jobs.py`

### Training data

- [RSS structure generation](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/rss/jobs.py): `src/autoplex/data/rss/jobs.py`
- [RSS data jobs](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/rss/flows.py): `src/autoplex/data/rss/flows.py`
- [RSS data processing](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/rss/jobs.py): `src/autoplex/data/rss/jobs.py`
- [Phonon data flows](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/phonons/flows.py): `src/autoplex/data/phonons/flows.py`
- [Phonon data jobs](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/phonons/jobs.py): `src/autoplex/data/phonons/jobs.py`
- [Shared data flows](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/common/flows.py): `src/autoplex/data/common/flows.py`
- [Data collection](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/common/jobs.py): `src/autoplex/data/common/jobs.py`
- [NMR data jobs](https://github.com/autoatml/autoplex/blob/main/src/autoplex/data/nmr/jobs.py): `src/autoplex/data/nmr/jobs.py`

### Potential fitting

- [Fitting workflows](https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/common/flows.py): `src/autoplex/fitting/common/flows.py`
- [MLIP fitting](https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/common/jobs.py): `src/autoplex/fitting/common/jobs.py`
- [Data regularization](https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/common/regularization.py): `src/autoplex/fitting/common/regularization.py`
- [MLIP hyperparameters](https://github.com/autoatml/autoplex/blob/main/src/autoplex/fitting/mlip_hypers/_gap_hypers.py): `src/autoplex/fitting/mlip_hypers/_gap_hypers.py`

### Compute integration

- [Workflow settings](https://github.com/autoatml/autoplex/blob/main/src/autoplex/settings.py): `src/autoplex/settings.py`
- [CASTEP jobs](https://github.com/autoatml/autoplex/blob/main/src/autoplex/misc/castep/jobs.py): `src/autoplex/misc/castep/jobs.py`
- [CASTEP flows](https://github.com/autoatml/autoplex/blob/main/src/autoplex/misc/castep/flows.py): `src/autoplex/misc/castep/flows.py`

### Other components

- **Researcher**

## Connections

- Researcher → RSS workflows: configures and launches
- Researcher → Phonon workflows: configures and launches
- RSS workflows → RSS iteration jobs: dispatches (evidence: `src/autoplex/auto/rss/flows.py`)
- RSS iteration jobs → RSS structure generation: generates structures (evidence: `src/autoplex/auto/rss/jobs.py`)
- RSS iteration jobs → RSS data jobs: collects data (evidence: `src/autoplex/auto/rss/jobs.py`)
- RSS data jobs → RSS data processing: uses data jobs (evidence: `src/autoplex/data/rss/flows.py`)
- RSS iteration jobs → Fitting workflows: requests fitting (evidence: `src/autoplex/auto/rss/jobs.py`)
- Phonon workflows → Phonon workflow jobs: dispatches (evidence: `src/autoplex/auto/phonons/flows.py`)
- Phonon workflows → Phonon data flows: requests data generation (evidence: `src/autoplex/auto/phonons/flows.py`)
- Phonon data flows → Phonon data jobs: uses phonon jobs (evidence: `src/autoplex/data/phonons/flows.py`)
- Phonon data flows → Data collection: uses shared jobs (evidence: `src/autoplex/data/phonons/flows.py`)
- Phonon workflows → Fitting workflows: requests fitting (evidence: `src/autoplex/auto/phonons/flows.py`)
- Shared data flows → Data collection: dispatches (evidence: `src/autoplex/data/common/flows.py`)
- Data collection → Data regularization: uses regularization (evidence: `src/autoplex/data/common/jobs.py`)
- NMR data jobs → Data collection: uses shared jobs (evidence: `src/autoplex/data/nmr/jobs.py`)
- Fitting workflows → MLIP fitting: dispatches fitting (evidence: `src/autoplex/fitting/common/flows.py`)
- Fitting workflows → Data regularization: applies regularization (evidence: `src/autoplex/fitting/common/flows.py`)
- Fitting workflows → MLIP hyperparameters: selects hyperparameters
- MLIP fitting → MLIP hyperparameters: loads model settings (evidence: `src/autoplex/fitting/common/jobs.py`)
- RSS workflows → Workflow settings: reads settings (evidence: `src/autoplex/auto/rss/flows.py`)
- CASTEP flows → CASTEP jobs: dispatches jobs (evidence: `src/autoplex/misc/castep/flows.py`)
- RSS iteration jobs → CASTEP jobs: uses CASTEP jobs (evidence: `src/autoplex/auto/rss/jobs.py`)
- CASTEP jobs → Workflow settings: reads configuration (evidence: `src/autoplex/misc/castep/jobs.py`)
