0
# MDAnalysis - Python Toolkit for Molecular Dynamics Analysis
1

2
MDAnalysis is a comprehensive Python library for analyzing molecular dynamics (MD) trajectories. It provides a unified interface for reading trajectory data from various simulation packages, performing geometric and temporal analyses, and writing results back to standard formats.
3

4
## Package Information
5

6
**Package Name:** `MDAnalysis`  
7
**Version:** Available through `MDAnalysis.__version__`  
8
**License:** GNU Lesser General Public License v2.1 or later  
9
**Python Compatibility:** Python 3.8+
10

11
**Installation:**
12
```bash
13
pip install MDAnalysis
14
```
15

16
**Key Dependencies:**
17
- NumPy (≥1.20.0)
18
- matplotlib (≥1.5.1) 
19
- networkx (≥1.0)
20

21
## Core Imports
22

23
The essential components are available directly from the main package:
24

25
```python { .api }
26
import MDAnalysis as mda
27

28
# Core classes available at top level
29
from MDAnalysis import Universe, AtomGroup, ResidueGroup, SegmentGroup, Writer
30
from MDAnalysis import Merge  # For merging universes
31

32
# Exception classes
33
from MDAnalysis.exceptions import (
34
    SelectionError, NoDataError, ApplicationError,
35
    SelectionWarning, MissingDataWarning
36
)
37

38
# Units handling
39
import MDAnalysis.units
40

41
# Analysis modules (imported as needed)
42
import MDAnalysis.analysis.align
43
import MDAnalysis.analysis.rms
44
import MDAnalysis.analysis.distances
45
```
46

47
## Basic Usage
48

49
### Creating a Universe
50

51
The `Universe` class is the central entry point for all MDAnalysis workflows. It combines topology and trajectory data:
52

53
```python { .api }
54
def __init__(self, topology, *coordinates, **kwargs):
55
    """
56
    Create a Universe from topology and coordinate files.
57
    
58
    Parameters
59
    ----------
60
    topology : str or file-like
61
        Topology file (PSF, PDB, GRO, TPR, etc.) containing atomic structure
62
    *coordinates : str or file-like, optional
63
        Trajectory file(s) (DCD, XTC, TRR, etc.) with coordinate time series
64
    **kwargs : dict
65
        Additional keyword arguments passed to readers
66
        
67
    Returns
68
    -------
69
    Universe
70
        Universe object ready for analysis
71
    """
72

73
# Basic usage examples
74
u = mda.Universe("topology.psf", "trajectory.dcd")
75
u = mda.Universe("structure.pdb")  # Single frame from PDB
76
u = mda.Universe("topol.tpr", "traj.xtc", "traj2.xtc")  # Multiple trajectories
77
```
78

79
### Selecting Atoms
80

81
MDAnalysis provides a powerful selection language similar to VMD:
82

83
```python { .api }
84
# Basic selections
85
protein = u.select_atoms("protein")
86
ca_atoms = u.select_atoms("name CA")
87
backbone = u.select_atoms("backbone")
88

89
# Residue-based selections  
90
active_site = u.select_atoms("resid 23 45 67")
91
binding_pocket = u.select_atoms("resname HIS PHE TRP")
92

93
# Geometric selections
94
near_protein = u.select_atoms("around 5.0 protein")
95
water_shell = u.select_atoms("resname SOL and around 8.0 protein")
96

97
# Boolean operations
98
flexible_region = u.select_atoms("protein and not (name CA or name C or name N)")
99
```
100

101
### Trajectory Analysis Loop
102

103
```python { .api }
104
# Iterate through trajectory frames
105
for ts in u.trajectory:
106
    print(f"Frame {ts.frame}, Time: {ts.time} ps")
107
    
108
    # Perform per-frame analysis
109
    com = protein.center_of_mass()
110
    rgyr = protein.radius_of_gyration()
111
    
112
# Random access to specific frames
113
u.trajectory[0]    # First frame
114
u.trajectory[-1]   # Last frame
115
u.trajectory[100:200:10]  # Slice with step
116
```
117

118
## Architecture
119

120
MDAnalysis is built around several key architectural concepts:
121

122
### Universe-Centric Design
123
- **Universe**: Central container holding topology and trajectory data
124
- **Topology**: Static molecular structure (bonds, atom types, residues)
125
- **Trajectory**: Time-dependent coordinate data with random/sequential access
126

127
### Hierarchical Group System
128
- **AtomGroup**: Primary analysis unit, represents collections of atoms
129
- **ResidueGroup**: Collections of residues with aggregate properties  
130
- **SegmentGroup**: Collections of segments (chains/molecules)
131
- All groups support set operations (union, intersection, difference)
132

133
### Modular I/O System
134
- **Readers**: Format-specific trajectory readers with unified interface
135
- **Writers**: Output coordinate data to various formats
136
- **Parsers**: Extract topology information from structure files
137
- Automatic format detection based on file extensions
138

