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 or tuple of molecular systems) – Molecular systems to inspect or combine in their given order.

  • selections (str, list, tuple, or numpy.ndarray, default='all') – Atom selection shared by the inputs or one selection per molecular system.

  • structure_indices (int, list, tuple, or numpy.ndarray, default='all') – Structure indices (0-based) to include or process.

  • to_form (str, list of str, or None, default=None) – Target molecular-system form; None preserves or infers the input form.

  • syntax (str, default='MolSysMT') – Selection syntax used to evaluate selection (e.g., ‘MolSysMT’, ‘MDTraj’).

  • attribute_policy ({'intersection', 'strict'}, default='intersection') – Policy for attributes available in only one input system.

  • skip_digestion (bool, default=False) – Whether to skip MolSysMT’s internal argument digestion mechanism.

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.