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

Overview

Eval results

Files

Interoperability and Converters

Name: tessl/pypi-mdanalysis
Author: tessl

MDAnalysis provides comprehensive conversion capabilities to facilitate interoperability with other molecular modeling and cheminformatics packages. The converters module enables seamless translation between MDAnalysis objects and external library formats.

Overview

The converters module supports bidirectional conversion between MDAnalysis and:

RDKit: Cheminformatics toolkit for molecular manipulation
ParmEd: Parameter/topology editor for molecular simulations
OpenMM: High-performance molecular simulation toolkit

Each converter provides both parser capabilities (reading external formats into MDAnalysis) and converter capabilities (exporting MDAnalysis data to external formats).

Core Imports

import MDAnalysis.converters as converters

# Specific converter imports
from MDAnalysis.converters import RDKit, RDKitParser
from MDAnalysis.converters import ParmEd, ParmEdParser  
from MDAnalysis.converters import OpenMM, OpenMMParser

# Base converter class
from MDAnalysis.converters.base import ConverterBase

Capabilities

RDKit Integration

Conversion between MDAnalysis and RDKit molecule objects for cheminformatics workflows.

class RDKitReader:
    """
    Coordinate reader for RDKit molecule objects.
    
    Allows reading coordinates from RDKit Mol objects into MDAnalysis.
    """
    
    def __init__(self, filename, **kwargs):
        """
        Create RDKit coordinate reader.
        
        Parameters
        ----------
        filename : rdkit.Chem.rdchem.Mol
            RDKit molecule object
        **kwargs
            Additional reader options
        """

class RDKitParser:
    """
    Topology parser for RDKit molecule objects.
    
    Extracts topology information from RDKit Mol objects.
    """
    
    def __init__(self, filename, **kwargs):
        """
        Create RDKit topology parser.
        
        Parameters
        ----------
        filename : rdkit.Chem.rdchem.Mol
            RDKit molecule object
        **kwargs
            Additional parser options
        """

class RDKitConverter(ConverterBase):
    """
    Convert MDAnalysis AtomGroup to RDKit Mol object.
    """
    
    lib = "RDKIT"
    
    def convert(self, obj, cache=dict(), NoImplicitHs=True, 
                max_iter=200, force=True):
        """
        Convert AtomGroup or Universe to RDKit Mol object.
        
        Parameters
        ----------
        obj : AtomGroup or Universe
            MDAnalysis object to convert
        cache : dict, optional
            Cache for conversion optimization
        NoImplicitHs : bool, optional
            Whether to exclude implicit hydrogens (default True)
        max_iter : int, optional
            Maximum iterations for bond perception (default 200)
        force : bool, optional
            Whether to force conversion even with warnings (default True)
            
        Returns
        -------
        rdkit.Chem.rdchem.Mol
            RDKit molecule object
            
        Examples
        --------
        >>> mol = protein.convert_to("RDKIT")
        >>> mol = u.atoms.convert_to("RDKIT", NoImplicitHs=False)
        """

ParmEd Integration

Conversion with ParmEd for advanced parameter and topology manipulation.

class ParmEdParser:
    """
    Topology parser for ParmEd Structure objects.
    
    Reads topology information from ParmEd Structure into MDAnalysis.
    """
    
    def __init__(self, filename, **kwargs):
        """
        Create ParmEd topology parser.
        
        Parameters
        ----------
        filename : parmed.Structure
            ParmEd Structure object
        **kwargs
            Additional parser options
        """

class ParmEdReader:
    """
    Coordinate reader for ParmEd Structure objects.
    
    Reads coordinates from ParmEd Structure into MDAnalysis.
    """
    
    def __init__(self, filename, **kwargs):
        """
        Create ParmEd coordinate reader.
        
        Parameters
        ----------
        filename : parmed.Structure
            ParmEd Structure object
        **kwargs
            Additional reader options
        """

class ParmEdConverter(ConverterBase):
    """
    Convert MDAnalysis objects to ParmEd Structure.
    """
    
    lib = "PARMED"
    
    def convert(self, obj, box=None):
        """
        Convert AtomGroup or Universe to ParmEd Structure.
        
        Parameters
        ----------
        obj : AtomGroup or Universe
            MDAnalysis object to convert
        box : array-like, optional
            Box dimensions [a, b, c, alpha, beta, gamma]
            
        Returns
        -------
        parmed.Structure
            ParmEd Structure object
            
        Examples
        --------
        >>> struct = protein.convert_to("PARMED")
        >>> struct = u.atoms.convert_to("PARMED", box=u.dimensions)
        """

