Editable#

Creating an editable molecular system builder to modify or construct topologies.

The function molsysmt.build.editable() serves as the primary entry point to work with the native molsysmt.MolSysBuilder container (detailed in the MolSysBuilder guide). While standard molecular system containers in MolSysMT are immutable for performance and safety, a builder provides a mutable staging environment to dynamically add, edit, or remove atoms, bonds, groups, and chains before materializing a final native molsysmt.MolSys instance via .build().

Added in version 1.0.0.

API documentation

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

Basic usage#

Let’s show how to make an existing molecular system editable using Met-enkephalin:

import molsysmt as msm

molsys = msm.convert(msm.systems['Met-enkephalin']['met_enkephalin.h5msm'])

Note

Demo Systems Catalog

This tutorial uses demonstration datasets provided by MolSysMT. To explore the full catalog of bundled systems, forms, and file paths, visit the Demo Systems guide.

Calling molsysmt.build.editable() on molsys returns an active molsysmt.MolSysBuilder instance:

builder = msm.build.editable(molsys)

type(builder)

molsysmt.native.molsys_builder.MolSysBuilder

Inspecting the builder#

A builder can be queried directly with standard functions like molsysmt.basic.get() or molsysmt.basic.info():

msm.get(builder, n_atoms=True, n_bonds=True, n_chains=True)

[72, 73, 1]

Modifying topology and bonds#

Using the builder, we can add new covalent bonds between specific atom indices:

builder.add_bond(atom_index_1=0, atom_index_2=10, bond_order=1, bond_type='covalent')

2

We can also remove specific covalent bonds by specifying their bond indices, or remove all bonds by passing 'all':

builder.remove_bonds([0, 1])

Residue groups can be reassigned to a new chain:

builder.assign_groups_to_new_chain(group_indices=[0, 1], chain_id='B', chain_name='B')

1

Materializing the final molecular system#

Once edits are completed, calling .build() compiles and validates the staging model into a new native molsysmt.MolSys object:

new_molsys = builder.build()

msm.info(new_molsys, element='chain')
index id name n atoms n groups n components molecule index molecule type entity index entity name
0 1 A 28 2 2 [0] ['peptide'] [0] ['peptide 0']
1 B B 44 3 1 [0] ['peptide'] [0] ['peptide 0']

Assembling a molecular system from scratch#

Calling molsysmt.build.editable() without arguments creates an empty builder ready for incremental model declaration:

empty_builder = msm.build.editable()

We declare atoms, group them into residues and chains, add covalent bonds, and assign 3D coordinates:

import numpy as np

empty_builder.add_atom(atom_name='N', atom_type='N')
empty_builder.add_atom(atom_name='CA', atom_type='C')
empty_builder.add_atom(atom_name='C', atom_type='C')
empty_builder.add_group(atom_indices=[0, 1, 2], group_name='ALA', group_id='1', group_type='amino_acid')
empty_builder.add_chain(group_indices=[0], chain_id='A', chain_name='A')
empty_builder.add_bond(atom_index_1=0, atom_index_2=1, bond_order=1, bond_type='covalent')
empty_builder.add_bond(atom_index_1=1, atom_index_2=2, bond_order=1, bond_type='covalent')

coords = np.array([[[0.0, 0.0, 0.0], [0.145, 0.0, 0.0], [0.245, 0.12, 0.0]]]) * msm.pyunitwizard.unit('nm')
empty_builder.set_coordinates(coords)

scratch_molsys = empty_builder.build()

msm.info(scratch_molsys)
form n_atoms n_groups n_components n_chains n_molecules n_entities n_peptides n_structures
molsysmt.MolSys 3 1 1 1 1 1 1 1

See also

Related Tools & References