molsysmt.basic.merge#

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

Merging elements from multiple molecular systems into a new one.

This function builds a new molecular system by merging selected elements from several input systems. All inputs must be compatible in their number of structures; otherwise, structure_indices must be provided to align the structures that will be merged. You can also provide per-system atom selections via selections. The output form can be set with to_form (defaults to the first system’s form).

Parameters:

  • molecular_systems (list of molecular systems) – Input systems, each in one of the supported forms.

  • 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. Selection strings follow Selection syntaxes.

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

  • keep_ids (bool, default True) – Whether to preserve original ids (atom, group, molecule) from the inputs. If False, ids are reassigned in the merged system.

  • syntax (str, default 'MolSysMT') – Selection syntax used when any entry in selections is a string. See Selection syntaxes.

  • to_form (str or None, default None) – Output form of the merged molecular system. If None, the output molecular system inherits the first input system’s form.

  • 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 composed of the selected elements from the inputs. Its form is controlled by to_form (or inherited from the first input when None).

Return type:

molecular system

Raises:

  • NotSupportedFormError – If any input molecular system has an unsupported form.

  • ArgumentError – If input arguments are invalid or inconsistent in length or compatibility.

Notes

  • Supported molecular-system forms are summarized in Items and Forms.

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

  • All input systems must be aligned in number of structures or explicitly aligned via structure_indices. Internal conversions are performed when the input forms differ from the chosen to_form.

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

Add elements from one system to another.

molsysmt.basic.append_structures()

Append structures from one system to another.

molsysmt.basic.concatenate_structures()

Concatenate structures across multiple molecular systems.

Examples

>>> import molsysmt as msm
>>> molsys = msm.systems['alanine dipeptide']['alanine_dipeptide.h5msm']
>>> molsys_A = msm.convert(molsys)
>>> molsys_B = msm.structure.translate(molsys_A, translation='[0.1, 0.1, 0.1] nanometers')
>>> molsys_merged = msm.basic.merge([molsys_A, molsys_B])
>>> msm.basic.get(molsys_merged, n_peptides=True)
2

Tutorial with more examples

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

Added in version 1.0.0.

On this page