OpenMM Integration

Conversion with OpenMM for high-performance molecular dynamics simulations.

class OpenMMParser:
    """
    Topology parser for OpenMM objects.
    
    Extracts topology from OpenMM Topology and System objects.
    """
    
    def __init__(self, filename, **kwargs):
        """
        Create OpenMM topology parser.
        
        Parameters
        ----------
        filename : simtk.openmm.app.Topology or tuple
            OpenMM Topology object or (Topology, positions) tuple
        **kwargs
            Additional parser options
        """

class OpenMMReader:
    """
    Coordinate reader for OpenMM Simulation objects.
    
    Reads coordinates from OpenMM trajectories and states.
    """
    
    def __init__(self, filename, **kwargs):
        """
        Create OpenMM coordinate reader.
        
        Parameters
        ----------
        filename : simtk.openmm.app.Simulation or tuple
            OpenMM Simulation object or (Topology, positions) tuple
        **kwargs
            Additional reader options
        """

class OpenMMAppConverter(ConverterBase):
    """
    Convert MDAnalysis objects to OpenMM App objects.
    """
    
    lib = "OPENMM"
    
    def convert(self, obj, positions=True):
        """
        Convert to OpenMM Topology and positions.
        
        Parameters
        ----------
        obj : AtomGroup or Universe
            MDAnalysis object to convert
        positions : bool, optional
            Whether to include positions (default True)
            
        Returns
        -------
        tuple
            (openmm.app.Topology, positions) tuple
            
        Examples
        --------
        >>> topology, positions = protein.convert_to("OPENMM")
        """

Base Converter Framework

Foundation classes for implementing custom converters.

class ConverterBase:
    """
    Base class for all converters.
    
    Provides the framework for converting MDAnalysis objects to external formats.
    """
    
    lib = None  # Override with target library name
    
    def convert(self, obj):
        """
        Convert MDAnalysis object to target format.
        
        Parameters
        ----------
        obj : AtomGroup or Universe
            Object to convert
            
        Returns
        -------
        Converted object in target library format
        """
        raise NotImplementedError("Subclasses must implement convert method")
    
    def __repr__(self):
        """String representation of converter."""
        return f"<{self.__class__.__name__}>"

Usage Examples

RDKit Workflows

import MDAnalysis as mda
from rdkit import Chem

# Load RDKit molecule into MDAnalysis
mol = Chem.MolFromSmiles('CCO')
mol = Chem.AddHs(mol)
AllChem.EmbedMolecule(mol)

u = mda.Universe(mol)
print(f"Universe: {u}")
print(f"Atoms: {u.atoms.n_atoms}")

# Convert back to RDKit
rdkit_mol = u.atoms.convert_to("RDKIT")
smiles = Chem.MolToSmiles(rdkit_mol)
print(f"SMILES: {smiles}")

# Work with conformers
multi_conf_mol = Chem.MolFromMol2File("conformers.mol2", removeHs=False)
u_conf = mda.Universe(multi_conf_mol)
print(f"Conformers: {len(u_conf.trajectory)}")

# Process each conformer
for ts in u_conf.trajectory:
    rdkit_conf = u_conf.atoms.convert_to("RDKIT")
    # Perform RDKit calculations on each frame

ParmEd Integration

import MDAnalysis as mda
import parmed as pmd

# Load from ParmEd Structure
struct = pmd.load_file('system.prmtop', 'trajectory.nc')
u = mda.Universe(struct)

# Modify in MDAnalysis
protein = u.select_atoms('protein') 
protein.atoms.masses *= 1.1  # Modify masses

# Convert back to ParmEd
modified_struct = u.atoms.convert_to("PARMED")

# Use ParmEd tools
modified_struct.strip(':WAT')  # Remove water
modified_struct.save('protein_only.pdb')

# Parameter manipulation
for atom in modified_struct.atoms:
    if atom.element_name == 'H':
        atom.charge *= 0.9  # Scale hydrogen charges

OpenMM Simulation Setup

import MDAnalysis as mda
from simtk.openmm.app import *
from simtk.openmm import *
from simtk.unit import *

# Load system in MDAnalysis
u = mda.Universe('system.pdb')

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

