Append structures#

Appending structures from one molecular system into another.

Structures (frames or conformations) from different molecular systems can be appended to a given system using molsysmt.basic.append_structures(). In this way, an existing molecular system can be extended with additional structures, for example when combining snapshots from different simulations.

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.append_structures().

Let’s show how this method works with the alanine dipeptide defined as three diferent molecular systems with different structures.

import molsysmt as msm

molsys_A = msm.build.build_peptide('AceAlaNME')
molsys_B = msm.structure.translate(molsys_A, translation='[0.1, 0.1, 0.1] nanometers')
molsys_C = msm.structure.translate(molsys_A, translation='[0.2, 0.2, 0.2] nanometers')

Systems \(B\) and \(C\) were translated in space. This way all three systems have the same elements but different structures. This sets the stage to append these structures as additional conformations (frames) of the same molecule. Let’s see how \(A\) is defined before appending the structures of \(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	22	3	1	1	1	1	1	1

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

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

Tip

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

Let’s see now the new content of \(A\). We expect \(A\) to now contain 3 structures, corresponding to the original plus those from \(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	22	3	1	1	1	1	1	3

And we can also visualize it. Try using the widget buttons to visualize the 3 frames.

msm.view(molsys_A, standard=True)

By default, the function modifies the target system in place. But if you prefer not to modify the original molecular system, setting in_place=False returns a new molecular system with the appended structures, while leaving the original system unchanged.

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

msm.get(molsys_B, n_structures=True)

msm.get(molsys_C, n_structures=True)

msm.get(molsys_D, n_structures=True)

Notice that the number of peptides in each system was retrieved with {func}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 appending structures between molecular systems, the number of atoms in the source and target systems must match. Otherwise, you need to provide a selection of atoms from the source system so that their number matches the atoms in the target (see: molsysmt.basic.append_structures()).

For example, if the source system contains extra solvent molecules while the target has only the protein, you can restrict the appended structures to the protein atoms:

msm.append_structures(molsys_A, molsys_B, selection='protein')