# thorben-frank/mlff architecture

> Architecture diagram of the GitHub repository thorben-frank/mlff, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-03-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/thorben-frank/mlff
- Repository: https://github.com/thorben-frank/mlff

## Overview

##### Main Components
- Data Processing & Input: Represent the input data pipeline – note the mlff/data directory which includes data reading, dataloading, and preprocessing of chemical structures. Also include the support for multiple file formats (XYZ, NPZ) as described in the README.
- Model & Neural Network Components: Emphasize the “mlff/nn” sub-package which houses various submodules (embedding, layers, MLP, observable functions, representations, and stacknet) that effectively build the SO3krates transformer network.
- MD Simulation & Integration: Include the “mlff/md” and “mlff/mdx” packages that deal with molecular dynamics simulations, integration methods, and potential calculations.
- Force Field & Calculation Modules: Highlight components in “mlff/cAPI” and “mlff/io” which provide the capability to evaluate, analyze, and relax structures, along with saving and checkpointing during training.
- Training, Evaluation, and Optimization: Direct attention to “mlff/training” where training routines, loss functions, optimizers, learning rate scheduling, and stopping criteria are defined. This is core to preparing and validating models.
- Auxiliary Components: Represent additional functionality such as geometric operations (mlff/geometric), indexing (mlff/indexing), masking (mlff/masking), cutoff functions, padding, random utilities, and property handling that support the primary modules.
- External Integration & CLI: Clearly denote the role of the command line interface (e.g., train_so3krates, run_md, evaluate, trajectory_to_xyz) as well as external dependencies like ASE for reading input geometries, Weights & Biases for experiment tracking, and the glp package for creating ASE calculators.

##### Relationships & Data Flow
- Input Data flows from file formats (XYZ, NPZ, etc.) into the data loading and preprocessing components.
- Preprocessed data is then funneled into the training pipeline which leverages the neural network modules (embedding, layers, etc.) to build and train the force field model.
- The training module communicates with the checkpointing and logging utilities (Weights & Biases integration) to track progress and save model states.
- After training, inference modules (found in mlff/inference and mlff/cAPI) use the stored model weights for evaluating energy, force, and other physical properties.
- MD simulation packages (mlff/md and mlff/mdx) incorporate the trained potential to perform simulations, where the simulation output can be post-processed using the IO and evaluation routines.
- Utility considerations like cutoff handling, masking, geometric transformations, and spherical operations are applied throughout and interconnect various modules to ensure data consistency and adherence to physical constraints.

