CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/pypi-mdanalysis

An object-oriented toolkit to analyze molecular dynamics trajectories.

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

index.mddocs/

MDAnalysis - Python Toolkit for Molecular Dynamics Analysis

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.

Package Information

Package Name: MDAnalysis
Version: Available through MDAnalysis.__version__
License: GNU Lesser General Public License v2.1 or later
Python Compatibility: Python 3.8+

Installation:

pip install MDAnalysis

Key Dependencies:

  • NumPy (≥1.20.0)
  • matplotlib (≥1.5.1)
  • networkx (≥1.0)

Core Imports

The essential components are available directly from the main package:

import MDAnalysis as mda

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

# Exception classes
from MDAnalysis.exceptions import (
    SelectionError, NoDataError, ApplicationError,
    SelectionWarning, MissingDataWarning
)

# Units handling
import MDAnalysis.units

# Analysis modules (imported as needed)
import MDAnalysis.analysis.align
import MDAnalysis.analysis.rms
import MDAnalysis.analysis.distances

Basic Usage

Creating a Universe

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

def __init__(self, topology, *coordinates, **kwargs):
    """
    Create a Universe from topology and coordinate files.
    
    Parameters
    ----------
    topology : str or file-like
        Topology file (PSF, PDB, GRO, TPR, etc.) containing atomic structure
    *coordinates : str or file-like, optional
        Trajectory file(s) (DCD, XTC, TRR, etc.) with coordinate time series
    **kwargs : dict
        Additional keyword arguments passed to readers
        
    Returns
    -------
    Universe
        Universe object ready for analysis
    """

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

Selecting Atoms

MDAnalysis provides a powerful selection language similar to VMD:

# Basic selections
protein = u.select_atoms("protein")
ca_atoms = u.select_atoms("name CA")
backbone = u.select_atoms("backbone")

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

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

# Boolean operations
flexible_region = u.select_atoms("protein and not (name CA or name C or name N)")

Trajectory Analysis Loop

# Iterate through trajectory frames
for ts in u.trajectory:
    print(f"Frame {ts.frame}, Time: {ts.time} ps")
    
    # Perform per-frame analysis
    com = protein.center_of_mass()
    rgyr = protein.radius_of_gyration()
    
# Random access to specific frames
u.trajectory[0]    # First frame
u.trajectory[-1]   # Last frame
u.trajectory[100:200:10]  # Slice with step

Architecture

MDAnalysis is built around several key architectural concepts:

Universe-Centric Design

  • Universe: Central container holding topology and trajectory data
  • Topology: Static molecular structure (bonds, atom types, residues)
  • Trajectory: Time-dependent coordinate data with random/sequential access

Hierarchical Group System

  • AtomGroup: Primary analysis unit, represents collections of atoms
  • ResidueGroup: Collections of residues with aggregate properties
  • SegmentGroup: Collections of segments (chains/molecules)
  • All groups support set operations (union, intersection, difference)

Modular I/O System

  • Readers: Format-specific trajectory readers with unified interface
  • Writers: Output coordinate data to various formats
  • Parsers: Extract topology information from structure files
  • Automatic format detection based on file extensions

Analysis Framework

  • AnalysisBase: Standard workflow for trajectory-based calculations
  • Results: Standardized storage for analysis outputs
  • Parallel analysis support through multiprocessing

Capabilities

Core Functionality

Essential operations for molecular system manipulation and basic analysis.

Key Features:

  • Universe creation and manipulation
  • Atom selection using powerful query language
  • Group operations and transformations
  • Basic geometric calculations
# Universe operations
u = mda.Universe("topology.pdb", "trajectory.xtc") 
merged = mda.Merge(u1.atoms, u2.atoms)  # Combine systems

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

# Basic analysis
center = protein.center_of_mass()
radius = protein.radius_of_gyration() 
coords = protein.positions  # Current frame coordinates

Core Functionality Documentation

File I/O and Format Support

Comprehensive support for reading and writing molecular structure and trajectory data.

Supported Formats:

  • Structure: PDB, PSF, GRO, TPR, MOL2, PQR, CRD
  • Trajectory: DCD, XTC, TRR, TNG, NetCDF, LAMMPS, AMBER
  • Analysis Output: PDB, GRO, XYZ, DCD, XTC
# Reading various formats
u1 = mda.Universe("system.psf", "trajectory.dcd")  # CHARMM
u2 = mda.Universe("topol.tpr", "traj.xtc")        # GROMACS  
u3 = mda.Universe("structure.prmtop", "mdcrd")     # AMBER

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

# Trajectory writing
with mda.Writer("output.dcd", u.atoms.n_atoms) as W:
    for ts in u.trajectory:
        W.write(u.atoms)

