Module 17: Merging and Growing Systems#

Welcome back, Apprentice Master. In Module 16: Structural Operations, you mastered spatial coordinate transformations and alignment using msm.structure. Now we transition to system composition: Merging and Growing Systems.

Complex molecular simulations frequently require assembling systems from separate components: fusing a receptor protein and a co-crystallized ligand, appending solvent ions into a box, or joining multiple coordinate structures. MolSysMT provides four dedicated composition functions in msm.basic categorized along two operational axes:

Composition Axis	Out-of-Place (Returns New Object)	In-Place (Modifies Target)
Topology	`msm.merge()`	`msm.add()`
Structures	`msm.concatenate_structures()`	`msm.append_structures()`

Learning Outcomes

By the end of this module, you will be able to:

Fuse independent molecular components out-of-place into a new complex using msm.merge().
Add elements and molecules into an existing system in-place using msm.add().
Concatenate multi-structure coordinate data out-of-place using msm.concatenate_structures().
Append new coordinate structures into an existing system in-place using msm.append_structures().

1. Merging Independent Systems#

Let’s begin by importing MolSysMT, loading our T4 Lysozyme system, and isolating the protein and co-crystallized small molecules into separate native MolSys objects.

import molsysmt as msm
from molsysmt import systems

# Load full T4 Lysozyme system
lysozyme = msm.convert(systems['T4 lysozyme L99A']['181l.bcif.gz'], to_form='molsysmt.MolSys')

# Extract protein component and small molecule ligands
protein = msm.extract(lysozyme, selection='molecule_type == "protein"')
ligand = msm.extract(lysozyme, selection='molecule_type == "small molecule"')

The function msm.merge() takes a list of independent molecular systems and fuses their topology and spatial coordinates into a new combined system object, leaving the input systems unchanged:

# Merge protein and ligand out-of-place into a new complex
complex_sys = msm.merge([protein, ligand])

# Inspect topology summary of the merged complex
msm.info(complex_sys)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_small_molecules	n_proteins	n_structures
molsysmt.MolSys	1303	164	3	3	3	3	2	1	1

Hint

msm.merge(): Fuses multiple independent molecular systems into a new target system in memory. See API doc: molsysmt.basic.merge().

2. Adding Elements In-Place#

While msm.merge() creates a new combined system from a list, msm.add() appends selected elements or molecules directly into an existing target system in place:

# Print atom count of target protein before addition
print(f"Protein atom count before addition: {msm.get(protein, element='system', n_atoms=True)}")

# Add ligand elements directly into the protein system in place
msm.add(protein, ligand)

# Print updated atom count
print(f"Protein atom count after in-place addition: {msm.get(protein, element='system', n_atoms=True)}")

Protein atom count before addition: 1289
Protein atom count after in-place addition: 1303

Hint

msm.add(): Appends elements or molecules from a source system into an existing target system. See API doc: molsysmt.basic.add().

3. Concatenating Structures#

When you have multiple coordinate datasets representing sequential conformations for systems with matching topology, msm.concatenate_structures() combines their 3D structures out-of-place into a new system along the structure axis:

# Synthesize an Alanine dipeptide peptide model
snap1 = msm.build.build_peptide('AceAlaNme')

# Create a shifted conformer using spatial translation
snap2 = msm.structure.translate(snap1, translation='[0.1, 0.1, 0.1] nanometers')

# Concatenate coordinate structures out-of-place into a multi-structure object
multi_struct_sys = msm.concatenate_structures([snap1, snap2])

n_structs = msm.get(multi_struct_sys, element='system', n_structures=True)
print(f"Concatenated system total structure count: {n_structs}")

Concatenated system total structure count: 2

Hint

msm.concatenate_structures(): Combines 3D coordinate structures from a list of matching systems into a new system. See API doc: molsysmt.basic.concatenate_structures().

4. Appending Structures In-Place#

To append new coordinate structures directly into an existing system along the structure axis in place, use msm.append_structures():

# Print structure count of snap1 before appending
print(f"Structure count of snap1 before appending: {msm.get(snap1, element='system', n_structures=True)}")

# Append snap2 coordinate structures directly into snap1 in place
msm.append_structures(snap1, snap2)

# Print updated structure count
print(f"Structure count of snap1 after in-place appending: {msm.get(snap1, element='system', n_structures=True)}")

Structure count of snap1 before appending: 1
Structure count of snap1 after in-place appending: 2

Hint

msm.append_structures(): Appends 3D coordinate structures from a source system onto an existing target system in place. See API doc: molsysmt.basic.append_structures().

🏆 Challenge 17: The Systems Builder#

Load T4 Lysozyme (systems['T4 lysozyme L99A']['181l.bcif.gz']).
Extract the protein (molecule_type == 'protein') and small molecule ligands (molecule_type == 'small molecule').
Merge them out-of-place using msm.merge([protein, ligand]) into complex_sys.
Synthesize a peptide using msm.build.build_peptide('AceAlaNme') and concatenate two conformations using msm.concatenate_structures().
Verify atom counts and structure counts of all resulting objects.

Building up molecular systems allows you to construct complex simulation models. In Module 18: Surgical Extraction and Removal, we will learn how to isolate and eliminate specific components using msm.extract() and msm.remove().