molsysmt.basic.concatenate_structures#

molsysmt.basic.concatenate_structures(molecular_systems, selections='all', structure_indices='all', to_form=None, syntax='MolSysMT', attribute_policy='intersection', 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, tuple, numpy.ndarray, int, str or 'all', default 'all') – Atom selections for the input systems. A list or tuple contains one selection per system and must match molecular_systems in length. A scalar, string, NumPy array, or range is applied to every system. Nest index collections to provide a different collection for each system.

  • structure_indices (list, tuple, numpy.ndarray, range, int or 'all', default 'all') – 0-based structure indices to include. A list or tuple contains one value or index collection per system and must match molecular_systems in length. A scalar, NumPy array, range, or ‘all’ is applied to every system.

  • 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.

  • attribute_policy ({'intersection', 'strict'}, default 'intersection') – Policy for structural attributes present in only one input block. 'intersection' discards one-sided series with a warning; 'strict' rejects the operation.

  • 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 Items and 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).

  • Input topology is optional after the first system establishes the output topology. Atom-count and ordering compatibility remain the caller’s responsibility.

  • A native target with one chemical state associates new structures with that state implicitly. Multi-state targets preserve compatible explicit associations and use an unknown association only when the incoming state cannot be determined.

  • Lists and tuples always express per-system intent. Use a NumPy array or range when one index collection should be applied to every system.

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.