# duartegroup/mlp-train architecture

> Architecture diagram of the GitHub repository duartegroup/mlp-train, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/duartegroup/mlp-train
- Repository: https://github.com/duartegroup/mlp-train

## Overview

##### Project type and purpose
- This is a Python library (mlp-train) for building and training machine-learning potentials (MLPs) for molecular systems (GAP, ACE, MACE).
- It provides:
- descriptor construction (SOAP, …)
- wrappers to external potential packages (libgap, Julia-ACE, MACE/CUDA)
- sampling methods (MD, metadynamics, umbrella)
- training workflows (active learning, selection, loss definitions)
- optional OpenMM integration

##### File-structure analysis
- Top level:
- mlptrain/        ← core package
- examples/        ← user scripts and notebooks
- docs/            ← Sphinx documentation
- tests/           ← pytest suite
- install_*.sh     ← env-setup scripts per model (GAP, ACE, MACE)
- config files      (.github workflows, pre-commit, environment.yml)
- mlptrain subpackages indicate the logical modules:
- configurations/  ← data I/O and potential evaluation
- descriptor/      ← feature generation
- potentials/      ← model wrappers (ace, gap, mace, nequip)
- sampling/        ← MD, metadynamics, plumed, umbrella, etc.
- training/        ← active learning, selection strategies
- loss/            ← loss‐function implementations
- energy.py, forces.py ← core energy/force API
- utils.py, log.py ← utilities and logging

##### README insights
- The library supports three backends (GAP, ACE, MACE) each in a separate conda environment.
- ACE backend requires Julia; MACE benefits from CUDA.
- Provides an OpenMM integration layer (mlptrain.md_openmm).
- Usage patterns: call mlptrain API (e.g. al_train, run_mlp_md_openmm) from user scripts.

