Module 4: Native Forms#

Welcome back, Apprentice Master. In Module 1 and Module 2, you discovered that MolSysMT treats every external file format or third-party object as a Form, while querying and modifying its internal data through Attributes.

While MolSysMT is form-agnostic, it is not homeless. When you want maximum computational speed, zero-copy structural queries, and complete control over your data, you rely on Native Forms.

At the center of this ecosystem is molsysmt.MolSys, a modular orchestrator that unifies domain-specific native objects: Topology (covalent graph & hierarchy), Structures (coordinates, boxes & trajectories), and MolecularMechanics (forcefield parameters, charges & energies).

Glossary: Native Form

A Native Form is any data structure built directly within MolSysMT (molsysmt.MolSys, molsysmt.Topology, molsysmt.Structures, molsysmt.TopologyDict, file:h5msm) designed for optimal memory layout and maximum analytical performance. See the user-foundations guide for a full list of native forms.

1. The Native Orchestrator: molsysmt.MolSys#

Let’s begin by importing MolSysMT, loading a molecular system, and converting it to MolSysMT’s primary in-memory native object: molsysmt.MolSys.

import molsysmt as msm
from molsysmt import systems

# Load T4 Lysozyme and convert it into the native MolSys object
lysozyme_file = systems['T4 lysozyme L99A']['181l.bcif.gz']
molsys = msm.convert(lysozyme_file, to_form='molsysmt.MolSys')

When inspecting molsys, notice the difference between Python’s internal class implementation (type()) and MolSysMT’s canonical form string (msm.get_form()):

print(f"Python class type : {type(molsys)}")
print(f"MolSysMT form name: {msm.get_form(molsys)}")

Python class type : <class 'molsysmt.native.molsys.MolSys'>
MolSysMT form name: molsysmt.MolSys

Hint

molsysmt.MolSys: The primary in-memory native container of MolSysMT. It orchestrates modular component objects (topology, structures, molecular_mechanics, and expanding domain modules). See API doc: molsysmt.native.MolSys().

2. Modular Domain Components: Topology, Structures, and MolecularMechanics#

Rather than storing all data in a single monolithic array, molsysmt.MolSys delegates domain responsibilities to specialized native component objects:

  • molsys.topology (molsysmt.Topology): Manages the covalent graph, atom names, element types, groups/residues, components, chains, molecules, entities, and chemical bonds. (Explored in depth in Module 05: Molecular Anatomy)

  • molsys.structures (molsysmt.Structures): Manages spatial coordinates array (n_structures, n_atoms, 3), periodic box vectors (n_structures, 3, 3), time steps, velocities, and frame observables. (Explored in depth in Module 21: Data Analyst & Module 40: The Physics Lab)

  • molsys.molecular_mechanics (molsysmt.MolecularMechanics): Manages forcefield definitions, formal charges, partial charges, non-bonded parameters, and potential energy.

These domains remain useful independently. For example, converting a molsysmt.Topology to molsysmt.MolSys produces a topology-only container with zero structures; MolSysMT does not invent coordinates. Consequently, converting that topology to a three-dimensional viewer requires explicit coordinates.

Let’s inspect the form of each component attribute inside our molsys instance:

print(f"Topology component form: {msm.get_form(molsys.topology)}")
print(f"Structures component form: {msm.get_form(molsys.structures)}")
print(f"Molecular Mechanics component form: {msm.get_form(molsys.molecular_mechanics)}")

Topology component form: molsysmt.Topology
Structures component form: molsysmt.Structures
Molecular Mechanics component form: molsysmt.MolecularMechanics

Hint

molsysmt.Topology: Native object representing the chemical and structural hierarchy (atoms, groups, chains, bonds). See API docs for native classes: molsysmt.native.Topology(), molsysmt.native.Structures(), and molsysmt.native.MolecularMechanics().

3. High-Performance Disk Storage: H5MSM Files (file:h5msm)#

The H5MSM format (file:h5msm) is the disk-based counterpart of molsysmt.MolSys. Built on top of HDF5, it stores system topology, trajectory coordinates, box vectors, and physical observables in binary form with maximum I/O performance.

Unlike third-party formats, H5MSM allows chunked execution and partial trajectory loading without materializing the full dataset into memory. (Trajectory I/O workflows are covered in Module 14: The Virtual Lab & Module 47: Pipeline Developer).

# Inspect an H5MSM file from the demo repository
h5msm_file = systems['T4 lysozyme L99A']['181l.h5msm']
print(f"Form of the file: {msm.get_form(h5msm_file)}")

Form of the file: file:h5msm

Hint

file:h5msm: Native disk-based HDF5 container for MolSysMT systems, supporting complete trajectory datasets and structural states. See User Guide: user-foundations.

4. Lightweight Native Dictionaries: TopologyDict, StructuresDict, and MolSysDict#

For high-speed Python pipelines, API serialization, or low-latency inspection, MolSysMT provides dictionary-based native forms:

  • molsysmt.TopologyDict: Lightweight dictionary containing pure topological arrays and connectivity maps.

  • molsysmt.StructuresDict: Lightweight dictionary containing raw coordinate arrays and frame observables.

  • molsysmt.MolSysDict: Dictionary representation bundling topology, structures, and mechanics data.

Because these forms use pure Python dictionaries, all internal data is transparently accessible via standard key lookup. Let’s convert molsys.topology into a TopologyDict and explore its data:

# Convert topology component to a native TopologyDict
topo_dict = msm.convert(molsys.topology, to_form='molsysmt.TopologyDict')

print(f"Form found: {msm.get_form(topo_dict)}")
print(f"Dictionary keys: {list(topo_dict.data.keys())}")
print(f"\nNumber of atom records: {len(topo_dict.data['atoms'])}")
print(f"Number of group records: {len(topo_dict.data['groups'])}")

Form found: molsysmt.TopologyDict
Dictionary keys: ['format', 'kind', 'version', 'metadata', 'atoms', 'groups', 'bonds', 'chains', 'molecules', 'entities']

Number of atom records: 1441
Number of group records: 302

Hint

molsysmt.TopologyDict: Lightweight native Python dictionary form holding topology attributes for zero-overhead iteration and serialization. See API doc: molsysmt.native.TopologyDict().

🏆 Challenge 4: The Native Architect#

  1. Load the SARS-CoV-2 Protease using its PDB ID: 'pdb_id:6LU7'.

  2. Convert it into a native molsysmt.MolSys object.

  3. Use msm.get_form() on its topology and structures attributes to verify their native forms.

  4. Convert the native object into a molsysmt.TopologyDict and inspect its 'atoms' key length.

Mastering native forms gives you maximum performance and flexibility. In Module 5: Combined Forms, we will learn how to compose systems using multiple complementary forms.