Welcome to the IMD-streaming workshop at the MDAnalysis UGM 2025! This workshop is a part of the broader IMD Streaming Session. The Streaming Session agenda has also been linked below for reference. This repository contains all the materials, scripts and instructions for the workshop
If you're interested in using our tools after the workshop and watching a recording, see post workshop
If you'd like to follow along with the speakers or use the demo codes after the workshop, all workshop demo code is available in this repo.
| Time | Topic | Location | Speaker | Code | Presentation |
|---|---|---|---|---|---|
| 2:30 PM - 2:50 PM | 🖼️ IMD Streaming Introduction | PSF 186 | Matthias Heyden | ||
| 2:50 PM - 3:10 PM | 📦 IMDv3 Streaming: Theory, Implementation, Technical Details | PSF 186 | Lawson Woods | ||
| 3:10 PM - 3:30 PM | 🚀 IMDv3 in Practice: MD Packages, Performance | PSF 186 | Amruthesh Thirumalaiswamy | ||
| 3:30 PM - 3:45 PM | ☕ Tea / Coffee Break | PSF foyer | |||
| 3:45 PM - 4:05 PM | 👀 Streaming Applications Demo (2 Examples) | PSF 186 | Heekun Cho | gromacs-demos/vdos/demo.ipynb, namd-demos/ion-flux/ion-flux.ipynb | 04-Application_Velocity_correlation_functions_and_2PT-Cho.pdf, 04-Application_Ion_channel_permeation-Cho.pdf |
| 4:05 PM - 5:05 PM | 🎯 Streaming Workshop | PSF 186 | Amruthesh Thirumalaiswamy | workshop.ipynb | |
| 5:05 PM - 5:25 PM | 🌊 Integrating MDAnalysis Streaming Analysis with WESTPA | PSF 186 | Jamie Rowe | ||
| 5:25 PM - 5:35 PM | ☕ Tea / Coffee Break | PSF foyer | |||
| 5:35 PM - 5:55 PM | 👀 Streaming Applications Demo | PSF 186 | Heekun Cho | namd-demos/rmsd-rdf/rmsd-rdf.ipynb | |
| 5:55 PM - 6:00 PM | 🚪 Closing Remarks | PSF 186 | Irfan Alibay |
For the workshop, we will be using GitHub codespaces - a cloud-based development environment. We have a pre-configured codespace environment linked to this repository that includes all the necessary tools and dependencies for live simulation streaming.
The easiest way is to simply use this repository to create a codespace. A workshop environment will be created and VSCode will automatically run in your browser.
Duplicate this tab so you will still have access to these instructions when the codespace is launched.
Select the green "Code" button and then create a codespace:
You're done! The codespace will launch in the current tab. Move on to section 2 to get started with the workshop.
You can use your own IDE to spin up and connect to a codespace (which GitHub will host).
If you have VSCode installed, you can install the codespace extension.
After installing, you'll see the "remote explorer" icon on the left. Sign in if you aren't already.
Select the dropdown arrow to select "Github codespaces" and then select the "+" to create a new codespace.
A dialog will appear. For the repository, enter "amruthesht/imd-workshop-2025". For the branch, select "main" For the machine type, select "2 cores, 8GB RAM, 32 GB storage"
After that, VSCode will automatically launch a new window which is executing in the codespace workshop environment. To troubleshoot, see the documentation here.
A codespace extension is also available for Pycharm.
You can also run the workshop activity locally if you have the devcontainers VScode extension and docker installed.
After docker is installed & enabled and your user has been added to the docker group, run:
git clone https://github.com/amruthesht/imd-workshop-2025.git
code imd-workshop-2025In VSCode, enter CTRL+SHIFT+P and type: "Dev Containers: Open Folder in Container..." and select the root of the cloned repo as the folder path. A new window will open which is executing in the workshop activity codespace.
First, open the workshop/workshop.ipynb Jupyter notebook from this repo in your codespace environment.
Before running any code, click the "Select kernel" button in the upper right corner of the Jupyter notebook.
Select "Python environments" and then the "workshop" environment.
Now you're ready to start the workshop! Follow the instructions in the notebook to complete the streaming activities.
If you need help, you can refer to the workshop/solutions.ipynb notebook which contains solutions/ expected output for all the try-yourself sections.
If you are interested in using our tools, please feel free to reach out for support, bug reports, or for sharing your ideas!
The best way to reach us is on the MDAnalysis Discord in the '#streaming' channel. You can also reach out to us via email ([email protected])
- A recording of the workshop will be made available after the event.
- All workshop materials are available in this repository. Broader Streaming Session materials are linked from the Session agenda.
- Below, we provide instructions for using the simulation engines integrated with IMDv3 capability. You can either use docker images (for GROMACS and LAMMPS) or build your own version (GROMACS, LAMMPS, NAMD).
For docker usage, ensure docker is installed and the nvidia container toolkit is installed if using GPU builds.
First, pull the container:
# CPU-only build
docker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu
# CUDA build
docker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-gpuTo run GROMACS, do:
# CPU
docker run -v /path/to/input/files:/home/conda:rw -p 8889:8889 \
ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu bash -c 'gmx <cmd>'
# GPU
docker run -v /path/to/input/files:/home/conda:rw --runtime=nvidia --gpus=all -p 8889:8889 \
ghcr.io/becksteinlab/streaming-md-docker:main-common-gpu bash -c 'gmx <cmd>'The modified codes are available in this GROMACS fork.
First, clone in the repo:
git clone https://gitlab.com/heydenlabasu/streaming-md/gromacs
cd gromacs
git checkout tags/imdv3-sans-testsFor build instructions, see the GROMACS installation instructions
New MDP file options (subject to change as we work with GROMACS developers):
IMD-group = <group> ; Use 'System' to send the entire system via IMD (inherited from IMDv2)
IMD-version = <2 | 3> ; Defaults to 2 for backwards compatibility
IMD-nst = <nst> ; Number of integration steps between simulation frames communicated via IMD, defaults to 100
IMD-time = <yes | no> ; Whether to send time and step information via IMD, defaults to 'no'
IMD-box = <yes | no> ; Whether to send box dimension information via IMD, defaults to 'no'
IMD-coords = <yes | no> ; Whether to send atomic coordinate information via IMD, defaults to 'no'
IMD-vels = <yes | no> ; Whether to send atomic velocities information via IMD, defaults to 'no'
IMD-forces = <yes | no> ; Whether to send atomic forces information via IMD, defaults to 'no'
IMD-unwrap = <yes | no> ; Whether to unwrap molecules to make them appear whole, defaults to 'no'
IMD-energies = <yes | no> ; Whether to send system energy information via IMD, defaults to 'no'
Note that new options will not be used if "IMD-version" is set to 2.
mdrun command line options for IMD are inherited from IMDv2, see gmx-mdrun
First, pull the container:
# CPU-only build
docker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu
# CUDA build
docker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-gpuTo run LAMMPS, do:
# CPU
docker run -v /path/to/input/files:/home/conda:rw -p 8889:8889 \
ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu bash -c 'lmp < </path/to/infile>'
# GPU
docker run -v /path/to/input/files:/home/conda:rw --runtime=nvidia --gpus=all -p 8889:8889 \
ghcr.io/becksteinlab/streaming-md-docker:main-common-gpu bash -c 'lmp < </path/to/infile>'IMDv3 was added to LAMMPS in the 4 Feb-2025 release and is avalailable in any newer release as well.
Build and installation instructions are available in the LAMMPS installation instructions
Original options in the IMD fix are available here.
With our modifications:
fix ID group-ID imd <imd_port> [trate <imd_trate>] [version (2|3)] [unwrap (on|off)] [fscale <imd_fscale>] [time (on|off)] [box (on|off)] [coordinates (on|off)] [velocities (on|off)] [forces (on|off)]
'version' will default to 2 for backward compatibility, in which case the new options (time, box, positions, etc) will have no effect.
Due to restrictions on distributing NAMD, we are unable to provide a pre-built docker image. However, IMDv3-enabled NAMD is available on the official NAMD GitLab repository. One can register and gain access to the GitLab repository by filling out the form on the NAMD website.
NAMD can then be built from source by following the instructions here.
IMD based options/settings can be set in the NAMD input configuration file.
Previously available options for IMD version 2 in NAMD are available here.
The following new options are available as a part of the IMDv3 implementation:
IMDversion 3 # IMD version -- 2 for VMD and 3 for latest protocol implementation, defaults to 2
# IMD session info settings
IMDsendPositions yes # IMDsendPositions -- sending positions of entire system
IMDsendEnergies yes # IMDsendEnergies -- sending energies and bonded, non-bonded and other contributions
IMDsendTime yes # IMDsendTime -- sending time information (time, dt, step)
IMDsendBoxDimensions yes # IMDsendBoxDimensions -- sending box dimensions (lattice vectors a, b, c)
# If box dimensions are not defined, default unit box is sent
IMDsendVelocities yes # IMDsendVelocities -- sending velocities of entire system
IMDsendForces yes # IMDsendForces -- sending forces on all atoms
IMDwrapPositions yes # IMDwrapPositions -- wrapping positions to box; applicable when IMDsendPositions is yes
When IMDversion is set to 2, the new options (IMDsendTime, IMDsendBoxDimensions, IMDsendVelocities, IMDsendForces, IMDwrapPositions) will have no effect.
The latest MDAnalysis version (2.10.0+) includes a IMDv3 streaming data reader (IMDReader) that uses the imdclient package to connect to IMDv3-compatible simulation engines.
For detailed usage and installation instructions, see the MDAnalysis and imdclient documentation: