# acesuit/mace architecture

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

- Interactive diagram: https://gitdiagram.com/acesuit/mace
- Repository: https://github.com/acesuit/mace

## Overview

MACE is a PyTorch implementation of equivariant machine-learning interatomic potentials. Its main workflow turns atomistic configurations into graph data, trains a model, and exposes predictions through calculators for simulation or evaluation. The repository also includes foundation-model fine-tuning, polar and magnetic model capabilities, dataset preprocessing, and model conversion utilities. The graph emphasizes documented capabilities and relationships visible in the README or source index; several runtime details are unsampled, so uncertain links are omitted or marked unverified.

Main entry points: [`mace/cli/run_train.py`](https://github.com/acesuit/mace/blob/develop/mace/cli/run_train.py) (Training CLI), [`mace/modules/blocks.py`](https://github.com/acesuit/mace/blob/develop/mace/modules/blocks.py) (Equivariant blocks), [`mace/data/atomic_data.py`](https://github.com/acesuit/mace/blob/develop/mace/data/atomic_data.py) (Atomic graph data), [`mace/tools/train.py`](https://github.com/acesuit/mace/blob/develop/mace/tools/train.py) (Training engine)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_data["Atomistic data"]
  node_preprocess["Data preprocessing<br/>[preprocess_data.py]"]
  node_atomic_data["Atomic graph data<br/>[atomic_data.py]"]
  node_neighborhood["Neighbor construction<br/>[neighborhood.py]"]
  node_graph_types["Graph batch types<br/>[data.py]"]
  node_hdf5["HDF5 dataset<br/>[hdf5_dataset.py]"]
  node_lmdb["LMDB dataset<br/>[lmdb_dataset.py]"]
end

subgraph group_model["Potential models"]
  node_model_blocks["Equivariant blocks<br/>[blocks.py]"]
  node_radial["Radial features<br/>[radial.py]"]
  node_extensions["Specialized models<br/>[extensions.py]"]
  node_loss["Training losses<br/>[loss.py]"]
end

subgraph group_train["Training and analysis"]
  node_train_cli["Training CLI<br/>[run_train.py]"]
  node_trainer["Training engine<br/>[train.py]"]
  node_fine_tune["Fine-tuning selection"]
  node_evaluation["Configuration evaluation<br/>[eval_configs.py]"]
end

subgraph group_inference["Inference and simulation"]
  node_foundation["Foundation models"]
  node_calculator["ASE calculator<br/>[mace.py]"]
  node_lammps["LAMMPS integration<br/>[lammps_mace.py]"]
  node_active_md["Active-learning MD"]
end

subgraph group_tools["Model utilities"]
  node_conversion["Equivariance conversion"]
  node_wrapper_ops["Backend operations<br/>[wrapper_ops.py]"]
  node_scatter["Scatter operations<br/>[scatter.py]"]
end

node_user(("MACE user"))
node_simulation(("Simulation user"))

node_user -->|"starts training"| node_train_cli
node_user -.->|"prepares data"| node_preprocess
node_train_cli -->|"uses data types"| node_atomic_data
node_atomic_data -->|"builds neighbors"| node_neighborhood
node_atomic_data -->|"creates graph data"| node_graph_types
node_train_cli -.->|"loads dataset"| node_hdf5
node_train_cli -.->|"loads dataset"| node_lmdb
node_model_blocks -->|"uses radial features"| node_radial
node_extensions -->|"uses blocks"| node_model_blocks
node_train_cli -.->|"runs training"| node_trainer
node_trainer -.->|"computes loss"| node_loss
node_user -->|"uses pretrained models"| node_foundation
node_foundation -->|"wraps calculator"| node_calculator
node_simulation -.->|"requests predictions"| node_calculator
node_simulation -.->|"runs simulations"| node_lammps
node_user -->|"selects fine-tuning"| node_fine_tune
node_user -.->|"evaluates configurations"| node_evaluation
node_user -.->|"runs active MD"| node_active_md
node_user -.->|"converts models"| node_conversion
node_conversion -->|"configures backend"| node_wrapper_ops
node_model_blocks -->|"uses operations"| node_wrapper_ops
node_model_blocks -->|"aggregates messages"| node_scatter

click node_train_cli "https://github.com/acesuit/mace/blob/develop/mace/cli/run_train.py"
click node_preprocess "https://github.com/acesuit/mace/blob/develop/mace/cli/preprocess_data.py"
click node_atomic_data "https://github.com/acesuit/mace/blob/develop/mace/data/atomic_data.py"
click node_neighborhood "https://github.com/acesuit/mace/blob/develop/mace/data/neighborhood.py"
click node_graph_types "https://github.com/acesuit/mace/blob/develop/mace/tools/torch_geometric/data.py"
click node_hdf5 "https://github.com/acesuit/mace/blob/develop/mace/data/hdf5_dataset.py"
click node_lmdb "https://github.com/acesuit/mace/blob/develop/mace/data/lmdb_dataset.py"
click node_model_blocks "https://github.com/acesuit/mace/blob/develop/mace/modules/blocks.py"
click node_radial "https://github.com/acesuit/mace/blob/develop/mace/modules/radial.py"
click node_extensions "https://github.com/acesuit/mace/blob/develop/mace/modules/extensions.py"
click node_loss "https://github.com/acesuit/mace/blob/develop/mace/modules/loss.py"
click node_trainer "https://github.com/acesuit/mace/blob/develop/mace/tools/train.py"
click node_foundation "https://github.com/acesuit/mace/blob/develop/mace/calculators/foundations_models.py"
click node_calculator "https://github.com/acesuit/mace/blob/develop/mace/calculators/mace.py"
click node_lammps "https://github.com/acesuit/mace/blob/develop/mace/calculators/lammps_mace.py"
click node_active_md "https://github.com/acesuit/mace/blob/develop/mace/cli/active_learning_md.py"
click node_fine_tune "https://github.com/acesuit/mace/blob/develop/mace/cli/fine_tuning_select.py"
click node_evaluation "https://github.com/acesuit/mace/blob/develop/mace/cli/eval_configs.py"
click node_conversion "https://github.com/acesuit/mace/blob/develop/mace/cli/convert_e3nn_cueq.py"
click node_wrapper_ops "https://github.com/acesuit/mace/blob/develop/mace/modules/wrapper_ops.py"
click node_scatter "https://github.com/acesuit/mace/blob/develop/mace/tools/scatter.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_preprocess,node_atomic_data,node_neighborhood,node_graph_types,node_hdf5,node_lmdb,node_user,node_simulation toneBlue
class node_model_blocks,node_radial,node_extensions,node_loss toneAmber
class node_train_cli,node_trainer,node_fine_tune,node_evaluation toneMint
class node_foundation,node_calculator,node_lammps,node_active_md toneRose
class node_conversion,node_wrapper_ops,node_scatter toneIndigo
```

## Components

### Atomistic data

- [Data preprocessing](https://github.com/acesuit/mace/blob/develop/mace/cli/preprocess_data.py): `mace/cli/preprocess_data.py`
- [Atomic graph data](https://github.com/acesuit/mace/blob/develop/mace/data/atomic_data.py): `mace/data/atomic_data.py`
- [Neighbor construction](https://github.com/acesuit/mace/blob/develop/mace/data/neighborhood.py): `mace/data/neighborhood.py`
- [Graph batch types](https://github.com/acesuit/mace/blob/develop/mace/tools/torch_geometric/data.py): `mace/tools/torch_geometric/data.py`
- [HDF5 dataset](https://github.com/acesuit/mace/blob/develop/mace/data/hdf5_dataset.py): `mace/data/hdf5_dataset.py`
- [LMDB dataset](https://github.com/acesuit/mace/blob/develop/mace/data/lmdb_dataset.py): `mace/data/lmdb_dataset.py`

### Potential models

- [Equivariant blocks](https://github.com/acesuit/mace/blob/develop/mace/modules/blocks.py): `mace/modules/blocks.py`
- [Radial features](https://github.com/acesuit/mace/blob/develop/mace/modules/radial.py): `mace/modules/radial.py`
- [Specialized models](https://github.com/acesuit/mace/blob/develop/mace/modules/extensions.py): `mace/modules/extensions.py`
- [Training losses](https://github.com/acesuit/mace/blob/develop/mace/modules/loss.py): `mace/modules/loss.py`

### Training and analysis

- [Training CLI](https://github.com/acesuit/mace/blob/develop/mace/cli/run_train.py): `mace/cli/run_train.py`
- [Training engine](https://github.com/acesuit/mace/blob/develop/mace/tools/train.py): `mace/tools/train.py`
- [Fine-tuning selection](https://github.com/acesuit/mace/blob/develop/mace/cli/fine_tuning_select.py): `mace/cli/fine_tuning_select.py`
- [Configuration evaluation](https://github.com/acesuit/mace/blob/develop/mace/cli/eval_configs.py): `mace/cli/eval_configs.py`

### Inference and simulation

- [Foundation models](https://github.com/acesuit/mace/blob/develop/mace/calculators/foundations_models.py): `mace/calculators/foundations_models.py`
- [ASE calculator](https://github.com/acesuit/mace/blob/develop/mace/calculators/mace.py): `mace/calculators/mace.py`
- [LAMMPS integration](https://github.com/acesuit/mace/blob/develop/mace/calculators/lammps_mace.py): `mace/calculators/lammps_mace.py`
- [Active-learning MD](https://github.com/acesuit/mace/blob/develop/mace/cli/active_learning_md.py): `mace/cli/active_learning_md.py`

### Model utilities

- [Equivariance conversion](https://github.com/acesuit/mace/blob/develop/mace/cli/convert_e3nn_cueq.py): `mace/cli/convert_e3nn_cueq.py`
- [Backend operations](https://github.com/acesuit/mace/blob/develop/mace/modules/wrapper_ops.py): `mace/modules/wrapper_ops.py`
- [Scatter operations](https://github.com/acesuit/mace/blob/develop/mace/tools/scatter.py): `mace/tools/scatter.py`

### Other components

- **MACE user**
- **Simulation user**

## Connections

- MACE user → Training CLI: starts training (evidence: `README.md`)
- MACE user → Data preprocessing: prepares data
- Training CLI → Atomic graph data: uses data types (evidence: `mace/cli/run_train.py`)
- Atomic graph data → Neighbor construction: builds neighbors (evidence: `mace/data/atomic_data.py`)
- Atomic graph data → Graph batch types: creates graph data (evidence: `mace/data/atomic_data.py`)
- Training CLI → HDF5 dataset: loads dataset
- Training CLI → LMDB dataset: loads dataset
- Equivariant blocks → Radial features: uses radial features (evidence: `mace/modules/blocks.py`)
- Specialized models → Equivariant blocks: uses blocks (evidence: `mace/modules/extensions.py`)
- Training CLI → Training engine: runs training
- Training engine → Training losses: computes loss
- MACE user → Foundation models: uses pretrained models (evidence: `README.md`)
- Foundation models → ASE calculator: wraps calculator (evidence: `mace/calculators/foundations_models.py`)
- Simulation user → ASE calculator: requests predictions
- Simulation user → LAMMPS integration: runs simulations
- MACE user → Fine-tuning selection: selects fine-tuning (evidence: `README.md`)
- MACE user → Configuration evaluation: evaluates configurations
- MACE user → Active-learning MD: runs active MD
- MACE user → Equivariance conversion: converts models
- Equivariance conversion → Backend operations: configures backend (evidence: `mace/cli/convert_e3nn_cueq.py`)
- Equivariant blocks → Backend operations: uses operations (evidence: `mace/modules/blocks.py`)
- Equivariant blocks → Scatter operations: aggregates messages (evidence: `mace/modules/blocks.py`)
