molsysmt.build.add_terminal_atoms#

molsysmt.build.add_terminal_atoms(molecular_system, new_atoms, coordinates, attribute_policy='intersection', skip_digestion=False)[source]#

Adding terminal atoms to existing groups in a new native system.

Parameters:

  • molecular_system (molecular system) – Any supported form providing topology, one chemical state and coordinates.

  • new_atoms (list or tuple) – Detached atom records. Each requires parent_atom_index (an existing zero-based index) and atom_type (element symbol). Optional atom_name, atom_id, isotope, bond_order (1, 2 or 3) and chemical_attributes declare identity, the parent bond and canonical ChemicalStates atom fields. Membership is inherited from the parent; IDs are normalized to strings.

  • coordinates (quantity) – Coordinates of the added atoms, shape (n_structures, n_new_atoms, 3), in units of length. Every source structure must be covered.

  • attribute_policy ({'intersection', 'strict'}, default='intersection') – Intersection drops unsupported velocities, occupancies, B-factors, system observables and force-field parameters with a diagnostic. Strict rejects those inputs. Sparse alternate locations remain attached to the existing atom indices. No values are fabricated for new atoms.

  • skip_digestion (bool, default=False) – Whether to skip argument digestion.

Returns:

New native molecular_system and detached terminal_attachment@1 report with int64 old/new atom_correspondence and parent_atom_pairs, generated string IDs, dropped attributes and invalidated named interactions.

Return type:

dict

Raises:

  • ArgumentError – If atom records or coordinate units are invalid.

  • StructuralInconsistencyError – If axes, membership, IDs or the selected attribute policy are incompatible.

Notes

Existing atom indices, coordinates and chemical assignments are preserved. Each added atom has one covalent bond to an existing parent. This tool does not predict chemistry, generate coordinates or accept multiple chemical states. Named analyses retain provenance but become unevaluated on the returned copy; added atoms have no original source index. Failure leaves the source unchanged. Empty addition returns an independent unchanged copy with no invalidation. Successful attachment, including empty addition, archives an independent report in output ChemicalStates preparation history. It declares all examined structure indices, original source counts, supplied-coordinate evidence, attribute policy and the producing MolSysMT version. H5MSM preserves that evidence without embedding coordinate arrays in the report. Historical indices retain the operation’s domain after extraction or reordering.

See also

add_missing_hydrogens

Generate H coordinates for a prepared chemical state.

Examples

>>> import molsysmt as msm
>>> builder = msm.MolSysBuilder()
>>> _ = builder.add_atom(atom_type='C', atom_name='C')
>>> builder.set_coordinates(msm.pyunitwizard.quantity([[[0., 0., 0.]]], 'nm'))
>>> result = msm.build.add_terminal_atoms(builder.build(),
...     [{'parent_atom_index': 0, 'atom_type': 'H'}],
...     msm.pyunitwizard.quantity([[[0., 0., 0.109]]], 'nm'))
>>> result['molecular_system'].get_n_atoms()
2

User guide

See Attaching terminal atoms for attachment and attribute policies.

Added in version 1.0.0.

On this page