Module 1: The Form-Agnostic Philosophy#

Welcome, Apprentice Master. Your journey into the heart of molecular matter starts here.

In this course, you are not just learning a software library; you are learning to talk to atoms. You are building your own virtual laboratory where the walls of file formats and software limitations simply do not exist.

The most important concept in MolSysMT is the Form. In traditional Computational Biology, you are often a prisoner of your file format: if you have a PDB file, you use one library; if you have an OpenMM object, you use another.

MolSysMT breaks these chains. It treats every molecular data structure as a Form. Whether it is a file on disk, an object in memory, or a string of text, MolSysMT sees them all as “Molecular Systems”.

Glossary: Form

A Form is any specific way molecular data is stored or represented (e.g., a .pdb file, an mdtraj.Trajectory object, or a molsysmt.MolSys native system).

1. The Universal Sampler: msm.get_form()#

Let’s begin by importing MolSysMT and its built-in demonstration systems repository.

import molsysmt as msm
from molsysmt import systems

Tip

Import Convention: The core developers of MolSysMT strongly recommend importing the package as msm (import molsysmt as msm).

Note

Demo Systems Repository: molsysmt.systems is a built-in catalog of curated demonstration and test molecular systems shipped directly with MolSysMT. See the user-foundations guide for more details.

To demonstrate that MolSysMT doesn’t care about the size or the source, let’s look at four systems from our specialized paths. Notice how we use the same msm.get_form() function for all of them.

# 🔬 Path A: Alzheimer (Amyloid-Beta Fibril from PDB ID)
alzheimer_system = 'pdb_id:2BEG'

# ♻️ Path B: Enzyme Engineering (Triosephosphate Isomerase from internal database)
enzyme_system = systems['TcTIM']['1tcd.h5msm']

# 💊 Path C: Antiviral Hunter (Barnase-Barstar Complex)
antiviral_system = systems['Barnase-Barstar']['barnase_barstar.h5msm']

# ⚡ Path D: Nano-Mechanic (POPC Membrane)
membrane_system = systems['POPC membrane']['popc_membrane.dcd']

systems_list = [alzheimer_system, enzyme_system, antiviral_system, membrane_system]
for sys in systems_list:
    print(f"Form found: {msm.get_form(sys)}")

Form found: string:pdb_id
Form found: file:h5msm
Form found: file:h5msm
Form found: file:dcd

Hint

msm.get_form(): Identifies and returns the structural or data form of a given molecular system item (e.g. 'string:pdb_id', 'file:h5msm', 'openmm.Topology'). See API doc: molsysmt.basic.get_form().

2. The Power of Conversion: msm.convert()#

You are never stuck in a form. You can convert() any system into another. But here is the magic: while the Form changes, the Content remains invariant.

# Let's convert the Enzyme (H5MSM file) into an OpenMM Topology
openmm_topo = msm.convert(enzyme_system, to_form='openmm.Topology')

print(f"New form: {msm.get_form(openmm_topo)}")

New form: openmm.Topology

Hint

msm.convert(): Converts a molecular system between any of the 89 supported forms in memory or on disk. See API doc: molsysmt.basic.convert().

3. Quick Reports with msm.info()#

How do we know the system is still the same after conversion? We use msm.info() to get a styled biological inventory.

# Report of the converted OpenMM object
msm.info(openmm_topo)
form n_atoms n_groups n_components n_chains n_molecules n_entities n_waters n_proteins n_structures
openmm.Topology 3983 662 167 4 167 3 165 2 None

Notice that the biological content is identical. msm.info() is your go-to tool for a quick human-readable audit.

Hint

msm.info(): Displays a human-readable summary of a molecular system’s topology, structures, and attributes. See API doc: molsysmt.basic.info().

🏆 Challenge 1: The Form Hunter#

  1. Load the T4 Lysozyme training ground using strictly its PDB ID: 'pdb_id:181L'.

  2. Check its form using msm.get_form().

  3. Use msm.info() to see what’s inside (How many protein molecules? How many waters?).

  4. Convert it into a Sequence string (to_form='string:amino_acids_3').

If you succeed, you are ready for Module 2: Molecular Attributes.