qrunch.chemistry.embedded_atoms.embedded_atoms_selector_creators

Sub-creators for building embedded atoms selectors and extenders in the builder pattern.

Classes

EmbeddedAtomsSelectorCreator

An Embedded Atoms Selector creator.

class EmbeddedAtomsSelectorCreator

Bases: object

An Embedded Atoms Selector creator.

__init__() → None

Initialize the embedded atoms selector creator.

Return type:: None

create() → EmbeddedAtomsSelector

Create an instance of EmbeddedAtomsSelector.

Return type:: EmbeddedAtomsSelector

with_aromatic_ring_extender(ring_sizes: tuple[int, ...] = (5, 6), planarity_tolerance: float = 0.1) → Self

Include an aromatic ring extender.

This extender includes the complete aromatic ring (e.g. a benzene ring) whenever any of its atoms is active, so that the whole conjugated ring is embedded together. Only the ring atoms are added - hydrogens and side chains attached to the ring are not included. Aromatic rings are detected geometrically as planar rings of aromatic-eligible elements, which handles both benzene and heteroaromatic rings.

Parameters:

ring_sizes (tuple[int, ...]) – Ring sizes (number of atoms) to treat as candidate aromatic rings.
planarity_tolerance (float) – Maximum out-of-plane deviation (in Angstrom) for a ring to be considered planar, and therefore aromatic.

Return type:

Self

with_bond_length_change_selector(threshold: float | None = None) → Self

Include a bond-length change selector.

This selector identifies atoms involved in bonds whose length changes most across reaction images. It is a purely geometric, rigid-motion-invariant selector that also detects symmetric homonuclear bond stretches (e.g. H2 dissociation) that electronic descriptors cannot see.

Parameters:: threshold (float | None) – Optional explicit threshold (in Angstrom) for the bond-length change. When None (default), the threshold is determined automatically via Jenks natural breaks clustering.
Return type:: Self

with_coordination_change_selector() → Self

Include a coordination change selector.

This selector identifies atoms whose coordination environment changes across reaction images. It builds a connectivity graph for each image and detects atoms whose sorted neighbor atomic numbers change between any pair of images.

Return type:: Self

with_distance_extender(distance_threshold: float) → Self

Include a distance-based extender.

This extender includes atoms within a distance threshold from any active atom.

Parameters:: distance_threshold (float) – Maximum distance (in Angstrom) for inclusion.
Return type:: Self

with_eeqbc_change_selector(total_charge: int = 0, charge_threshold: float = 0.05) → Self

Include an atomic charge change selector based on the EEQBC charge model.

This selector identifies atoms whose partial charges change significantly across reaction images. It uses the bond capacity electronegativity equilibration model (EEQBC), which strongly suppresses artificial long-range charge transfer between distant fragments, so it is less likely to select chemically irrelevant, distant spectator atoms than ordinary QEq/EEQ. Useful for detecting charge transfer reactions where bond connectivity may not change.

Parameters:

total_charge (int) – Total charge of the system in elementary charges.
charge_threshold (float) – Minimum absolute charge change (in elementary charges) to flag an atom.

Return type:

Self

with_electronic_structure_change_selector(threshold: float | None = None) → Self

Include an electronic structure change selector.

This selector identifies atoms whose local electronic structure (measured via IAO density matrices) changes significantly across reaction images.

Supports both restricted and unrestricted calculations.

Parameters:: threshold (float | None) – Optional explicit threshold for the Frobenius norm change score. When None (default), the threshold is determined automatically via Jenks natural breaks clustering.
Return type:: Self

with_embedded_atoms_connection_extender(ring_sizes: tuple[int, ...] = (5, 6), planarity_tolerance: float = 0.1) → Self

Include a connection extender that chemically repairs the active fragment.

This extender adds the minimum number of backbone atoms needed to link the disconnected pieces of the active selection into a single connected fragment (or as few fragments as possible - atoms in genuinely different molecules cannot be connected). Afterward it applies an aromatic ring extender so that connecting paths do not cut through aromatic (or conjugated planar) ring systems.

Parameters:

ring_sizes (tuple[int, ...]) – Ring sizes (number of atoms) to treat as candidate aromatic rings when completing rings the connecting paths pass through.
planarity_tolerance (float) – Maximum out-of-plane deviation (in Angstrom) for a ring to be considered planar, and therefore aromatic.

Return type:

Self

with_full_molecule_extender() → Self

Include a full molecule extender.

This extender includes all atoms in connected fragments containing active atoms. Useful for ensuring entire molecules are included when any part of them is active.

Return type:: Self

with_hydrogen_bond_change_selector(acceptor_atomic_numbers: tuple[int, ...] = (7, 8, 9, 15, 16, 17), hydrogen_acceptor_max_distance: float = 2.5, minimum_angle: float = 120.0, distance_change_scale: float = 0.3, angle_change_scale: float = 30.0, threshold: float | None = None) → Self

Include a hydrogen-bond change selector.

This selector identifies atoms in hydrogen bonds (donor-hydrogen-acceptor, e.g. C-H…O) whose geometry - the donor-hydrogen distance, hydrogen-acceptor distance and donor-hydrogen-acceptor angle - changes most across reaction images. It is a purely geometric, rigid-motion-invariant selector that detects reactions driven by hydrogen-bond formation, breaking or rearrangement.

Parameters:

acceptor_atomic_numbers (tuple[int, ...]) – Atomic numbers eligible to act as hydrogen-bond acceptors (default: N, O, F, P, S, Cl).
hydrogen_acceptor_max_distance (float) – Maximum hydrogen-acceptor distance (in Angstrom) for a pair to be considered a hydrogen bond.
minimum_angle (float) – Minimum donor-hydrogen-acceptor angle (in degrees) for a pair to be considered a hydrogen bond.
distance_change_scale (float) – Distance change (in Angstrom) mapped to a unit contribution in the combined score.
angle_change_scale (float) – Angle change (in degrees) mapped to a unit contribution in the combined score.
threshold (float | None) – Optional explicit threshold for the combined hydrogen-bond change score. When None (default), the threshold is determined automatically via Jenks natural breaks clustering.

Return type:

Self

with_nearest_neighbor_extender() → Self

Include a nearest neighbor extender.

This extender includes atoms directly bonded to any active atom in any image.

Return type:: Self

with_options(options: EmbeddedAtomsSelectorOptions) → Self

Set the options for the embedded atoms selector.

Parameters:: options (EmbeddedAtomsSelectorOptions) – The EmbeddedAtomsSelectorOptions controlling the embedded atoms selection, e.g. the maximum number of embedded atoms.
Return type:: Self