##### Architectural Patterns & Design Principles
- Layered Modularization: The project is divided into specialized packages such as “data”, “nn”, “md”, “training”, etc., which is typical of a well-modularized ML application.
- Separation of Concerns: By isolating data handling, neural network modeling, training routines, and MD simulation, the architecture supports clear abstraction boundaries.
- CLI-Driven Workflow: The project supports command-line training and evaluation, with clear separation between experimentation (training/evaluation) and production (calculator for MD simulations).
- Extensibility: The presence of components like “cAPI” and “nn/h_register” indicate a design that favors extensibility via new registration of modules, hyperparameters, or potential components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Input & Data Layer
    subgraph "Input & Data Layer"
        ExternalInputs("External Inputs (XYZ, NPZ)"):::external
        DataPreprocessing("Data Preprocessing (mlff/data)"):::data
    end

    %% Model & Neural Network Layer
    subgraph "Model & Neural Network Layer"
        NNModules("Neural Network Modules (mlff/nn)"):::model
    end

    %% Training & Evaluation Layer
    subgraph "Training & Evaluation Layer"
        TrainingEvaluation("Training & Evaluation (mlff/training)"):::training
    end

    %% Post-training Modules
    subgraph "Post-Training Modules"
        MD_Sim("MD Simulation (mlff/md & mlff/mdx)"):::md
        ForceField("Force Field & Calc (mlff/cAPI & mlff/io)"):::force
    end

    %% Auxiliary Components
    subgraph "Auxiliary Components"
        AuxGeo("Geometric Operations (mlff/geometric)"):::aux
        AuxIdx("Indexing (mlff/indexing)"):::aux
        AuxMask("Masking (mlff/masking)"):::aux
        AuxCut("Cutoff Functions (mlff/cutoff_function)"):::aux
        AuxPad("Padding (mlff/padding)"):::aux
        AuxRand("Random Utilities (mlff/random)"):::aux
        AuxProp("Properties (mlff/properties)"):::aux
        AuxSph("Spherical Ops (mlff/sph_ops)"):::aux
    end

    %% External Integration & CLI
    subgraph "External Integration & CLI"
        WnB("Weights&Biases"):::external
        ASE("ASE"):::external
        glp("glp Calculator"):::external
        CLI1("Train So3krates (examples/train_so3krates.py)"):::cli
        CLI2("Run MD (examples/mdx_md.py)"):::cli
    end

    %% Data Flow Connections
    ExternalInputs -->|"data"| DataPreprocessing
    DataPreprocessing -->|"preprocessing"| NNModules
    NNModules -->|"features"| TrainingEvaluation
    TrainingEvaluation -->|"checkpoints"| ForceField
    TrainingEvaluation -->|"model_for_sim"| MD_Sim
    ForceField -->|"forces_&_energies"| MD_Sim

    %% Auxiliary Component Usage
    DataPreprocessing ---|"utilizes"| AuxGeo
    DataPreprocessing ---|"utilizes"| AuxIdx
    NNModules ---|"integrates"| AuxMask
    TrainingEvaluation ---|"customizes"| AuxRand
    ForceField ---|"employs"| AuxCut
    ForceField ---|"applies"| AuxPad
    ForceField ---|"references"| AuxProp
    MD_Sim ---|"applies"| AuxSph

    %% External Integrations
    TrainingEvaluation -->|"logging"| WnB
    ASE -->|"reads_geom"| MD_Sim
    glp -->|"interfaces"| ForceField
    CLI1 -->|"triggers_train"| TrainingEvaluation
    CLI2 -->|"triggers_md"| MD_Sim

    %% Click Events
    click DataPreprocessing "https://github.com/thorben-frank/mlff/tree/main/mlff/data"
    click NNModules "https://github.com/thorben-frank/mlff/tree/main/mlff/nn"
    click TrainingEvaluation "https://github.com/thorben-frank/mlff/tree/main/mlff/training"
    click MD_Sim "https://github.com/thorben-frank/mlff/tree/main/mlff/md"
    click MD_Sim "https://github.com/thorben-frank/mlff/tree/main/mlff/mdx"
    click ForceField "https://github.com/thorben-frank/mlff/tree/main/mlff/cAPI"
    click ForceField "https://github.com/thorben-frank/mlff/tree/main/mlff/io"
    click AuxGeo "https://github.com/thorben-frank/mlff/tree/main/mlff/geometric"
    click AuxIdx "https://github.com/thorben-frank/mlff/tree/main/mlff/indexing"
    click AuxMask "https://github.com/thorben-frank/mlff/tree/main/mlff/masking"
    click AuxCut "https://github.com/thorben-frank/mlff/tree/main/mlff/cutoff_function"
    click AuxPad "https://github.com/thorben-frank/mlff/tree/main/mlff/padding"
    click AuxRand "https://github.com/thorben-frank/mlff/tree/main/mlff/random"
    click AuxProp "https://github.com/thorben-frank/mlff/tree/main/mlff/properties"
    click AuxSph "https://github.com/thorben-frank/mlff/tree/main/mlff/sph_ops"
    click CLI1 "https://github.com/thorben-frank/mlff/blob/main/examples/train_so3krates.py"
    click CLI2 "https://github.com/thorben-frank/mlff/blob/main/examples/mdx_md.py"

    %% Styles
    classDef external fill:#bbf,stroke:#333,stroke-width:2px
    classDef data fill:#fcf,stroke:#333,stroke-width:2px
    classDef model fill:#cff,stroke:#333,stroke-width:2px
    classDef training fill:#ffc,stroke:#333,stroke-width:2px
    classDef md fill:#cfc,stroke:#333,stroke-width:2px
    classDef force fill:#fcc,stroke:#333,stroke-width:2px
    classDef aux fill:#eee,stroke:#666,stroke-width:1px,stroke-dasharray: 5 5
    classDef cli fill:#eef,stroke:#333,stroke-width:2px
```
