Add#

Adding elements of a molecular system into another molecular system.

Elements coming from different molecular systems can be added to a given system with the molsysmt.basic.add() function.

Added in version 1.0.0.

How this function works#

API documentation

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

Let’s show how this function works with three peptides defined as three different molecular systems: proline dipeptide (\(A\)), valine dipeptide (\(B\)), and lysine dipeptide (\(C\)).

import molsysmt as msm

molsys_A = msm.build.build_peptide('AceProNme')
molsys_B = msm.build.build_peptide('AceValNme')
molsys_C = msm.build.build_peptide('AceLysNme')

The molecular systems \(B\) and \(C\) need to be translated to avoid their overlapping once their elements are added to \(A\) -all systems are built centered around the origin-.

molsys_B = msm.structure.translate(molsys_B, translation='[-1.0, 0.0, 0.0] nanometers')
molsys_C = msm.structure.translate(molsys_C, translation='[1.0, 0.0, 0.0] nanometers')

Let’s see how \(A\) is defined before adding \(B\) and \(C\):

msm.info(molsys_A)

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_peptides	n_structures
molsysmt.MolSys	26	3	1	1	1	1	1	1

Now it is time to use molsysmt.basic.add():

msm.add(molsys_A, molsys_B)
msm.add(molsys_A, molsys_C)

Tip

All methods defined in the molsysmt.basic module can be invoked also from the main level of the library. Hence, molsysmt.add() is the same method as molsysmt.basic.add().

We first inspect how \(A\) is defined before adding \(B\) and \(C\). Once the addition is done, we expect \(A\) to show a larger count of atoms, groups, and residues.

msm.info(molsys_A, element='system')

form	n_atoms	n_groups	n_components	n_chains	n_molecules	n_entities	n_peptides	n_structures
molsysmt.MolSys	88	9	3	1	3	3	3	1

And we can also visualize it. Try rotating and zooming to observe the spatial separation between \(A\), \(B\), and \(C\).

# This cell is removed with the tag: "remove-input"
# As such, it will not be shown in documentation

nglview_htmlfile = '../../../../_static/nglview/add.html'

msm.view(molsys_A, standard=True)

Finally, if you prefer not to modify the original molecular system, you can pass the argument in_place=False to the molsysmt.basic.add() function. This will return a new molecular system with the added elements, while leaving the original unchanged.

molsys_D = msm.add(molsys_B, molsys_C, in_place=False)

msm.get(molsys_B, n_peptides=True)

msm.get(molsys_C, n_peptides=True)

msm.get(molsys_D, n_peptides=True)

Notice that the number of peptides in each system was retrieved with molsysmt.basic.get(). This function allows us to query specific attributes, such as the count of peptides, atoms, or molecules, from a molecular system.

Warning

When adding elements between molecular systems that contain structural data (such as coordinates, box, or velocities), the number of structures in the source and target systems must match. Otherwise, you need to specify which structures to use with the structure_indices argument (see: molsysmt.basic.add()).

For example, if the source system has multiple frames while the target has only one, you can restrict the addition to the first frame of the source:

msm.add(molsys_A, molsys_B, structure_indices=0)