139
### Analysis Framework  
140
- **AnalysisBase**: Standard workflow for trajectory-based calculations
141
- **Results**: Standardized storage for analysis outputs
142
- Parallel analysis support through multiprocessing
143

144
## Capabilities
145

146
### Core Functionality
147
Essential operations for molecular system manipulation and basic analysis.
148

149
**Key Features:**
150
- Universe creation and manipulation
151
- Atom selection using powerful query language
152
- Group operations and transformations
153
- Basic geometric calculations
154

155
```python { .api }
156
# Universe operations
157
u = mda.Universe("topology.pdb", "trajectory.xtc") 
158
merged = mda.Merge(u1.atoms, u2.atoms)  # Combine systems
159

160
# Selection and grouping
161
protein = u.select_atoms("protein")
162
ca_atoms = protein.select_atoms("name CA")
163
binding_site = u.select_atoms("resid 23-45 and around 5.0 resname LIG")
164

165
# Basic analysis
166
center = protein.center_of_mass()
167
radius = protein.radius_of_gyration() 
168
coords = protein.positions  # Current frame coordinates
169
```
170

171
**[Core Functionality Documentation](./core-functionality.md)**
172

173
### File I/O and Format Support
174
Comprehensive support for reading and writing molecular structure and trajectory data.
175

176
**Supported Formats:**
177
- **Structure**: PDB, PSF, GRO, TPR, MOL2, PQR, CRD
178
- **Trajectory**: DCD, XTC, TRR, TNG, NetCDF, LAMMPS, AMBER
179
- **Analysis Output**: PDB, GRO, XYZ, DCD, XTC
180

181
```python { .api }
182
# Reading various formats
183
u1 = mda.Universe("system.psf", "trajectory.dcd")  # CHARMM
184
u2 = mda.Universe("topol.tpr", "traj.xtc")        # GROMACS  
185
u3 = mda.Universe("structure.prmtop", "mdcrd")     # AMBER
186

187
# Writing coordinate data
188
protein.write("protein_only.pdb")
189
u.atoms.write("all_atoms.gro")
190

191
# Trajectory writing
192
with mda.Writer("output.dcd", u.atoms.n_atoms) as W:
193
    for ts in u.trajectory:
194
        W.write(u.atoms)
195
```
196

197
**[File I/O and Format Support Documentation](./io-formats.md)**
198

199
### Analysis Tools
200
Specialized analysis classes for common molecular dynamics calculations.
201

202
**Available Analyses:**
203
- Structural alignment and RMSD calculations
204
- Distance analysis and contact maps
205
- Hydrogen bonding analysis
206
- Radial distribution functions
207
- Principal component analysis
208
- Mean squared displacement
209

210
```python { .api }
211
from MDAnalysis.analysis import align, rms, distances
212

213
# RMSD analysis
214
R = rms.RMSD(u, u, select="backbone")
215
R.run()
216
print(R.results.rmsd)  # Time series of RMSD values
217

218
# Distance analysis
219
dist_array = distances.distance_array(group1.positions, group2.positions)
220
contacts = distances.contact_matrix(protein.positions, cutoff=8.0)
221

222
# Structural alignment
223
alignto_result = align.alignto(mobile, reference, select="name CA")
224
```
225

226
**[Analysis Tools Documentation](./analysis-tools.md)**
227

228
### Topology Handling
229
Management of molecular topology including bonds, angles, and connectivity.
230

231
**Key Capabilities:**
232
- Topology attribute management
233
- Bond/angle/dihedral manipulation  
234
- Connectivity guessing and validation
235
- Topology merging and modification
236

237
```python { .api }
238
# Topology queries
239
print(u.atoms.bonds)     # Bond connectivity
240
print(u.atoms.angles)    # Angle definitions
241
print(u.atoms.dihedrals) # Dihedral angles
242

243
# Adding topology information
244
u.add_bonds([(0, 1), (1, 2), (2, 3)])  # Add bonds by atom indices
245
u.guess_bonds()  # Automatically guess bonds from distances
246

247
# Topology attributes
248
u.add_TopologyAttr('masses', [12.0] * u.atoms.n_atoms)
249
masses = u.atoms.masses
250
```
251

252
**[Topology Handling Documentation](./topology-handling.md)**
253

254
### Coordinate Transformations  
255
Geometric transformations and coordinate manipulations for structural analysis.
256

257
**Transformation Types:**
258
- Translation, rotation, and scaling
259
- Structural alignment and fitting
260
- Periodic boundary condition handling
261
- Coordinate wrapping and unwrapping
262

263
```python { .api }
264
# Basic transformations
265
protein.translate([10.0, 0.0, 0.0])  # Move along x-axis
266
protein.rotate([[1,0,0], [0,0,1], [0,1,0]])  # Rotation matrix
267
protein.transform(transformation_matrix)  # General transformation
268

269
# Alignment operations  
270
align.alignto(mobile, reference, select="name CA")
271
transformations.fit_rot_trans(mobile, reference)
272

273
# Periodic boundary handling
274
protein.wrap(compound="residues")      # Wrap by residue
275
protein.unwrap(compound="fragments")   # Unwrap fragments
276
```
277

