Form Teleportation: Seamless Conversions

Task: Convert a molecular system across different libraries (OpenMM, MDAnalysis, NetworkX) while checking the semantics each target can represent.

One of MolSysMT’s greatest strengths is its ability to bridge disparate ecosystems. This recipe shows you how to “teleport” your data into other tools for specialized analysis.

import molsysmt as msm
from molsysmt import systems

# Load the T4 Lysozyme (bcif.gz form)
lysozyme = systems['T4 lysozyme L99A']['181l.bcif.gz']

1. To OpenMM (Simulation Ready)

Convert to a standard OpenMM Topology for physics-based work. When a report contains issues, inspect each issue’s scope, attribute, kind, and reason before accepting target-model loss. Preflight work runs only when return_report=True or strict=True requests it. Treat is_exhaustive=True as a route-specific guarantee backed by an explicit schema audit. Native Structures, Topology, and MolSys dictionary conversions report unsupported structural, chemical-state, or mechanical payloads before conversion. Direct native projections also inspect the source form’s complete declared contract: for example, projecting MolSys to topology reports present coordinates, while projecting it to structures reports present topology. The shared atom_index and n_atoms attributes preserve the meaning of the atom inventory across topology-only, structures-only, and combined native forms. When a workflow passes through StructuresDict, optional temperature and energy series retain their units and selected structure order; total_energy remains derived instead of being duplicated. A selected conversion to MolSys builds matching topological and structural atom axes instead of retaining an unselected anonymous topology. The audited XYZ, DCD, and XTC routes preserve the coordinate payload and requested structure order; atom subsets are canonicalized, while format-specific omissions are surfaced by the conversion report.

omm_topo, conversion_report = msm.convert(
    lysozyme, to_form='openmm.Topology', return_report=True
)
print(f"Teleported to OpenMM. Atom count: {omm_topo.getNumAtoms()}")
print(
    conversion_report.outcome,
    conversion_report.audited_scopes,
    conversion_report.is_exhaustive,
    conversion_report.issues,
)

Teleported to OpenMM. Atom count: 1441
equivalent ()

2. To MDAnalysis (Selected Topology and Structures)

An MDAnalysis Universe can be selected with MolSysMT syntax and materialized without changing the source Universe’s active frame.

trp_cage_pdb = systems['Trp-Cage']['1l2y.pdb']
mda_universe = msm.convert(trp_cage_pdb, to_form='MDAnalysis.Universe')
mda_alpha_carbons = msm.convert(
    mda_universe,
    to_form='MDAnalysis.Universe',
    selection='atom_name=="CA"',
)
print(f"Selected MDAnalysis atoms: {mda_alpha_carbons.atoms.n_atoms}")

3. To NetworkX (Topological Graph)

Convert the covalent bonds into a mathematical graph for advanced network analysis.

graph = msm.convert(lysozyme, to_form='networkx.Graph')
print(f"Teleported to Graph. Edge count: {graph.number_of_edges()}")

Teleported to Graph. Edge count: 1322

4. To BioPython (Sequence Focus)

Convert to a BioPython SeqRecord for sequence-alignment workflows.

biopython_seq = msm.convert(lysozyme, to_form='biopython.SeqRecord')
print(f"Teleported to BioPython. Sequence: {biopython_seq.seq[:30]}...")

Teleported to BioPython. Sequence: MNIFEMLRIDEGLRLKIYKDTEGYYTIGIG...