- User Interface:
– CLI scripts (examples/*.py, notebooks)
– Python API (mlptrain.*)
- Core Package (mlptrain):
– Descriptor Module
– Potential Wrappers (GAP, ACE, MACE)
– Sampling Module (MD, metadynamics, umbrella)
– Training Module (active learning, selection)
– Loss Module
– Utilities & Logging
- External Engines & Libraries:
– GAP (libgap)
– ACE (Julia library)
– MACE (PyPI + CUDA)
– OpenMM / PLUMED
– Conda (environment management)
- Data Storage:
– Configuration files, trajectory files, bias files
– Checkpoints (trained models)
b. Relationships & data‐flow
1. User invokes a script → calls mlptrain API
2. mlptrain.descriptor generates features from XYZ inputs
3. descriptor passes to potential wrapper, which calls external engine → returns energy & forces
4. sampling uses forces to propagate MD or collect biased samples → writes trajectories
5. training consumes features + energies + trajectories → updates model parameters (active learning loop)
6. checkpoints saved to disk; can be re-loaded for inference or further training
7. optional: OpenMM backend plug-in overrides the sampling loop, calling mlptrain.md_openmm.run_mlp_md_openmm()
c. Architectural patterns
- Modular package structure (clear separation: descriptor / potential / sampling / training)
- Strategy pattern for sampling and training algorithms (each sampler/trainer implements a common interface)
- Adapter pattern for external engines (GAP, ACE, MACE, OpenMM)
d. Key technologies & frameworks
- Python 3.8+ package, uses conda environments per model
- Julia (for ACE backend)
- CUDA (for MACE)
- OpenMM, PLUMED (for MD backends)
- pytest, pre-commit, Ruff for CI

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph "User Interface"
        UI_CLI["CLI Scripts"]:::ui
        UI_API["Python API"]:::ui
    end

    subgraph "Core Package"
        subgraph "Descriptor Module"
            Descriptor["Descriptor"]:::core
        end
        subgraph "Potentials"
            PotBase["Potential Base"]:::core
            GAPWrap["GAP Adapter"]:::core
            ACEWrap["ACE Adapter"]:::core
            MACEWrap["MACE Adapter"]:::core
            NequIP["NequIP Adapter"]:::core
        end
        subgraph "Sampling"
            SampBase["Sampling Base"]:::core
            MD["MD Sampler"]:::core
            OpenMM["OpenMM Sampler"]:::core
            Meta["Metadynamics"]:::core
            PLUMED["PLUMED"]:::core
            RXCoord["Reaction Coordinate"]:::core
            Umbrella["Umbrella Sampling"]:::core
        end
        subgraph "Training"
            Active["Active Learning"]:::core
            Select["Selection Strategies"]:::core
        end
        subgraph "Loss"
            LossBase["Loss Base"]:::core
            MeanErr["Mean Error Loss"]:::core
            TauLoss["Tau Loss"]:::core
        end
        subgraph "Configurations"
            CalcConfig["Calculate Config"]:::core
            ConfigObj["Configuration Object"]:::core
            ConfigSet["Configuration Set"]:::core
            PlotUtil["Plotting Utilities"]:::core
            TrajIO["Trajectory I/O"]:::core
        end
        Energy["Energy API"]:::core
        Forces["Forces API"]:::core
        Utils["Utilities"]:::core
        Log["Logging"]:::core
        System["System Entrypoints"]:::core
        ConfigParser["Configuration Parser"]:::core
        Molecule["Molecule Data"]:::core
        Box["Box Handling"]:::core
    end

    subgraph "External Engines & Libraries"
        GAP["GAP (libgap)"]:::external
        ACE["ACE (Julia)"]:::external
        MACE["MACE (CUDA)"]:::external
        OpenMMLib["OpenMM"]:::external
        PLUMEDLib["PLUMED"]:::external
        Conda["Conda Environments"]:::external
    end

    subgraph "Data Stores"
        ConfigFiles["Config Files"]:::data
        Trajectories["Trajectory Files"]:::data
        Checkpoints["Checkpoints"]:::data
    end

    UI_CLI -->|"invoke"| UI_API
    UI_API -->|"calls API"| Descriptor
    Descriptor -->|"features"| GAPWrap
    Descriptor -->|"features"| ACEWrap
    Descriptor -->|"features"| MACEWrap
    Descriptor -->|"features"| NequIP
    GAPWrap -.->|calls| GAP
    ACEWrap -.->|calls| ACE
    MACEWrap -.->|calls| MACE
    NequIP -.->|calls| MACE
    UI_API -->|"selects sampler"| MD
    UI_API -->|"selects sampler"| OpenMM
    UI_API -->|"selects sampler"| Meta
    UI_API -->|"selects sampler"| PLUMED
    UI_API -->|"selects sampler"| RXCoord
    UI_API -->|"selects sampler"| Umbrella
    MD -.->|calls| Conda
    OpenMM -.->|calls| OpenMMLib
    OpenMM -.->|calls| Conda
    Meta -.->|calls| PLUMEDLib
    PLUMED -.->|calls| PLUMEDLib
    MD -->|"forces"| Forces
    MD -->|"energies"| Energy
    OpenMM -->|"run_mlp_md_openmm()"| OpenMMLib
    MD -->|"trajectory"| Trajectories
    Meta -->|"trajectory"| Trajectories
    PLUMED -->|"trajectory"| Trajectories
    RXCoord -->|"trajectory"| Trajectories
    Umbrella -->|"trajectory"| Trajectories
    Trajectories -->|"used by"| Active
    Active -->|"selects data"| Select
    Select -->|"provides samples"| Descriptor
    Active -->|"updates model"| Checkpoints
    Checkpoints -->|"loaded by"| UI_API
    LossBase -->|"used in"| Active
    MeanErr -->|"used in"| LossBase
    TauLoss -->|"used in"| LossBase
    ConfigParser -->|"reads"| ConfigFiles
    CalcConfig -->|"generates"| ConfigFiles
    ConfigObj -->|"holds"| ConfigFiles
    ConfigSet -->|"groups"| ConfigFiles
    PlotUtil -->|"plots"| Trajectories
    TrajIO -->|"reads/writes"| Trajectories
    Utils -->|"supports"| UI_API
    Log -->|"logs events"| UI_API
    System -->|"orchestrates"| UI_API
    Molecule -->|"data model"| Descriptor
    Box -->|"data model"| Descriptor

    click Descriptor "https://github.com/duartegroup/mlp-train/tree/main/mlptrain/descriptor/"
    click PotBase "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/potentials/_base.py"
    click GAPWrap "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/potentials/gap/gap.py"
    click ACEWrap "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/potentials/ace/ace.py"
    click MACEWrap "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/potentials/mace/mace.py"
    click NequIP "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/potentials/nequip/_nequip.py"
    click SampBase "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/sampling/_base.py"
    click MD "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/sampling/md.py"
    click OpenMM "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/sampling/md_openmm.py"
    click Meta "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/sampling/metadynamics.py"
    click PLUMED "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/sampling/plumed.py"
    click RXCoord "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/sampling/reaction_coord.py"
    click Umbrella "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/sampling/umbrella.py"
    click Active "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/training/active.py"
    click Select "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/training/selection.py"
    click LossBase "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/loss/_base.py"
    click MeanErr "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/loss/mean_errors.py"
    click TauLoss "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/loss/tau.py"
    click CalcConfig "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/configurations/calculate.py"
    click ConfigObj "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/configurations/configuration.py"
    click ConfigSet "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/configurations/configuration_set.py"
    click PlotUtil "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/configurations/plotting.py"
    click TrajIO "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/configurations/trajectory.py"
    click Energy "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/energy.py"
    click Forces "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/forces.py"
    click Utils "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/utils.py"
    click Log "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/log.py"
    click System "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/system.py"
    click ConfigParser "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/config.py"
    click Molecule "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/molecule.py"
    click Box "https://github.com/duartegroup/mlp-train/blob/main/mlptrain/box.py"

    classDef core fill:#D0E6FF,stroke:#333,stroke-width:1px
    classDef external fill:#D0FFD0,stroke:#333,stroke-width:1px
    classDef data fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef ui fill:#E0E0E0,stroke:#333,stroke-width:1px
```
