Path A - Module 28: The MolSysBuilder API#

Sometimes, you need to create something that doesn’t exist in any file. Maybe you want to add dummy atoms to guide a simulation, or build a custom molecule from scratch.

MolSysMT provides the MolSysBuilder, a declarative API that allows you to construct systems step-by-step.

While editing, msm.get(builder, ...) can inspect the complete chemical/topological and structural state stored by the builder. Molecular-mechanics data and per-structure chemical-state associations are added to the materialized MolSys, not stored in the builder.

Conversions among MolSys, MolSysBuilder, and MolSysDict report fidelity exhaustively. In selected exports, atom order is canonical and structure_indices retains the requested order; strict=True rejects detected reduced-schema loss.

import numpy as np
import molsysmt as msm
from molsysmt import pyunitwizard as puw

builder = msm.MolSysBuilder()

1. Creating Editable Declared State#

MolSysBuilder() starts an empty declared system. Use msm.build.editable(molsys) instead when you need an editable copy of an existing native system.

print(f"Builder ready with {msm.get(builder, element='system', n_atoms=True)} declared atoms.")

2. Declaring Atoms, Hierarchy, and Geometry#

Topology is declared first. Atom-dependent arrays are then assigned with set_coordinates() before build() materializes a native system.

dummy = builder.add_atom(atom_name='DUM', atom_type='D')
group = builder.add_group([dummy], group_name='DUM')
builder.add_chain([group], chain_id='X')
molecule = builder.add_molecule([group], molecule_name='Marker')
builder.add_entity([molecule], entity_name='Scaffold')
builder.set_coordinates(puw.quantity(np.array([[0.0, 0.0, 0.0]]), 'nm'))
molsys = builder.build()
print(f"Built system with {msm.get(molsys, element='system', n_atoms=True)} atom.")

3. Building from Scratch#

You can also start from a completely empty system. This is the ultimate level of control.

new_builder = msm.MolSysBuilder()
hydrogen_1 = new_builder.add_atom(atom_name='H1', atom_type='H')
hydrogen_2 = new_builder.add_atom(atom_name='H2', atom_type='H')
new_builder.add_group([hydrogen_1, hydrogen_2], group_name='H2')
new_builder.add_bond(hydrogen_1, hydrogen_2, bond_order=1)
new_builder.set_coordinates(puw.quantity(np.array([[0.0, 0.0, 0.0], [0.0, 0.0, 0.074]]), 'nm'))
hydrogen = new_builder.build()
msm.info(hydrogen)

🏆 Path A Challenge: The Scaffold Builder#

  1. Create an empty MolSys object.

  2. Use the builder to add 3 atoms in a triangle shape (coordinates [0,0,0], [1,0,0], [0,1,0] in nm).

  3. Name the atoms A1, A2, and A3.

  4. Assign them to a residue named TRI and a chain named S.

  5. Visualize your triangular scaffold.

You now know how to build any molecular geometry! In Module 29, we will finish this phase by dealing with the complexities of the PDB format: Bioassemblies and AltLocs.