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. The source can be a coordinate-only trajectory such as XTC, DCD, or XYZ; it does not need to repeat the target topology. Every stored structural series covers the complete resulting structure axis. By default, attribute_policy='intersection' discards optional series that are not available in both blocks and emits one warning; use attribute_policy='strict' to reject the operation without modifying the target instead.

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 alanine dipeptide defined as three different 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')

Basic usage#

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 let’s append the structures of \(B\) and \(C\) into \(A\):

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:

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 interactively. Try using the widget buttons to cycle through the 3 frames.

msm.view(molsys_A, standard=True)

Creating a new system (`in_place=False`)#

By default, the function modifies the target system in place. 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)

Appending selected structures (`structure_indices`)#

When the source system contains multiple structures, you can select specific frames to append using structure_indices. For example, let’s concatenate \(A\), \(B\), and \(C\) into a 3-structure system, and then append only structure 1 into \(B\):

molsys_multi = msm.concatenate_structures([molsys_A, molsys_B, molsys_C])
molsys_E = msm.append_structures(molsys_B, molsys_multi, structure_indices=1, in_place=False)

msm.get(molsys_E, n_structures=True)

Appending structural subsets (`selection`)#

If the source system contains additional atoms or you want to append structures considering only a specific subset of atoms, pass a matching selection string:

molsys_A_C = msm.extract(molsys_A, selection='atom_type=="C"')
molsys_F = msm.append_structures(molsys_A_C, molsys_B, selection='atom_type=="C"', in_place=False)

msm.info(molsys_F)

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