molsysmt.basic.concatenate_structures#

molsysmt.basic.concatenate_structures(molecular_systems, selections='all', structure_indices='all', to_form=None, syntax='MolSysMT', skip_digestion=False)[source]#

Concatenate structures from a list of molecular systems into a single molecular system.

This function collects structures from several molecular systems and returns a new molecular system whose structural dimension is the concatenation of the selected structures. All participating systems must be aligned in atom count and ordering over the chosen selections; use selections to provide per-system matching subsets when needed. Optionally, select specific structures from each input with structure_indices.

Parameters:

  • molecular_systems (list of molecular systems) – List of input molecular systems in any of the supported forms. Structures will be taken from these systems.

  • selections (list of (str, tuple, list, numpy.ndarray) or 'all', default 'all') – Atom selections to extract structures from each molecular system. Provide a single value (applied to all systems) or a list of selections with the same length as molecular_systems. Each entry can be a 0-based index collection or a selection string parsed according to Selection syntaxes.

  • structure_indices (list of (int, tuple, list, numpy.ndarray) or 'all', default 'all') – Structure indices (0-based) per system to include. Provide a single value (applied to all systems) or a list matching molecular_systems in length.

  • to_form (str or None, default None) – Output form for the resulting molecular system. If None, the form is inherited from the first input system.

  • syntax (str, default 'MolSysMT') – Selection syntax used when entries of selections are strings. See Selection syntaxes.

  • skip_digestion (bool, default False) – Whether to skip MolSysMT’s internal argument digestion mechanism. MolSysMT includes a built-in digestion system that validates and normalizes function arguments. This process checks types, shapes, and values, and automatically adjusts them when possible to meet expected formats. Setting skip_digestion=True disables this process, which may improve performance in workflows where inputs are already validated. Use with caution: only set this to True if you are certain all input arguments are correct and consistent.

Returns:

New molecular system containing the concatenated structures. The topology is inherited from the first item in molecular_systems. The output form is controlled by to_form (or inherited if None).

Return type:

molecular system

Raises:

  • NotSupportedFormError – If any input system is provided in an unsupported form.

  • ArgumentError – If input values are invalid or inconsistent.

Notes

  • Supported molecular-system forms are summarized in Forms.

  • Selection strings must follow one of the syntaxes described in Selection syntaxes.

  • All systems must be consistent in number and ordering of atoms over the final selections. Use selections to align subsets when needed.

  • Structural attributes concatenated include coordinates, velocities, box, time (when available in the inputs).

See also

molsysmt.basic.select()

Select elements from a molecular system.

molsysmt.basic.append_structures()

Append structures from one molecular system to another.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> A = msm.convert(systems['alanine dipeptide']['alanine_dipeptide.h5msm'])
>>> B = msm.structure.translate(A, translation='[0.1, 0.1, 0.1] nanometers')
>>> C = msm.concatenate_structures([A, B])
>>> msm.get(C, n_structures=True)
2

Tutorial with more examples

See the following tutorial for a practical demonstration of how to use this function, along with additional examples: Concatenate structures.

Added in version 1.0.0.