Concatenate structures#

Concatenating the structures found in a list of molecular systems.

The structures found in a list of molecular systems can be concatenated with molsysmt.basic.concatenate_structures(). The first input establishes the output system and topology when available; subsequent inputs may be coordinate-only XTC, DCD, XYZ, or native Structures objects. Every selected source must match the output atom count and ordering, and the result preserves the input structure order. By default, attribute_policy='intersection' keeps only structural series available in every block and warns about discarded series; use attribute_policy='strict' to reject any one-sided series.

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

Let’s demonstrate how this function works using alanine dipeptide represented as three different molecular systems, each with a distinct structure.

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#

Each of the three molecular systems initially contains a single structure. Let’s inspect the state of \(A\) before concatenation:

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 create a fourth molecular system by concatenating the structures from \(A\), \(B\), and \(C\):

molsys_D = msm.concatenate_structures([molsys_A, molsys_B, 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.concatenate_structures() is the same method as molsysmt.basic.concatenate_structures().

Let’s inspect the newly created system \(D\). We expect \(D\) to contain 3 structures:

msm.info(molsys_D)

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

Finally, the resulting system can be visualized interactively. Try using the widget controls to cycle through the 3 concatenated structures.

msm.view(molsys_D, standard=True)

Selecting specific structures to concatenate (`structure_indices`)#

Instead of concatenating all structures present in the input systems, you can pass explicit structure indices for each system via structure_indices. For example, let’s select structures [0, 2] from \(D\) and structure 0 from \(A\):

molsys_E = msm.concatenate_structures([molsys_D, molsys_A], structure_indices=[[0, 2], 0])

msm.info(molsys_E)

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

Specifying output form (`to_form`)#

By default, the resulting molecular system inherits the form of the first input system (molsysmt.MolSys). You can specify a different target output form using to_form:

molsys_F = msm.concatenate_structures([molsys_A, molsys_B, molsys_C], to_form='molsysmt.Structures')

msm.get_form(molsys_F)

'molsysmt.Structures'

Concatenating structural subsets (`selections`)#

You can also restrict concatenation to a specific subset of atoms across all input systems using selections:

molsys_G = msm.concatenate_structures([molsys_A, molsys_B, molsys_C], selections='atom_type=="C"')

msm.info(molsys_G)

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	3