molsysmt.basic.append_structures#

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

Appending structures from one molecular system into another.

This function appends structural information (coordinates, box dimensions, velocities, etc.) from a source molecular system (from_molecular_system) into a target molecular system (to_molecular_system). The result is a molecular system with additional structures (frames or conformations).

The appended structures must correspond to the same number and ordering of atoms as the target system. The source does not need to provide topology; coordinate-only forms such as XTC, DCD, and XYZ are accepted. If the number of atoms differs, a selection of atoms from the source system must be provided using the selection argument. Matching atom ordering is the caller’s responsibility when the source has no topology.

By default, the operation modifies the input molecular system in place. This behavior can be changed by setting in_place=False, in which case a new molecular system is returned.

Parameters:

  • to_molecular_system (molecular system) – Molecular system that will receive the new structures. Must be in one of the supported forms.

  • from_molecular_system (molecular system) – Molecular system providing the structures to append. Must be in one of the supported forms.

  • selection (str, list, tuple or numpy.ndarray, default 'all') – Selection of atoms from the source system whose structural attributes will be appended. Can be a list/array of 0-based atom indices, or a string using any of the supported selection syntaxes (Selection syntaxes). Only needed when the number of atoms differs between systems.

  • structure_indices (int, list, tuple, numpy.ndarray or 'all', default 'all') – 0-based indices of the structures in the source system to append.

  • syntax (str, default 'MolSysMT') – Selection syntax used if selection is a string. Must be one of the supported syntaxes in Selection syntaxes.

  • in_place (bool, default True) – If True, modifies to_molecular_system directly. If False, returns a new molecular system with the appended structures, leaving the original unmodified.

  • attribute_policy ({'intersection', 'strict'}, default 'intersection') – Policy for structural attributes present in only one 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. Use with caution.

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 appended structures.

Return type:

molecular system or None

Raises:

  • NotSupportedFormError – If either molecular system is not provided in a supported form.

  • StructuralInconsistencyError – If atom counts differ, structural axes are inconsistent, or strict policy rejects one-sided attributes.

  • SyntaxError – If the selection syntax is not recognized.

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.

  • Source topology is optional. Atom-count compatibility is always required, while chemical identity is not inferred from coordinates alone.

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

See also

molsysmt.basic.select()

Select atoms from a molecular system.

molsysmt.basic.concatenate_structures()

Concatenate structures from multiple molecular systems into one.

molsysmt.basic.add()

Adding elements from one molecular system into another.

molsysmt.basic.merge()

Merge multiple molecular systems into one.

Examples

>>> import molsysmt as msm
>>> from molsysmt import systems
>>> molsys_A = msm.convert(systems['alanine dipeptide']['alanine_dipeptide.h5msm'])
>>> molsys_B = msm.structure.translate(molsys_A, translation='[0.1, 0.1, 0.1] nanometers')
>>> msm.get(molsys_A, n_structures=True)
1
>>> msm.append_structures(molsys_A, molsys_B)
>>> msm.get(molsys_A, 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: Append structures.

Added in version 1.0.0.

On this page