qrunch.chemistry.active_sites.active_site_selection

Active site selection based on coordination number changes and partial charge changes during a reaction.

Classes

ActiveSiteExtender	Extends an existing active site selection with additional atoms.
ActiveSiteSelector	Composes primary active site selectors and extenders to identify active atoms in a reaction.
CoordinationChangeSelector	Selects atoms whose coordination number changes across reaction images.
DistanceExtender	Extends the active site to include atoms within a distance threshold from any active atom.
FullMoleculeExtender	Extends the active site to include all atoms in connected fragments containing active atoms.
NearestNeighborExtender	Extends the active site to include atoms directly bonded to any active atom in any image.
PrimaryActiveSiteSelector	Identifies the core set of active atoms from a reaction.
QEqAtomicChargeChangeSelector	Selects atoms whose QEq/EEQ partial charges change significantly across reaction images.

class ActiveSiteExtender

Bases: Protocol

Extends an existing active site selection with additional atoms.

__init__(*args, **kwargs)

extend(active_indices: set[int], reaction: Reaction) → set[int]

Return additional atom indices to include based on the current active set.

The returned set should contain all new atoms to add (not including the input set).

Parameters:

• active_indices (set[int]) – The current set of active atom indices.

• reaction (Reaction) – The reaction being analyzed.

Return type:

set[int]

class ActiveSiteSelector

Bases: object

Composes primary active site selectors and extenders to identify active atoms in a reaction.

Primary selectors identify the core active atoms (e.g., atoms with changed coordination or significant charge redistribution). Extenders then expand the selection (e.g., by including nearest neighbors, atoms within a distance threshold, or entire connected fragments).

__init__(primary_selectors: list[PrimaryActiveSiteSelector], extenders: list[ActiveSiteExtender] | None = None) → None

Initialize the ActiveSiteSelector.

Parameters:

• primary_selectors (list[PrimaryActiveSiteSelector]) – One or more selectors that identify core active atoms. Results are unioned across all selectors.

• extenders (list[ActiveSiteExtender] | None) – Optional list of extenders applied in order to expand the selection.

Return type:

None

select_active_sites(reaction: Reaction) → list[int]

Identify active site atoms by running all selectors and extenders.

Parameters:

reaction (Reaction) – The reaction to analyze.

Return type:

list[int]

static write_active_site_reaction_xyz(reaction: Reaction, active_site_indices: list[int], file_path: Path, *, comment: str = '') → None

Write a reaction XYZ file containing only the specified active_site atoms.

The output file contains multiple XYZ frames (one per reaction image), which can be viewed as an animation in molecular visualization tools.

Parameters:

• reaction (Reaction) – The reaction to write.

• active_site_indices (list[int]) – The atom indices to include in the output.

• file_path (Path) – Path to the output XYZ file.

• comment (str) – Optional comment to include in each frame’s comment line.

Return type:

None

class CoordinationChangeSelector

Bases: object

Selects atoms whose coordination number changes across reaction images.

Builds a connectivity graph for each image and detects atoms whose coordination number changes between any pair of images. Useful for identifying atoms involved in bond breaking/forming processes.

__init__(bond_tolerance_factor: float = 1.3) → None

Parameters:

bond_tolerance_factor (float)

Return type:

None

bond_tolerance_factor: float = 1.3

select(reaction: Reaction) → set[int]

Select atom indices with changed coordination numbers.

Parameters:

reaction (Reaction) – The reaction to analyze.

Return type:

set[int]

class DistanceExtender

Bases: object

Extends the active site to include atoms within a distance threshold from any active atom.

__init__(distance_threshold: float) → None

Parameters:

distance_threshold (float)

Return type:

None

distance_threshold: float

Maximum distance (in Angstrom) for inclusion.

extend(active_indices: set[int], reaction: Reaction) → set[int]

Return atom indices within the distance threshold from active atoms.

Parameters:

• active_indices (set[int]) – The current set of active atom indices.

• reaction (Reaction) – The reaction being analyzed.

Return type:

set[int]

class FullMoleculeExtender

Bases: object

Extends the active site to include all atoms in connected fragments containing active atoms.

This is useful for ensuring that entire molecules are included when any part of them is active, which can be important for preserving chemical context in reactions involving many small molecules, like a reaction solvated in water where only a few water molecules are directly involved but the entire solvent environment is relevant.

__init__(bond_tolerance_factor: float = 1.3) → None

Parameters:

bond_tolerance_factor (float)

Return type:

None

bond_tolerance_factor: float = 1.3

extend(active_indices: set[int], reaction: Reaction) → set[int]

Return atom indices belonging to the same molecule as active atoms.

This assumes the reaction consist of several disconnected molecules (e.g., reactants, products, solvent molecules) and that we want to include entire molecules if any part of them is active.

Parameters:

• active_indices (set[int]) – The current set of active atom indices.

• reaction (Reaction) – The reaction being analyzed.

Return type:

set[int]

class NearestNeighborExtender

Bases: object

Extends the active site to include atoms directly bonded to any active atom in any image.

__init__(bond_tolerance_factor: float = 1.3) → None

Parameters:

bond_tolerance_factor (float)

Return type:

None

bond_tolerance_factor: float = 1.3

extend(active_indices: set[int], reaction: Reaction) → set[int]

Return atom indices that are nearest neighbors of active atoms.

Parameters:

• active_indices (set[int]) – The current set of active atom indices.

• reaction (Reaction) – The reaction being analyzed.

Return type:

set[int]

class PrimaryActiveSiteSelector

Bases: Protocol

Identifies the core set of active atoms from a reaction.

__init__(*args, **kwargs)

select(reaction: Reaction) → set[int]

Select atom indices that are part of the active site.

Parameters:

reaction (Reaction) – The reaction to analyze.

Return type:

set[int]

class QEqAtomicChargeChangeSelector

Bases: object

Selects atoms whose QEq/EEQ partial charges change significantly across reaction images.

Uses the Rappé-Goddard charge equilibration model, which is geometry-dependent, non-iterative, and much cheaper than any SCF-based method. Useful for identifying charge transfer reactions where bond connectivity may not change.

__init__(total_charge: int = 0, charge_threshold: float = 0.2) → None

Parameters:

• total_charge (int)

• charge_threshold (float)

Return type:

None

charge_threshold: float = 0.2

select(reaction: Reaction) → set[int]

Select atom indices with significant charge changes.

Parameters:

reaction (Reaction) – The reaction to analyze.

Return type:

set[int]

total_charge: int = 0