# nec-research/dimos architecture

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

- Interactive diagram: https://gitdiagram.com/nec-research/dimos
- Repository: https://github.com/nec-research/dimos

## Overview

##### Project type and purpose
- DIMOS is an open-source Python library and framework for differentiable molecular simulations (MD and MC) built on PyTorch.
- It bridges classical force fields, machine-learning interatomic potentials (MLIPs), and hybrid ML/MM methods, exposing an API for users to configure systems, integrators, simulation loops, and advanced sampling.

##### File structure
- Top-level:
- dimos/            ← core Python package
- benchmark/       ← performance scripts
- examples/        ← usage examples for Amber/GROMACS
- experiments/     ← research notebooks
- tests/           ← unit and integration tests
- pyproject.toml   ← project metadata
- Within dimos/:
- advanced_methods/← metadynamics, replica-exchange
- barostats.py, integrators.py, constraints.py, ewald.py, neighbor_handling.py, distribution.py
- ff.py            ← classical force fields
- mlip/            ← modules for MACE and ORB ML potentials
- mlmm.py          ← hybrid ML/MM mixing
- monte_carlo.py   ← MC samplers
- energy.py, simulation.py
- utils.py, constants.py, splines.py
- Configuration & I/O: no dedicated “io” folder, but examples load prmtop/rst7/gro files directly via AmberForceField and GROMACS parsers (embedded in ff.py).

##### README
- Confirms core API: AmberForceField, integrators (e.g. LangevinDynamics), MDSimulation.
- Highlights extensibility (optional MLIP dependencies).
- Shows end-to-end differentiable workflow on PyTorch.

1. User/API Layer
– Scripts, examples, benchmarks, experiments
– Calls into dimos.* classes
2. Simulation Coordinator
– MDSimulation (or MCSimulation)
– orchestrates time stepping, loss/grad computations
3. System Definition
– AmberForceField, GROMACS parser, custom topologies
– Constants, utility functions
4. Force Field Modules
– Classical FF (ff.py)
– MLIPs (dimos.mlip: MACE, ORB)
– Hybrid ML/MM (mlmm.py)
5. Energy & Forces
– energy.py, ewald.py, splines.py
6. Dynamics Engines
– Integrators (integrators.py)
– Monte Carlo (monte_carlo.py)
7. Auxiliary Algorithms
– Constraints (constraints.py)
– Neighbor Lists & PME (neighbor_handling.py, ewald.py)
– Distribution/Thermostats (distribution.py)
– Barostats (barostats.py)
8. Advanced Sampling
– Metadynamics, ReplicaExchange (advanced_methods/)
9. Backend
– PyTorch tensors, GPU/CPU compute
10. I/O & Utilities
– utils.py, constants.py, logging, checkpointing

b. Relationships & interactions
- User/API → Simulation Coordinator: instantiates MDSimulation with system, integrator, initial positions.
- Simulation Coordinator ↔ System Definition: queries topology, parameters.
- Simulation Coordinator → Force Field Modules: requests energy, forces.
- Force Field Modules → Energy & Forces: call Ewald, splines, neighbor lists.
- Simulation Coordinator → Dynamics Engines: passes forces & state, receives updated positions.
- Dynamics Engines → Auxiliary Algorithms: enforce constraints, apply thermostats/barostats, update neighbor lists.
- Advanced Sampling hooks into Simulation Coordinator to bias energies or swap replicas.
- All compute operations map to PyTorch backend for automatic differentiation.
- I/O & Utilities serve all layers for logging, file parsing, unit conversions.

c. Architectural patterns/design principles
- Modular plugin pattern: each component (FF, integrator, sampler) implements a common interface.
- Separation of concerns: system definition, energy evaluation, dynamics, and sampling strategies are distinct.
- Extensibility: MLIP modules and advanced methods can be added without changing core engine.
- Data-flow-centric: pipelines built on PyTorch computational graph for end-to-end diff.

d. Key technologies/frameworks
- Python 3.8+
- PyTorch (tensor operations, autodiff)
- Optional MLIP backends: MACE, ORB
- Amber/GROMACS file readers (via custom parsers/utilities)
- Standard scientific libraries for tests (scipy, networkx, pandas, tqdm)

##### Final recommendations
- How user scripts (examples, benchmark) sit on top of the API.

## Diagram (Mermaid)

