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', attribute_policy='intersection', 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) – Target molecular system that receives the added elements or structures.

  • from_molecular_system (molecular system) – Source molecular system providing the elements or structures to add.

  • selection (str, list, tuple, or numpy.ndarray, default='all') – Selection string or boolean/integer array specifying elements.

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

  • keep_ids (bool, default=True) – Whether to preserve element identifiers from the input systems.

  • in_place (bool, default=True) – Whether to modify the input molecular system in place.

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

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

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 Items and Forms are accepted for both source and target systems.

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

  • add takes one target and one source. A list is read as one molecular system split into complementary items, exactly as molsysmt.basic.convert() reads it, and is assembled before the addition; it is never a sequence of systems to add one after another.

  • Atom-aligned structural attributes are kept only when they are available in both systems. A one-sided coordinate, velocity, B-factor, or occupancy series is dropped with a StructuralAttributeDropWarning so no partial atom-axis series is created. See attribute_policy to reject instead.

  • The target’s periodic box, time, structure_id and time_step are preserved: adding atoms does not touch the structure axis and does not reinterpret the unit cell. A box disagreement is reported with an IncompatibleBoxWarning.

  • temperature, potential_energy and kinetic_energy describe the whole system, and the system changes when atoms are added, so they are dropped.

  • Bioassemblies from both systems are combined, with the incoming chain indices remapped; a colliding assembly identifier is renamed and reported.

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