# Set up OpenMM simulation
forcefield = ForceField('amber14-all.xml', 'amber14/tip3pfb.xml')
system = forcefield.createSystem(topology, 
                                 nonbondedMethod=PME,
                                 nonbondedCutoff=1*nanometer)

integrator = LangevinIntegrator(300*kelvin, 1/picosecond, 2*femtoseconds)
simulation = Simulation(topology, system, integrator)
simulation.context.setPositions(positions)

# Run simulation
simulation.minimizeEnergy()
simulation.step(1000)

# Convert back to MDAnalysis for analysis
state = simulation.context.getState(getPositions=True)
positions = state.getPositions()
u_sim = mda.Universe((topology, positions))

Cross-Platform Workflows

import MDAnalysis as mda
from rdkit import Chem
import parmed as pmd

# Start with SMILES
smiles = 'CC(=O)NC1=CC=C(C=C1)O'  # Acetaminophen
mol = Chem.MolFromSmiles(smiles)
mol = Chem.AddHs(mol)
AllChem.EmbedMolecule(mol)

# RDKit -> MDAnalysis
u = mda.Universe(mol)

# Add missing topology information
u.add_TopologyAttr('masses')
u.add_TopologyAttr('charges')

# MDAnalysis -> ParmEd for parameter assignment
struct = u.atoms.convert_to("PARMED")

# Use ParmEd for advanced parameterization
# struct.load_parameters(some_parameter_set)

# ParmEd -> MDAnalysis for analysis
u_param = mda.Universe(struct)

# Perform MDAnalysis-based analysis
com = u_param.atoms.center_of_mass()
rgyr = u_param.atoms.radius_of_gyration()

# MDAnalysis -> OpenMM for simulation
topology, positions = u_param.atoms.convert_to("OPENMM")
# Continue with OpenMM simulation setup...

Custom Converter Implementation

from MDAnalysis.converters.base import ConverterBase

class CustomLibraryConverter(ConverterBase):
    lib = "CUSTOMLIB"
    
    def convert(self, obj, **kwargs):
        """Convert to custom library format."""
        # Extract MDAnalysis data
        positions = obj.positions
        masses = obj.masses if hasattr(obj, 'masses') else None
        
        # Create custom library object
        custom_obj = CustomLibrary.Molecule()
        custom_obj.set_coordinates(positions)
        if masses is not None:
            custom_obj.set_masses(masses)
            
        return custom_obj

# Register converter
# Converter automatically registers via metaclass

Format Compatibility

Library	Parser	Reader	Converter	Dependencies
RDKit	✓	✓	✓	rdkit-pypi
ParmEd	✓	✓	✓	parmed
OpenMM	✓	✓	✓	openmm

Conversion Considerations

Data Fidelity

Bond perception: Automatic bond detection may differ between libraries
Stereochemistry: Chirality information may not be preserved
Aromaticity: Aromatic bond representation varies between libraries
Formal charges: Charge assignment methods differ

Performance

Large systems may require significant memory during conversion
Bond perception algorithms can be computationally expensive
Caching mechanisms available for repeated conversions

Error Handling

try:
    rdkit_mol = atoms.convert_to("RDKIT")
except Exception as e:
    print(f"Conversion failed: {e}")
    # Fallback to alternative method or simplified representation

Validation

# Validate conversion by round-trip
original_atoms = u.atoms
rdkit_mol = original_atoms.convert_to("RDKIT")
u2 = mda.Universe(rdkit_mol)
roundtrip_atoms = u2.atoms

# Compare key properties
assert original_atoms.n_atoms == roundtrip_atoms.n_atoms
assert np.allclose(original_atoms.positions, roundtrip_atoms.positions, atol=1e-3)

Integration with Analysis Workflows

The converters seamlessly integrate with MDAnalysis analysis capabilities:

from MDAnalysis.analysis import rms

# RDKit conformer analysis
mol = Chem.SDMolSupplier('conformers.sdf', removeHs=False)
u = mda.Universe(mol)

# Standard MDAnalysis analysis
R = rms.RMSD(u, u, select='name CA')
R.run()

# Convert results back for RDKit processing
for i, rmsd_val in enumerate(R.results.rmsd):
    u.trajectory[i]
    current_mol = u.atoms.convert_to("RDKIT")
    # Use RDKit tools on each conformer

Install with Tessl CLI