```mermaid
graph TD
    subgraph "User/API Layer"
        Examples["examples"]:::userapi
        Benchmark["benchmark"]:::userapi
        Experiments["experiments"]:::userapi
    end

    Sim["Simulation Coordinator\n(dimos/simulation.py)"]:::core
    click Sim "https://github.com/nec-research/dimos/blob/public-branch/dimos/simulation.py"

    Examples -->|"instantiate"| Sim
    Benchmark -->|"instantiate"| Sim
    Experiments -->|"instantiate"| Sim

    subgraph "System Definition"
        FFSystem["ForceField Parsers\n(dimos/ff.py)"]:::core
        Constants["Constants & Units\n(dimos/constants.py)"]:::utility
        Utils["Utilities & I/O\n(dimos/utils.py)"]:::utility
    end
    click FFSystem "https://github.com/nec-research/dimos/blob/public-branch/dimos/ff.py"
    click Constants "https://github.com/nec-research/dimos/blob/public-branch/dimos/constants.py"
    click Utils "https://github.com/nec-research/dimos/blob/public-branch/dimos/utils.py"

    Sim -->|"query topology, params"| FFSystem
    Sim -->|"query constants"| Constants
    Sim -->|"use utilities"| Utils

    subgraph "Force Evaluation"
        ClassicalFF["Classical FF\n(dimos/ff.py)"]:::core
        MACE["MACE MLIP\n(dimos/mlip/mace.py)"]:::plugin
        ORB["ORB MLIP\n(dimos/mlip/orb.py)"]:::plugin
        Hybrid["Hybrid ML/MM\n(dimos/mlmm.py)"]:::plugin
    end
    click ClassicalFF "https://github.com/nec-research/dimos/blob/public-branch/dimos/ff.py"
    click MACE "https://github.com/nec-research/dimos/blob/public-branch/dimos/mlip/mace.py"
    click ORB "https://github.com/nec-research/dimos/blob/public-branch/dimos/mlip/orb.py"
    click Hybrid "https://github.com/nec-research/dimos/blob/public-branch/dimos/mlmm.py"

    Sim -->|"request forces"| ClassicalFF
    Sim -->|"request forces"| MACE
    Sim -->|"request forces"| ORB
    Sim -->|"request forces"| Hybrid

    subgraph "Energy & Forces"
        Energy["Energy Eval\n(dimos/energy.py)"]:::core
        Ewald["PME/Ewald\n(dimos/ewald.py)"]:::core
        Splines["Splines\n(dimos/splines.py)"]:::core
    end
    click Energy "https://github.com/nec-research/dimos/blob/public-branch/dimos/energy.py"
    click Ewald "https://github.com/nec-research/dimos/blob/public-branch/dimos/ewald.py"
    click Splines "https://github.com/nec-research/dimos/blob/public-branch/dimos/splines.py"

    ClassicalFF -->|"calls"| Energy
    MACE -->|"calls"| Energy
    ORB -->|"calls"| Energy
    Hybrid -->|"calls"| Energy

    Energy -->|"uses"| Ewald
    Energy -->|"uses"| Splines

    subgraph "Dynamics & Sampling"
        Integrator["Integrators\n(dimos/integrators.py)"]:::core
        MonteCarlo["Monte Carlo\n(dimos/monte_carlo.py)"]:::core
    end
    click Integrator "https://github.com/nec-research/dimos/blob/public-branch/dimos/integrators.py"
    click MonteCarlo "https://github.com/nec-research/dimos/blob/public-branch/dimos/monte_carlo.py"

    Sim -->|"control flow"| Integrator
    Sim -->|"control flow"| MonteCarlo

    subgraph "Auxiliary Algorithms"
        Constraints["Constraints\n(dimos/constraints.py)"]:::core
        Distribution["Thermostats\n(dimos/distribution.py)"]:::core
        Barostats["Barostats\n(dimos/barostats.py)"]:::core
        NeighborList["Neighbor Handling\n(dimos/neighbor_handling.py)"]:::core
    end
    click Constraints "https://github.com/nec-research/dimos/blob/public-branch/dimos/constraints.py"
    click Distribution "https://github.com/nec-research/dimos/blob/public-branch/dimos/distribution.py"
    click Barostats "https://github.com/nec-research/dimos/blob/public-branch/dimos/barostats.py"
    click NeighborList "https://github.com/nec-research/dimos/blob/public-branch/dimos/neighbor_handling.py"

    Integrator -->|"enforce"| Constraints
    Integrator -->|"apply"| Distribution
    Integrator -->|"apply"| Barostats
    MonteCarlo -->|"update neighbors"| NeighborList

    subgraph "Advanced Sampling"
        Meta["Metadynamics\n(dimos/advanced_methods/metadynamics.py)"]:::advanced
        Replica["Replica Exchange\n(dimos/advanced_methods/replica_exchange.py)"]:::advanced
    end
    click Meta "https://github.com/nec-research/dimos/blob/public-branch/dimos/advanced_methods/metadynamics.py"
    click Replica "https://github.com/nec-research/dimos/blob/public-branch/dimos/advanced_methods/replica_exchange.py"

    Meta -->|"bias energies"| Sim
    Replica -->|"swap replicas"| Sim

    Sim -->|"tensor ops"| Backend
    ClassicalFF -->|"tensor ops"| Backend
    MACE -->|"tensor ops"| Backend
    ORB -->|"tensor ops"| Backend
    Hybrid -->|"tensor ops"| Backend
    Energy -->|"tensor ops"| Backend
    Integrator -->|"tensor ops"| Backend
    MonteCarlo -->|"tensor ops"| Backend
    Constraints -->|"tensor ops"| Backend
    Distribution -->|"tensor ops"| Backend
    Barostats -->|"tensor ops"| Backend
    NeighborList -->|"tensor ops"| Backend
    Meta -->|"tensor ops"| Backend
    Replica -->|"tensor ops"| Backend

    subgraph "Backend"
        Backend["PyTorch Compute"]:::backend
    end

    classDef core fill:#AED8E6,stroke:#333,stroke-width:1px
    classDef plugin fill:#C8E6C9,stroke:#333,stroke-width:1px
    classDef advanced fill:#FFE0B2,stroke:#333,stroke-width:1px
    classDef utility fill:#F5F5F5,stroke:#333,stroke-width:1px
    classDef userapi fill:#B3E5FC,stroke:#333,stroke-width:1px
    classDef backend fill:#D1C4E9,stroke:#333,stroke-width:1px
```
