molsysmt.basic.add#

molsysmt.basic.add(to_molecular_system, from_molecular_system, selection='all', structure_indices='all', keep_ids=True, in_place=True, syntax='MolSysMT', skip_digestion=False)[source]#

Adding elements from one molecular system into another.

This function adds selected elements from a source molecular system (from_molecular_system) into a target molecular system (to_molecular_system). Both systems must be compatible in terms of structure count: if the target system contains structural information (e.g., coordinates), the source must either match this number of structures or the user must explicitly provide structure_indices to specify which structures to use during the addition.

Parameters:

  • to_molecular_system (molecular system) – The target molecular system, in any of the supported forms. Elements from the source system will be added to this system by default. If in_place=False, a copy will be returned instead of modifying this object directly.

  • from_molecular_system (molecular system) – The source molecular system, in any of the supported forms. Selected elements from this system will be added to the target system.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Atoms to be added, specified as a list/tuple/array of 0-based atom indices, or as a string following one of the supported selection syntaxes.

  • structure_indices (str, list, tuple, or numpy.ndarray, default='all') – Indices (0-based) of structures in the source system to use for copying structural attributes (e.g., coordinates) of the selected atoms.

  • keep_ids (bool, default=True) – Whether to preserve the unique IDs of elements from the source system when adding them to the target system.

  • in_place (bool, default=True) – If True, modifies to_molecular_system in place. If False, returns a new modified copy, leaving the original unchanged.

  • syntax (str, default='MolSysMT') – Selection syntax to interpret the selection string. See Selection syntaxes for options.

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

If in_place=True, returns None and modifies to_molecular_system directly. If in_place=False, returns a new molecular system (same form as the input) with the added structures.

Return type:

molecular system or None

Raises:

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

  • ArgumentError – If any argument has an invalid or inconsistent value.

Notes

  • All forms listed in Forms are accepted for both source and target systems.

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

See also

molsysmt.basic.select()

Select elements from a molecular system.

molsysmt.basic.merge()

Merge multiple molecular systems into one.

molsysmt.basic.append_structures()

Append structures from one system to another.

molsysmt.basic.concatenate_structures()

Concatenate multiple systems along the structural dimension.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = msm.convert(systems['alanine dipeptide']['alanine_dipeptide.h5msm'])
>>> molsys_B = msm.convert(systems['valine dipeptide']['valine_dipeptide.h5msm'])
>>> msm.get(molsys_A, n_molecules=True)
1
>>> msm.add(molsys_A, molsys_B)
>>> msm.get(molsys_A, n_molecules=True)
2

Tutorial with more examples

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

Added in version 1.0.0.

On this page