{"id":23948642,"url":"https://github.com/mdanalysis/imd-workshop-2024","last_synced_at":"2025-04-12T21:26:59.867Z","repository":{"id":259115043,"uuid":"875050237","full_name":"MDAnalysis/imd-workshop-2024","owner":"MDAnalysis","description":"Materials for the virtual 2024 MDAnalysis IMD streaming workshop.","archived":false,"fork":false,"pushed_at":"2024-12-18T00:57:47.000Z","size":26712,"stargazers_count":7,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-04-08T07:02:03.338Z","etag":null,"topics":["gromacs","lammps","mdanalysis","namd","python","streaming"],"latest_commit_sha":null,"homepage":"","language":"Jupyter Notebook","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MDAnalysis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-19T01:28:00.000Z","updated_at":"2025-03-10T09:21:11.000Z","dependencies_parsed_at":"2024-12-20T08:38:25.300Z","dependency_job_id":null,"html_url":"https://github.com/MDAnalysis/imd-workshop-2024","commit_stats":{"total_commits":58,"total_committers":6,"mean_commits":9.666666666666666,"dds":0.2931034482758621,"last_synced_commit":"7e22c6151bfea67a4234f275efaa3f0a83bcfd99"},"previous_names":["becksteinlab/imd-workshop-2024","ljwoods2/imd-workshop-2024","mdanalysis/imd-workshop-2024"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MDAnalysis%2Fimd-workshop-2024","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MDAnalysis%2Fimd-workshop-2024/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MDAnalysis%2Fimd-workshop-2024/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MDAnalysis%2Fimd-workshop-2024/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MDAnalysis","download_url":"https://codeload.github.com/MDAnalysis/imd-workshop-2024/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248633640,"owners_count":21136894,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["gromacs","lammps","mdanalysis","namd","python","streaming"],"created_at":"2025-01-06T10:43:15.574Z","updated_at":"2025-04-12T21:26:59.838Z","avatar_url":"https://github.com/MDAnalysis.png","language":"Jupyter Notebook","funding_links":[],"categories":[],"sub_categories":[],"readme":"Welcome to the MDAnalysis 2024 trajectory streaming workshop! \nFor the interactive activity, see [interactive activity](#interactive-activity).\nIf you're interested in using our tools after the workshop and watching a recording, see [post workshop](#post-workshop)\n\n##### Table of Contents  \n\n- [Workshop agenda](#workshop-agenda)\n- [Interactive activity](#interactive-activity)\n  - [1. Codespace environment setup](#1-codespace-environment-setup)\n    - [i. Github codespaces in the browser (recommended)](#i-github-codespaces-in-the-browser-recommended)\n    - [ii. Github codespaces tunnel from your IDE (VSCode and Pycharm)](#ii-github-codespaces-tunnel-from-your-ide-vscode-and-pycharm)\n      - [VSCode](#vscode)\n      - [Pycharm](#pycharm)\n    - [iii. Local codespace in IDE (VSCode only) (slow, not recommend)](#iii-local-codespace-in-ide-vscode-only-slow-not-recommend)\n  - [2. Getting started with the activity](#2-getting-started-with-the-activity)\n- [Post-workshop](#post-workshop)\n  - [Workshop recording and materials](#workshop-recording-and-materials)\n  - [Using IMDv3-compatible simulation engines](#using-imdv3-compatible-simulation-engines)\n    - [GROMACS](#gromacs)\n      - [With docker](#with-docker)\n      - [From source](#from-source)\n      - [New options](#new-options)\n    - [LAMMPS](#lammps)\n      - [With docker](#with-docker-1)\n      - [From source](#from-source-1)\n      - [New options](#new-options-1)\n    - [NAMD](#namd)\n\n\n# Workshop agenda\n\nIf 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. \n\n| Topic | Duration | Code | Presentation\n| --- | --- | --- | --- |\n| 👋 Welcome  | 5 min |\n| 📦 MDAnalysis mission \u0026 ecosystem | 15 min | | [presentations/00-MDAnalysis_mission_and_ecosystem-MacDermottOpeskin.pdf](presentations/00-MDAnalysis_mission_and_ecosystem-MacDermottOpeskin.pdf)\n| 🖼️ Streaming: big picture  | 15 min | | [presentations/01-Streaming_Big_Picture-Heyden.pdf](presentations/01-Streaming_Big_Picture-Heyden.pdf)\n| 👀 Streaming: first look | 10 min | [streaming-101/LAMMPS/MDAnalysis/demo.ipynb](streaming-101/LAMMPS/MDAnalysis/demo.ipynb) | [presentations/01-Streaming_First_Look-Heyden.pdf](presentations/01-Streaming_First_Look-Heyden.pdf)\n| ❓ Q\u0026A: Streaming overview  | 5 min |\n| 📦 Streaming: MD packages, IMDClient | 15 min | | [presentations/02-Streaming_MD_Packages_and_IMDClient-Thirumalaiswamy.pdf](presentations/02-Streaming_MD_Packages_and_IMDClient-Thirumalaiswamy.pdf)\n| 👀 Demo: Multiple analyses on NAMD simulation stream | 10 min | [namd-demos/rmsd-rdf/rmsd-rdf.ipynb](namd-demos/rmsd-rdf/rmsd-rdf.ipynb)\n| 💤 Break | 10 min |\n| 🎯 Activity: Write your own stream analysis  | 40 min | See [Interactive activity](#interactive-activity)\n| 📦 Streaming: MDAnalysis functionality | 10 min | | [presentations/03-Streaming_MDAnalysis_Functionality-Woods.ipynb](presentations/03-Streaming_MDAnalysis_Functionality-Woods.ipynb)\n| ❓ Q\u0026A: Streaming with MDAnalysis | 5 min |\n| 👀 Application: Velocity correlation functions and 2PT | 10 min | [gromacs-demos/vdos/demo.ipynb](gromacs-demos/vdos/demo.ipynb) | [presentations/04-Application_Velocity_correlation_functions_and_2PT-Cho.pdf](presentations/04-Application_Velocity_correlation_functions_and_2PT-Cho.pdf)\n| 👀 Application: Ion channel permeation | 10 min | [namd-demos/ion-flux/ion-flux.ipynb](namd-demos/ion-flux/ion-flux.ipynb) | [presentations/04-Application_Ion_channel_permeation-Cho.pdf](presentations/04-Application_Ion_channel_permeation-Cho.pdf)\n| ❓ Q\u0026A: Applications | 5 min |\n| 🔮 Future direction | 5 min | | [presentations/05-Future_Directions-Heyden.pdf](presentations/05-Future_Directions-Heyden.pdf)\n| 📖 Open Forum | 20 min |\n| 🚪 Closing | 5 min |\n\n\n# Interactive activity\n\nTo get started, we recommend using VSCode\nin the browser with the Github codespace we've provided \nwhich includes all the tools you'll need to get started with live\nsimulation streaming.\n\n## 1. Codespace environment setup\n\n### i. Github codespaces in the browser (recommended)\n\nThe easiest way is to simply use this repository to create a codespace.\nA workshop environment will be created and VSCode will automatically run in your browser.\n\nDuplicate this tab so you will still have access\nto these instructions when the codespace is launched.\n\nSelect the green \"Code\" button and then create a codespace:\n\n![alt text](.media/browser_1.png)\n![alt text](.media/browser_2.png)\n\nYou're done! The codespace will launch in the current tab. Move on to section 2 to get started with the [activity](#2-getting-started-with-the-activity).\n\n### ii. Github codespaces tunnel from your IDE (VSCode and Pycharm)\n\nYou can use your own IDE to spin up and connect to a codespace (which GitHub will host). \n\n#### VSCode\n\nIf you have VSCode installed, you can install the \n[codespace extension](https://marketplace.visualstudio.com/items?itemName=GitHub.codespaces). \n\nAfter installing, you'll see the \"remote explorer\" icon on the left.\nSign in if you aren't already.\n\n![alt text](.media/ide_1.png)\n\nSelect the dropdown arrow to select \"Github codespaces\" and\nthen select the \"+\" to create a new codespace.\n\n![alt text](.media/ide_2.png)\n\nA dialog will appear. For the repository, enter \"ljwoods2/imd-workshop-2024\". For the branch, select \"main\"\nFor the machine type, select \"2 cores, 8GB RAM, 32 GB storage\"\n\nAfter that, VSCode will automatically launch a new window which is executing in the codespace workshop environment.\nTo troubleshoot, see the documentation [here](https://docs.github.com/en/codespaces/developing-in-a-codespace/using-github-codespaces-in-visual-studio-code).\n\n#### Pycharm\n\nA codespace extension is also available for [Pycharm](https://plugins.jetbrains.com/plugin/20060-github-codespaces).\n\n### iii. Local codespace in IDE (VSCode only) (slow, not recommend)\n\nYou can also run the workshop activity locally if you have the [devcontainers VScode extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)\nand [docker](https://docs.docker.com/engine/install/) installed. \n\nAfter docker is installed \u0026 enabled and your user has been added to the docker group, run:\n```bash\ngit clone https://github.com/ljwoods2/imd-workshop-2024.git\ncode imd-workshop-2024\n```\nIn VSCode, enter CTRL+SHIFT+P and type: \"Dev Containers: Open Folder in Container...\" and select\nthe root of the cloned repo as the folder path. A new window will open which is executing \nin the workshop activity codespace.\n\n## 2. Getting started with the activity\n\nFirst, open the \"activity/activity.ipynb\" jupyter notebook from this repo in your codespace environment.\n\n![alt text](.media/codespace_1.png)\n\nBefore running any code, click the \"Select kernel\" button\nin the upper right corner of the jupyter notebook. \n\n![alt text](.media/codespace_2.png)\n\nSelect \"Python environments\" and then the \"workshop\" environment.\n\n![alt text](.media/codespace_3.png)\n![alt text](.media/codespace_4.png)\n\nNow you're ready to start the activity! Follow the instructions in the notebook to complete the activity.\n\n# Post-workshop\n\nIf you are interested in using our tools, please feel free to reach out for support, bug reports, or for sharing your ideas!\n\nThe best way to reach us is on the [MDAnalysis Discord](https://discord.gg/fXTSfDJyxE) in the '#streaming' channel. You can also reach out via email (workshops@mdanalysis.org)\n\n## Workshop recording and materials\n\n* You can watch the [MDAnalysis Streaming Online Workshop Recording](https://www.youtube.com/watch?v=fjBTvnEADGs) from the MDAnalysis channel on YouTube.\n* All workshop materials are available in _this_ repository and are linked from the [Workshop Agenda](#workshop-agenda), including presentations and code.\n* 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).\n\n## Using IMDv3-compatible simulation engines\n\nFor docker usage, ensure [docker](https://docs.docker.com/engine/install/) is installed and the [nvidia container toolkit](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/index.html) is installed if using GPU builds.\n\n### GROMACS\n\n#### With docker\n\n\nFirst, pull the container:\n\n```bash\n# CPU-only build\ndocker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu\n\n# CUDA build\ndocker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-gpu\n```\n\nTo run GROMACS, do:\n\n```bash\n# CPU\ndocker run -v /path/to/input/files:/home/conda:rw -p 8889:8889 \\\n    ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu bash -c 'gmx \u003ccmd\u003e'\n\n# GPU\ndocker run -v /path/to/input/files:/home/conda:rw --runtime=nvidia --gpus=all -p 8889:8889 \\\n    ghcr.io/becksteinlab/streaming-md-docker:main-common-gpu bash -c 'gmx \u003ccmd\u003e'\n```\n\n#### From source\n\nThe modified codes are available in [this GROMACS fork](https://gitlab.com/ljwoods2/gromacs).\n\nFirst, clone in the repo:\n```\ngit clone https://gitlab.com/ljwoods2/gromacs.git\ngit checkout imd-v3\n```\n\nFor build instructions, see the [GROMACS installation instructions](https://manual.gromacs.org/documentation/current/install-guide/index.html)\n\n#### New options\n\nNew MDP file options (subject to change as we work with GROMACS developers):\n```\nIMD-group               = \u003cgroup\u003e ; Use 'System' to send the entire system via IMD (inherited from IMDv2)\nIMD-version             = \u003c2 | 3\u003e ; Defaults to 2 for backwards compatibility\nIMD-nst                 = \u003cnst\u003e   ; Number of integration steps between simulation frames communicated via IMD, defaults to 100\nIMD-time                = \u003cyes | no\u003e ; Whether to send time and step information via IMD, defaults to 'no'\nIMD-box                 = \u003cyes | no\u003e ; Whether to send box dimension information via IMD, defaults to 'no'\nIMD-coords              = \u003cyes | no\u003e ; Whether to send atomic coordinate information via IMD, defaults to 'no'\nIMD-vels                = \u003cyes | no\u003e ; Whether to send atomic velcities information via IMD, defaults to 'no'\nIMD-forces              = \u003cyes | no\u003e ; Whether to send atomic forces information via IMD, defaults to 'no'\nIMD-unwrap              = \u003cyes | no\u003e ; Whether to unwrap molecules to make them appear whole, defaults to 'no'\nIMD-energies            = \u003cyes | no\u003e ; Whether to send system energy information via IMD, defaults to 'no'\n```\nNote that new options will not be used if \"IMD-version\" is set to 2.\n\n`mdrun` command line options for IMD are inherited from IMDv2, see [gmx-mdrun](https://manual.gromacs.org/current/onlinehelp/gmx-mdrun.html)\n\n### LAMMPS\n\n#### With docker\n\nFirst, pull the container:\n\n```bash\n# CPU-only build\ndocker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu\n\n# CUDA build\ndocker pull ghcr.io/becksteinlab/streaming-md-docker:main-common-gpu\n```\n\nTo run LAMMPS, do:\n\n```bash\n# CPU\ndocker run -v /path/to/input/files:/home/conda:rw -p 8889:8889 \\\n    ghcr.io/becksteinlab/streaming-md-docker:main-common-cpu bash -c 'lmp \u003c \u003c/path/to/infile\u003e'\n\n# GPU\ndocker run -v /path/to/input/files:/home/conda:rw --runtime=nvidia --gpus=all -p 8889:8889 \\\n    ghcr.io/becksteinlab/streaming-md-docker:main-common-gpu bash -c 'lmp \u003c \u003c/path/to/infile\u003e'\n```\n\n#### From source\n\nThe modified codes are available in [this LAMMPS fork](https://github.com/ljwoods2/lammps).\n\nFirst, clone in the repo:\n```\ngit clone https://github.com/ljwoods2/lammps.git\ngit checkout imd-v3-integration\n```\n\nBuild instructions are available in the [LAMMPS installation instructions](https://docs.lammps.org/Install.html)\n\n#### New options\n\nOriginal options in the IMD fix are available [here](https://docs.lammps.org/fix_imd.html).\n\nWith our modifications:\n\n```\nfix ID group-ID imd \u003cimd_port\u003e [trate \u003cimd_trate\u003e] [version (2|3)] [unwrap (on|off)] [fscale \u003cimd_fscale\u003e] [time (on|off)] [box (on|off)] [coordinates (on|off)] [velocities (on|off)] [forces (on|off)]\n```\n\n'version' will default to 2 for backward compatibility, in which case the new options (time, box, positions, etc) will have no effect.\n\n### NAMD\n\nDue to restrictions on distributing NAMD, we are unable to provide a pre-built docker image. However, we provide a patch for NAMD 3.0 to enable IMDv3 compatibility.\n\n#### IMDv3 patch\n\nOne can register for and download the NAMD 3.0 source code from the [NAMD website](https://www.ks.uiuc.edu/Development/Download/download.cgi?UserID=\u0026AccessCode=\u0026ArchiveID=1712).\n\nThe IMDv3 patch is available as a `*.diff` file in this [repository](https://github.com/amruthesht/namd-3.0-IMDv3-patch). To apply the patch, navigate to the root directory of the NAMD source code and run:\n\n```\n  cd /path/to/namd-3.0-source-repo\n  patch -p1 \u003c /path/to/namd-3_0-IMDv3.diff\n```\n\nOnce this is done, the source code will be patched with the new IMDv3 protocol. Detailed compile and build instructions can be found in the `IMDv3-dev.md` file in the patched repository.\n\n#### New options\n\nIMD based options/settings can be set in the NAMD input configuration file.\n\nPreviously available options for IMD version 2 in NAMD are available [here](https://www.ks.uiuc.edu/Research/namd/3.0/ug/node49.html).\n\nThe following new options are available as a part of the IMDv3 protocol:\n\n```bash\n# IMD version -- 2 for VMD and 3 for latest protocol, defaults to 2\nIMDversion     3\n# IMD session info settings\n# IMDsendPositions -- sending positions of entire system\nIMDsendPositions        yes\n# IMDsendEnergies -- sending energies and bonded, non-bonded and other contributions\nIMDsendEnergies     yes\n# IMDsendTime -- sending time information (time, dt, step)\nIMDsendTime        yes\n# IMDsendBoxDimensions -- sending box dimensions (lattice vectors a, b, c)\n# If box dimensions are not defined, default unit box is sent\nIMDsendBoxDimensions       yes\n# IMDsendVelocities -- sending velocities of entire system\nIMDsendVelocities       yes\n# IMDsendForces -- sending forces on all atoms\nIMDsendForces      yes\n# IMDwrapPositions -- wrapping positions to box; applicable when IMDsendPositions is yes\nIMDwrapPositions       yes\n```\n\nWhen `IMDversion` is set to 2, the new options (`IMDsendTime`, `IMDsendBoxDimensions`, `IMDsendVelocities`, `IMDsendForces`, `IMDwrapPositions`) will have no effect.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdanalysis%2Fimd-workshop-2024","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmdanalysis%2Fimd-workshop-2024","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmdanalysis%2Fimd-workshop-2024/lists"}