# microsoft/ai2bmd architecture

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

- Interactive diagram: https://gitdiagram.com/microsoft/ai2bmd
- Repository: https://github.com/microsoft/ai2bmd

## Overview

##### Project type and purpose
- AI²BMD is a scientific simulation application for *ab initio* biomolecular dynamics.
- It is primarily a command-line Python program packaged in a Docker image, not a web or GUI app.
- Its main tasks: preprocess a protein structure, run a production MD simulation (fragment-based or whole-molecule via ViSNet), and post-process trajectories.

##### File structure
- Top level:
- `scripts/ai2bmd`: Python launcher that wraps Docker and dispatches simulation.
- `src/`: core Python modules.
- `examples/`: sample PDB inputs, preprocessed folders.
- `docs/`: design and algorithm notes.
- CI/CD configs under `.github/`.
- Under `src/`:
- `main.py`: entry point.
- `AIMD/`: orchestrates high-level simulation workflow (arguments, fragment generation, preprocessing, simulation control).
- `Fragmentation/`: logic and data files for protein fragmentation.
- `Calculators/`: core physics and ML force/energy computations (bonded, nonbonded, PME, QM/MM, VisNet wrapper).
- `ViSNet/`: contains pretrained model checkpoints and model code for whole-molecule inference.
- `utils/`: I/O for PDB, trajectories, system setup, conversion tools.
- Configuration/build/deploy:
- Docker image holds Python runtime, ASE, AmberTools inside container.
- CI pipeline uses `codeql.yml` to run tests and security scans.

##### Extract insights from README
- Workflow: User invokes `ai2bmd` launcher → Docker container runs `main.py`.
- Modes:
- `fragment`: break protein into dipeptides → use ML potential in each step.
- `visnet`: whole-molecule inference using ViSNet.
- Preprocess methods: `FF19SB` (Amber solvation, heating, pre-equilibration), `AMOEBA`.
- Post-analysis: ASE `.traj` → optional DCD conversion via `traj2dcd.py`.

- Launcher (scripts/ai2bmd + Docker CLI)
- Container (Docker image)
- Simulation Orchestrator (src/main.py + AIMD module)
- Preprocessor (AIMD/preprocess.py invoking AmberTools or internal routines)
- Fragmentation Engine (src/Fragmentation)
- Calculator Suite (src/Calculators)
- ViSNet Inference Module (src/ViSNet)
- Utilities & I/O (src/utils)
- External Tools & Services (Docker daemon, GPU driver, AmberTools, PyMOL)
- Data Stores: Input PDB, NPZ datasets, checkpoint files, output trajectory.

1. User → Launcher → Docker daemon
2. Docker invokes Simulation Orchestrator
3. Orchestrator calls:
- Preprocessor ← PDB input
- Fragmentation (if mode=fragment) → passes fragments to Calculator Suite
- ViSNet Module (if mode=visnet) → passes structure to model
4. Calculator Suite ↔ GPU (device strategy)
5. Calculations produce forces → back to Orchestrator to update positions
6. Orchestrator writes trajectory via Utilities
7. Post Analysis tool reads trajectory → writes DCD.

c. Architectural patterns and principles
- Modular pipeline: clear separation of preprocessing, simulation control, calculation, post-processing.
- Strategy pattern for device allocation (`device_strategy` in Calculators).
- Plugin-like ML models: VisNet adapter in Calculators for seamless interchange with fragment-based ML.
- Data directory mapping: mounting host dirs into container for reproducibility.

