How microsoft/ai2bmd works
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