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.

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

Basic usage#

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')

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)

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#

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#

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