d. Key technologies/frameworks
- Python 3.7+ and modules (ASE, MDAnalysis optional)
- Docker for environment isolation
- AmberTools (external binary)
- PyMOL (external Python library for capping)
- PyTorch (implicitly in ViSNet model code)
- NumPy/NPZ for datasets
- CLI argument parsing in `src/AIMD/arguments.py`

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User and Host Layer
    User["User"]:::external -->|invokes| Launcher["Launcher<br/>(scripts/ai2bmd)"]:::external
    Launcher -->|docker run| DockerDaemon["Docker Daemon"]:::external

    %% Docker Container Boundary
    subgraph "Docker Container" 
        direction TB
        ContainerEntrypoint["Entrypoint<br/>(src/main.py)"]:::orchestration

        %% Orchestration Layer
        subgraph "Orchestration Layer"
            direction TB
            Orchestrator["Simulation Orchestrator<br/>(src/main.py,<br/>src/AIMD/__init__.py,<br/>src/AIMD/simulator.py)"]:::orchestration
            CLIArgs["CLI Argument Parser<br/>(src/AIMD/arguments.py)"]:::orchestration
        end

        %% Preprocessing and Data
        subgraph "Preprocessing"
            direction TB
            Preprocessor["Preprocessor<br/>(src/AIMD/preprocess.py)"]:::orchestration
            ProteinData["Protein Data Structures<br/>(src/AIMD/protein.py,<br/>src/AIMD/fragment.py)"]:::orchestration
        end

        %% Simulation Modules
        subgraph "Simulation Modules"
            direction TB
            FragEngine["Fragmentation Engine<br/>(src/Fragmentation)"]:::compute
            ViSNetModule["ViSNet Inference Module<br/>(src/ViSNet)"]:::compute
            CalcSuite["Calculator Suite<br/>(src/Calculators)"]:::compute
        end

        %% Utilities and I/O
        subgraph "Utilities & I/O"
            direction TB
            Utils["Utilities<br/>(src/utils)"]:::io
            TrajDB["Trajectory Output"]:::io
        end

        %% Orchestrator Flow
        ContainerEntrypoint --> Orchestrator
        Orchestrator --> CLIArgs
        Orchestrator -->|reads PDB| Preprocessor
        Preprocessor -->|writes preprocessed files| TrajDB
        Orchestrator -->|mode=fragment| FragEngine
        Orchestrator -->|mode=visnet| ViSNetModule
        FragEngine -->|fragments| CalcSuite
        ViSNetModule -->|structure| CalcSuite
        CalcSuite -->|calculates forces| Orchestrator
        Orchestrator -->|writes trajectory| Utils
        Utils -->|writes DCD| TrajDB

        %% External Tools
        subgraph "External Tools & Hardware"
            direction TB
            GPU["GPU Device"]:::external
            AmberTools["AmberTools"]:::external
            DockerDaemonEdge((" ")):::external
        end

        CalcSuite -->|GPU acceleration| GPU
        Preprocessor -->|calls| AmberTools
        ContainerEntrypoint -.-> DockerDaemonEdge
    end

    %% Data Stores
    subgraph "Data Stores"
        direction TB
        PDBInput["Input PDB Files"]:::io
        NPZData["NPZ Datasets"]:::io
        Checkpoints["Model Checkpoints"]:::io
    end
    PDBInput --> Preprocessor
    NPZData --> FragEngine
    Checkpoints --> ViSNetModule

    %% Click Events
    click Launcher "https://github.com/microsoft/ai2bmd/tree/main/scripts/ai2bmd"
    click ContainerEntrypoint "https://github.com/microsoft/ai2bmd/blob/main/src/main.py"
    click Orchestrator "https://github.com/microsoft/ai2bmd/blob/main/src/AIMD/simulator.py"
    click CLIArgs "https://github.com/microsoft/ai2bmd/blob/main/src/AIMD/arguments.py"
    click Preprocessor "https://github.com/microsoft/ai2bmd/blob/main/src/AIMD/preprocess.py"
    click ProteinData "https://github.com/microsoft/ai2bmd/blob/main/src/AIMD/protein.py"
    click ProteinData "https://github.com/microsoft/ai2bmd/blob/main/src/AIMD/fragment.py"
    click FragEngine "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/__init__.py"
    click FragEngine "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/basefrag.py"
    click FragEngine "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/distancefrag.py"
    click FragEngine "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/hydrogen/ctable.py"
    click FragEngine "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/hydrogen/energies.py"
    click FragEngine "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/hydrogen/topology.py"
    click FragEngine "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/mm.in"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/__init__.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/calculator.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/device_strategy.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/async_utils.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/bonded.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/nonbonded.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/pme.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/qmmm.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/fragment.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/combiner.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/tinker_async.py"
    click CalcSuite "https://github.com/microsoft/ai2bmd/blob/main/src/Calculators/visnet_calculator.py"
    click ViSNetModule "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/__init__.py"
    click ViSNetModule "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/model/visnet.py"
    click ViSNetModule "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/model/visnet_block.py"
    click ViSNetModule "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/model/output_modules.py"
    click ViSNetModule "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/model/priors.py"
    click ViSNetModule "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/model/utils.py"
    click ViSNetModule "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/checkpoints/visnet.ckpt"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/pdb.py"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/system.py"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/traj2dcd.py"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/utils.py"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/reference.py"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/signals.py"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/amoebabio18.prm"
    click Utils "https://github.com/microsoft/ai2bmd/blob/main/src/utils/seq_dict.pkl"
    click DockerDaemon "https://github.com/microsoft/ai2bmd/tree/main/Dockerfile"
    click PDBInput "https://github.com/microsoft/ai2bmd/blob/main/examples/sample.pdb"
    click NPZData "https://github.com/microsoft/ai2bmd/blob/main/src/Fragmentation/bondlen/sample.npz"
    click Checkpoints "https://github.com/microsoft/ai2bmd/blob/main/src/ViSNet/checkpoints/sample.ckpt"

    %% Styles
    classDef orchestration fill:#D0E6FF,stroke:#009,stroke-width:1px;
    classDef compute fill:#DFF2BF,stroke:#3A7,stroke-width:1px;
    classDef io fill:#FFE4B5,stroke:#E68,stroke-width:1px;
    classDef external fill:#E0E0E0,stroke:#666,stroke-width:1px;
```
