Add UserGuide documentation for IMDReader - reading streaming data with IMDv3 protocol #427
Description
User story
As a user familiar with MDAnalysis, but unaware of the new IMDReader-IMDv3 feature, I would want to easily discover and learn how to use the streaming reader with the new IMDv3 protocol support without having to dig through API docs.
Additional context
MDAnalysis is adding (recently added) support for real-time streaming via the IMDv3 protocol through the new IMDReader, but this feature is only documented in the API docs. Most users read the UserGuide to learn about MDA capabilities, so they're unlikely to discover this functionality. The current API docs assumes that users already know about streaming and focuses on technical details rather than helping them understand what it is, and when and how to use it.
This creates a discoverability gap for a feature that could change how users approach simulation analysis - enabling real-time monitoring, and in-situ analysis.
Proposed UserGuide Documentation Structure
1. Introduction: What is streaming?
- Brief explanation of IMDv3 protocol vs traditional file-based analysis
- Benefits: real-time monitoring, in-situ analysis et al.
2. When to use streaming?
- Real-time quality control and monitoring (Long-running simulations where early feedback is valuable)
- Adaptive sampling, selection
- Interactive visualization during simulation
- Avoid large data storage - in-situ analysis
3. Installation and setup
- Installing imdclient:
pip install imdclient - MD engine support status and configuration:
- GROMACS: example .mdp settings and mdrun flags
- LAMMPS: configuration examples
- NAMD: configuration examples
- Links to engine-specific documentation
4. Basic streaming example - how to use IMDReader
Basic example using streaming, something like ---
import MDAnalysis as mda
# Connect to running simulation
u = mda.Universe("topol.tpr", "imd://localhost:8889")
# Streaming loop
for ts in u.trajectory:
print streaming_info
# Your analysis code here
if some_stopping_condition:
break5. Additional features
Features that are available through IMDClient via the IMDReader
continue_after_disconnectbuffer_size- pause/resume? (not available directly)
6. Analysis workflows
- Integration with MDAnalysis analysis modules
(which analysis methods work/don't with IMDv3 MDA (limitations from StreamReaderBase) - Examples?
7. Complete working example
End-to-end workflow: GROMACS/NAMD/LAMMPS setup and streaming --> IMDReader --> visualization/analysis
8. Current limitations
- Limitations with accessing data
- implications for analysis usage
- (from streamreaderbase)
Above information needs to be updated as imd.rst under doc/source/formats/reference