`HierarchyScheme`

class openff.toolkit.topology.HierarchyScheme(parent: Molecule | FrozenMolecule | _SimpleMolecule, uniqueness_criteria: Iterable[str], iterator_name: str)[source]

Perceives hierarchy elements from the metadata of atoms in a Molecule.

The Open Force Field Toolkit has no native understanding of hierarchical atom organisation schemes common to other biomolecular software, such as “residues” or “chains” (see Hierarchy data (chains and residues)). To facilitate iterating over groups of atoms, a HierarchyScheme can be used to collect atoms into HierarchyElements, groups of atoms that share the same values for certain metadata elements. Metadata elements are stored in the Atom.properties attribute.

Hierarchy schemes are not updated dynamically; if a Molecule with hierarchy schemes changes, Molecule.update_hierarchy_schemes() must be called before the scheme is iterated over again or else the grouping may be incorrect.

A HierarchyScheme contains the information needed to perceive HierarchyElement objects from a Molecule containing atoms with metadata.

__init__(parent: Molecule | FrozenMolecule | _SimpleMolecule, uniqueness_criteria: Iterable[str], iterator_name: str)[source]

Create a new hierarchy scheme for iterating over groups of atoms.

Parameters:

parent – The Molecule to which this scheme belongs.
uniqueness_criteria – The names of Atom metadata entries that define this scheme. An atom belongs to a HierarchyElement only if its metadata has the same values for these criteria as the other atoms in the HierarchyElement.
iterator_name – The name of the iterator that will be exposed to access the hierarchy elements generated by this scheme

Methods

`__init__`(parent, uniqueness_criteria, ...)	Create a new hierarchy scheme for iterating over groups of atoms.
`add_hierarchy_element`(identifier, atom_indices)	Instantiate a new HierarchyElement belonging to this HierarchyScheme.
`perceive_hierarchy`()	Prepare the parent `Molecule` for iteration according to this scheme.
`sort_hierarchy_elements`()	Semantically sort the HierarchyElements belonging to this object, according to their identifiers.
`to_dict`()	Serialize this object to a basic dict of strings, ints, and floats

to_dict() → dict[source]: Serialize this object to a basic dict of strings, ints, and floats

perceive_hierarchy()[source]

Prepare the parent Molecule for iteration according to this scheme.

Groups the atoms of the parent of this HierarchyScheme according to their metadata, and creates HierarchyElement objects suitable for iteration over the parent. Atoms missing the metadata fields in this object’s uniqueness_criteria tuple will have those spots populated with the string 'None'.

This method overwrites the scheme’s hierarchy_elements attribute in place. Each HierarchyElement in the scheme’s hierarchy_elements attribute is static — that is, it is updated only when perceive_hierarchy() is called, and not on-the-fly when atom metadata is modified.

add_hierarchy_element(identifier: tuple[Union[str, int]], atom_indices: Sequence[int]) → HierarchyElement[source]

Instantiate a new HierarchyElement belonging to this HierarchyScheme.

This is the main way to instantiate new HierarchyElements.

Parameters:

identifier – tuple of metadata values (not keys) that define the uniqueness criteria for this element
atom_indices – The indices of atoms in scheme.parent that are in this element

sort_hierarchy_elements()[source]: Semantically sort the HierarchyElements belonging to this object, according to their identifiers.