278
**[Coordinate Transformations Documentation](./coordinate-transformations.md)**
279

280
### Selection Language
281
Powerful atom selection system supporting complex queries and geometric criteria.
282

283
**Selection Capabilities:**
284
- Atom property-based selections
285
- Residue and segment selections  
286
- Geometric proximity selections
287
- Boolean logic combinations
288

289
```python { .api }
290
# Property-based selections
291
u.select_atoms("name CA CB CG")
292
u.select_atoms("resname ALA VAL LEU ILE")  
293
u.select_atoms("resid 1-100 and name CA")
294

295
# Geometric selections
296
u.select_atoms("around 5.0 resname LIG")          # Within distance
297
u.select_atoms("spherical_layer 2.0 4.0 protein") # Spherical shell
298
u.select_atoms("sphlayer 2.0 4.0 protein")        # Alias for above
299

300
# Complex boolean selections  
301
u.select_atoms("protein and not backbone")
302
u.select_atoms("(resname ALA or resname GLY) and name CA")
303
```
304

305
**[Selection Language Documentation](./selection-language.md)**
306

307
### Units and Utilities
308
Unit conversion, mathematical utilities, and helper functions.
309

310
**Key Utilities:**
311
- Unit system management and conversions
312
- Mathematical operations for MD analysis
313
- Distance calculations and neighbor searching
314
- Utility functions for common tasks
315

316
```python { .api }
317
import MDAnalysis.units as units
318

319
# Unit conversions
320
units.convert(10.0, 'Angstrom', 'nm')  # Length conversion
321
units.convert(300.0, 'K', 'kJ/mol')    # Temperature to energy
322

323
# Base units in MDAnalysis
324
print(units.MDANALYSIS_BASE_UNITS)
325
# {'length': 'Angstrom', 'time': 'ps', 'energy': 'kJ/mol', ...}
326

327
# Distance calculations
328
from MDAnalysis.lib.distances import distance_array, self_distance_array
329
distances = distance_array(coords1, coords2, box=u.dimensions)
330
```
331

332
**[Units and Utilities Documentation](./units-utilities.md)**
333

334
### Auxiliary Data Handling
335
Time-series data management and integration with trajectory analysis.
336

337
**Key Features:**
338
- Reading auxiliary data from XVG and EDR files
339
- Automatic alignment with trajectory timesteps
340
- Integration with trajectory iteration workflows
341
- Support for multiple auxiliary data sources
342

343
```python { .api }
344
from MDAnalysis.auxiliary import auxreader, get_auxreader_for
345
from MDAnalysis.auxiliary import XVGReader, EDRReader
346

347
# Load auxiliary data
348
aux = auxreader('pullforce.xvg')
349
u.trajectory.add_auxiliary('force', aux)
350

351
# Access during iteration
352
for ts in u.trajectory:
353
    force_value = ts.aux.force
354
```
355

356
**[Auxiliary Data Documentation](./auxiliary-data.md)**
357

358
### Interoperability and Converters
359
Seamless conversion between MDAnalysis and other molecular modeling packages.
360

361
**Supported Libraries:**
362
- RDKit for cheminformatics workflows
363
- ParmEd for parameter and topology editing
364
- OpenMM for high-performance simulations
365
- Bidirectional conversion capabilities
366

367
```python { .api }
368
from MDAnalysis.converters import RDKit, ParmEd, OpenMM
369

370
# Convert to RDKit molecule
371
rdkit_mol = protein.convert_to("RDKIT")
372

373
# Convert to ParmEd structure  
374
parmed_struct = u.atoms.convert_to("PARMED")
375

376
# Convert to OpenMM topology
377
topology, positions = u.atoms.convert_to("OPENMM")
378
```
379

380
**[Interoperability and Converters Documentation](./converters.md)**
381

382
## Getting Started
383

384
1. **Install MDAnalysis**: `pip install MDAnalysis`
385

386
2. **Import and create Universe**:
387
   ```python
388
   import MDAnalysis as mda
389
   u = mda.Universe("topology.pdb", "trajectory.xtc")
390
   ```
391

392
3. **Select atoms of interest**:
393
   ```python
394
   protein = u.select_atoms("protein")
395
   ```
396

397
4. **Analyze trajectory**:
398
   ```python
399
   for ts in u.trajectory:
400
       # Perform analysis on each frame
401
       center = protein.center_of_mass()
402
   ```
403

404
5. **Use specialized analysis tools**:
405
   ```python
406
   from MDAnalysis.analysis import rms
407
   R = rms.RMSD(u, u, select="backbone")
408
   R.run()
409
   ```
410

411
For detailed examples and API documentation, explore the capability-specific documentation linked above.