Convert#

Converting a molecular system into another form or multiple forms

In the context of MolSysMT, a molecular system can have different ‘forms’. Therefore, the library provides a function to convert a system from one form into another. This function is molsysmt.basic.convert().

Hint

Visit the section User guide > Introduction > Molecular System > Forms in case you are not familiar with the concept of “form” in MolSysMT.

Added in version 1.0.0.

How this function works#

API documentation

Follow this link for a detailed description of the input arguments, raised errors, and returned objects of this function:molsysmt.basic.convert().

To have a first approach to molsysmt.basic.convert(), the following example illustrates how the function operates in a simple context: the conversion of a molecular system from its form to a different form.

import molsysmt as msm

molsys_A = '181L'
molsys_B = msm.convert(molsys_A, to_form='181L.h5msm')
molsys_C = msm.convert(molsys_B)
molsys_D = msm.convert(molsys_C, to_form='string:pdb_text')
molsys_E = msm.convert(molsys_D, to_form='mdtraj.Trajectory')
molsys_F = msm.convert(molsys_E, to_form='nglview.NGLWidget')
molsys_G = msm.convert(molsys_F, to_form='openmm.Topology')
molsys_H = msm.convert(molsys_G, to_form='string:amino_acids_3')

Tip

All methods defined in the molsysmt.basic module can be invoked also from the main level of the library. Hence, molsysmt.convert() is the same method as molsysmt.basic.convert().

Tip

The default output form of molsysmt.basic.convert() is the native molsysmt.MolSys.

The molecular system was converted from the form “string:pdb_id” to “string:aminoacids3” passing through some intermediate forms: “string:pdb_id” \(\rightarrow\) “molsysmt.MolSys” \(\rightarrow\) “string:pdb_text” \(\rightarrow\) “mdtraj.Trajectory” \(\rightarrow\) “nglview.NGLWidget” \(\rightarrow\) “openmm.Topology” \(\rightarrow\) “string:aminoacids3”. We can have a look to each form with the help of molsysmt.basic.info():

msm.info(molsys_F)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_waters	n_ions	n_small_molecules	n_proteins	n_structures
nglview.NGLWidget	1441	302	141	1	141	5	136	2	2	1	1

Finally, the conversion can be done over the entire system or over a part of it. The input argument selection works with most of the MolSysMT methods, and molsysmt.basic.convert() is not an exception. Let’s see how a simple selection can be applied during conversion.

molsys = msm.convert('181L', to_form='string:pdb_text', selection='molecule_name=="BENZENE"')

print(molsys)

HEADER    MOLECULAR SYSTEM                        12-APR-25       
REMARK   1 Created by MolSysMT version 1.0 on 12-APR-2025 at 21:02:58
CRYST1   60.900   60.900   97.000  90.00  90.00 120.00
ATOM   1300 C1   BNZ A 400      25.978   5.327   4.779  0.00  0.00           C
ATOM   1301 C2   BNZ A 400      26.395   5.074   3.499  0.00  0.00           C
ATOM   1302 C3   BNZ A 400      27.340   5.860   2.902  0.00  0.00           C
ATOM   1303 C4   BNZ A 400      27.837   6.921   3.569  0.00  0.00           C
ATOM   1304 C5   BNZ A 400      27.420   7.196   4.856  0.00  0.00           C
ATOM   1305 C6   BNZ A 400      26.498   6.379   5.469  0.00  0.00           C
END

Multiple items into one#

Hint

Visit the section User guide > Introduction > Molecular System > Items in case you are not familiar with the concept of “item” in MolSysMT.

Sometimes the molecular system comes from the combination of multiple items with different forms. For example, we can have two files with topology and coordinates to be converted into a single molecular item:

prmtop_file = msm.systems['pentalanine']['pentalanine.prmtop']
inpcrd_file = msm.systems['pentalanine']['pentalanine.inpcrd']

msm.info(prmtop_file)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_waters	n_peptides	n_structures
file:prmtop	5207	1722	1716	1	1716	2	1715	1	None

msm.info(inpcrd_file)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_structures
file:inpcrd	5207	None	None	None	None	None	1

molsys = msm.convert([prmtop_file, inpcrd_file], to_form='molsysmt.MolSys')

msm.info(molsys)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_waters	n_peptides	n_structures
molsysmt.MolSys	5207	1722	1716	1	1716	2	1715	1	1

An item into multiple ones#

Hint

Visit the section User guide > Introduction > Molecular System > Items in case you are not familiar with the concept of “item” in MolSysMT.

The way to convert multiple items into one was illustrated in the previous section. Let’s see now how to produce more than a single item with different forms just in one line:

molsys = msm.systems['pentalanine']['traj_pentalanine.h5']

topology, structures = msm.convert(molsys, to_form=['molsysmt.Topology','molsysmt.Structures'])

msm.info(topology)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_peptides	n_structures
molsysmt.Topology	62	7	1	1	1	1	1	None

msm.info(structures)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_structures
molsysmt.Structures	62	None	None	None	None	None	5000

msm.info([topology, structures])

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_peptides	n_structures
['molsysmt.Topology', 'molsysmt.Structures']	62	7	1	1	1	1	1	5000

Let`s now visualize the combination of both forms to double check that they were properly converted:

msm.view([topology, structures], structure_indices=3500, standard=True, viewer='NGLView')

Supported conversions#

msm.supported.conversions(from_form='mdtraj.Trajectory', to_form_type='string')

	string:alphafold_id	string:amino_acids_1	string:amino_acids_3	string:pdb_id	string:pdb_text
mdtraj.Trajectory	False	True	True	False	False

msm.supported.conversions(from_form='mdtraj.Trajectory', to_form_type='file', as_rows='to')

	mdtraj.Trajectory
file:bcif	False
file:bcif.gz	False
file:cif	False
file:crd	False
file:dcd	False
file:gro	False
file:h5	False
file:h5msm	False
file:inpcrd	False
file:mmtf	False
file:mol2	False
file:msmpk	False
file:pdb	True
file:prmtop	False
file:psf	False
file:trjpk	False
file:xtc	True
file:xyznpy	False

from_list=['pytraj.Trajectory','MDAnalysis.Universe']
to_list=['mdtraj.Trajectory', 'openmm.Topology']
msm.supported.conversions(from_form=from_list, to_form=to_list, as_rows='from')

	mdtraj.Trajectory	openmm.Topology
MDAnalysis.Universe	True	False
pytraj.Trajectory	False	False