File I/O and Format Support Documentation

Analysis Tools

Specialized analysis classes for common molecular dynamics calculations.

Available Analyses:

  • Structural alignment and RMSD calculations
  • Distance analysis and contact maps
  • Hydrogen bonding analysis
  • Radial distribution functions
  • Principal component analysis
  • Mean squared displacement
from MDAnalysis.analysis import align, rms, distances

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

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

# Structural alignment
alignto_result = align.alignto(mobile, reference, select="name CA")

Analysis Tools Documentation

Topology Handling

Management of molecular topology including bonds, angles, and connectivity.

Key Capabilities:

  • Topology attribute management
  • Bond/angle/dihedral manipulation
  • Connectivity guessing and validation
  • Topology merging and modification
# Topology queries
print(u.atoms.bonds)     # Bond connectivity
print(u.atoms.angles)    # Angle definitions
print(u.atoms.dihedrals) # Dihedral angles

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

# Topology attributes
u.add_TopologyAttr('masses', [12.0] * u.atoms.n_atoms)
masses = u.atoms.masses

Topology Handling Documentation

Coordinate Transformations

Geometric transformations and coordinate manipulations for structural analysis.

Transformation Types:

  • Translation, rotation, and scaling
  • Structural alignment and fitting
  • Periodic boundary condition handling
  • Coordinate wrapping and unwrapping
# Basic transformations
protein.translate([10.0, 0.0, 0.0])  # Move along x-axis
protein.rotate([[1,0,0], [0,0,1], [0,1,0]])  # Rotation matrix
protein.transform(transformation_matrix)  # General transformation

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

# Periodic boundary handling
protein.wrap(compound="residues")      # Wrap by residue
protein.unwrap(compound="fragments")   # Unwrap fragments

Coordinate Transformations Documentation

Selection Language

Powerful atom selection system supporting complex queries and geometric criteria.

Selection Capabilities:

  • Atom property-based selections
  • Residue and segment selections
  • Geometric proximity selections
  • Boolean logic combinations
# Property-based selections
u.select_atoms("name CA CB CG")
u.select_atoms("resname ALA VAL LEU ILE")  
u.select_atoms("resid 1-100 and name CA")

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

# Complex boolean selections  
u.select_atoms("protein and not backbone")
u.select_atoms("(resname ALA or resname GLY) and name CA")

Selection Language Documentation

Units and Utilities

Unit conversion, mathematical utilities, and helper functions.

Key Utilities:

  • Unit system management and conversions
  • Mathematical operations for MD analysis
  • Distance calculations and neighbor searching
  • Utility functions for common tasks
import MDAnalysis.units as units

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

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

# Distance calculations
from MDAnalysis.lib.distances import distance_array, self_distance_array
distances = distance_array(coords1, coords2, box=u.dimensions)

Units and Utilities Documentation

Auxiliary Data Handling

Time-series data management and integration with trajectory analysis.

Key Features:

  • Reading auxiliary data from XVG and EDR files
  • Automatic alignment with trajectory timesteps
  • Integration with trajectory iteration workflows
  • Support for multiple auxiliary data sources
from MDAnalysis.auxiliary import auxreader, get_auxreader_for
from MDAnalysis.auxiliary import XVGReader, EDRReader

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

# Access during iteration
for ts in u.trajectory:
    force_value = ts.aux.force

Auxiliary Data Documentation

Interoperability and Converters

Seamless conversion between MDAnalysis and other molecular modeling packages.

Supported Libraries:

  • RDKit for cheminformatics workflows
  • ParmEd for parameter and topology editing
  • OpenMM for high-performance simulations
  • Bidirectional conversion capabilities
from MDAnalysis.converters import RDKit, ParmEd, OpenMM

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

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

# Convert to OpenMM topology
topology, positions = u.atoms.convert_to("OPENMM")

Interoperability and Converters Documentation

Getting Started

  1. Install MDAnalysis: pip install MDAnalysis

  2. Import and create Universe:

    import MDAnalysis as mda
u = mda.Universe("topology.pdb", "trajectory.xtc")

  3. Select atoms of interest:

    protein = u.select_atoms("protein")

  4. Analyze trajectory:

    for ts in u.trajectory:
    # Perform analysis on each frame
    center = protein.center_of_mass()

  5. Use specialized analysis tools:

    from MDAnalysis.analysis import rms
R = rms.RMSD(u, u, select="backbone")
R.run()

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

docs

analysis-tools.md

auxiliary-data.md

converters.md

coordinate-transformations.md

core-functionality.md

index.md

io-formats.md

selection-language.md

topology-handling.md

units-utilities.md

tile.json