How nec-research/dimos works
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.