Molecular Interaction Data Structures

Molecular interaction classes for HBAT analysis.

This module defines the data structures for representing different types of molecular interactions including hydrogen bonds, halogen bonds, π interactions, and cooperativity chains.

class hbat.core.interactions.MolecularInteraction

Bases: ABC

Base class for all molecular interactions.

This abstract base class defines the unified interface for all types of molecular interactions analyzed by HBAT, including hydrogen bonds, halogen bonds, and π interactions.

All interactions have the following core components: - Donor: The electron/proton donor (atom or virtual atom) - Acceptor: The electron/proton acceptor (atom or virtual atom) - Interaction: The mediating atom/point (e.g., hydrogen, π center) - Geometry: Distances and angles defining the interaction - Bonding: The interaction atom must be bonded to the donor atom

Bonding Requirements: - For H-bonds: Hydrogen must be covalently bonded to the donor - For X-bonds: Halogen is covalently bonded to donor carbon - For X-H…π interactions: Hydrogen must be covalently bonded to the donor - For π-π stacking (future): No bonding requirement - uses centroid distances

abstractmethod get_donor() → Atom | NPVec3D

Get the donor atom or virtual atom.

Returns:

The donor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

abstractmethod get_acceptor() → Atom | NPVec3D

Get the acceptor atom or virtual atom.

Returns:

The acceptor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

abstractmethod get_interaction() → Atom | NPVec3D

Get the interaction mediating atom or point.

Returns:

The mediating atom (e.g., hydrogen) or virtual point (e.g., π center)

Return type:

Union[Atom, NPVec3D]

abstractmethod get_donor_residue() → str

Get the donor residue identifier.

Returns:

String identifier for the donor residue

Return type:

str

abstractmethod get_acceptor_residue() → str

Get the acceptor residue identifier.

Returns:

String identifier for the acceptor residue

Return type:

str

abstractmethod get_interaction_type() → str

Get the interaction type.

Returns:

String identifier for the interaction type

Return type:

str

abstractmethod get_donor_interaction_distance() → float

Get the donor to interaction distance.

Returns:

Distance from donor to interaction point in Angstroms

Return type:

float

abstractmethod get_donor_acceptor_distance() → float

Get the donor to acceptor distance.

Returns:

Distance from donor to acceptor in Angstroms

Return type:

float

abstractmethod get_donor_interaction_acceptor_angle() → float

Get the donor-interaction-acceptor angle.

Returns:

Angle in radians

Return type:

float

abstractmethod is_donor_interaction_bonded() → bool

Check if the interaction atom is bonded to the donor atom.

This is a fundamental requirement for most molecular interactions (except π-π stacking which will be implemented separately).

Returns:

True if donor and interaction atom are bonded

Return type:

bool

property donor: Atom | NPVec3D

Property accessor for donor.

property acceptor: Atom | NPVec3D

Property accessor for acceptor.

property interaction: Atom | NPVec3D

Property accessor for interaction.

property donor_residue: str

Property accessor for donor residue.

property acceptor_residue: str

Property accessor for acceptor residue.

property interaction_type: str

Property accessor for interaction type.

property donor_interaction_distance: float

Property accessor for donor-interaction distance.

property donor_acceptor_distance: float

Property accessor for donor-acceptor distance.

property donor_interaction_acceptor_angle: float

Property accessor for donor-interaction-acceptor angle.

get_donor_atom() → Atom | None

Get the donor atom if it’s an Atom instance.

Returns:

The donor atom if it’s an Atom, None otherwise

Return type:

Optional[Atom]

get_acceptor_atom() → Atom | None

Get the acceptor atom if it’s an Atom instance.

Returns:

The acceptor atom if it’s an Atom, None otherwise

Return type:

Optional[Atom]

property distance: float

Legacy property for interaction distance.

Returns:

Donor-interaction distance for backward compatibility

Return type:

float

property angle: float

Legacy property for interaction angle.

Returns:

Donor-interaction-acceptor angle for backward compatibility

Return type:

float

class hbat.core.interactions.HydrogenBond(_donor: Atom, hydrogen: Atom, _acceptor: Atom, distance: float, angle: float, _donor_acceptor_distance: float, bond_type: str, _donor_residue: str, _acceptor_residue: str)

Bases: MolecularInteraction

Represents a hydrogen bond interaction.

This class stores all information about a detected hydrogen bond, including the participating atoms, geometric parameters, and classification information.

Parameters:

• _donor (Atom) – The hydrogen bond donor atom

• hydrogen (Atom) – The hydrogen atom in the bond

• _acceptor (Atom) – The hydrogen bond acceptor atom

• distance (float) – H…A distance in Angstroms

• angle (float) – D-H…A angle in radians

• _donor_acceptor_distance (float) – D…A distance in Angstroms

• bond_type (str) – Classification of the hydrogen bond type

• _donor_residue (str) – Identifier for donor residue

• _acceptor_residue (str) – Identifier for acceptor residue

__init__(_donor: Atom, hydrogen: Atom, _acceptor: Atom, distance: float, angle: float, _donor_acceptor_distance: float, bond_type: str, _donor_residue: str, _acceptor_residue: str)

Initialize a HydrogenBond object.

Parameters:

• _donor (Atom) – The hydrogen bond donor atom

• hydrogen (Atom) – The hydrogen atom in the bond

• _acceptor (Atom) – The hydrogen bond acceptor atom

• distance (float) – H…A distance in Angstroms

• angle (float) – D-H…A angle in radians

• _donor_acceptor_distance (float) – D…A distance in Angstroms

• bond_type (str) – Classification of the hydrogen bond type

• _donor_residue (str) – Identifier for donor residue

• _acceptor_residue (str) – Identifier for acceptor residue

property distance: float

Legacy property for interaction distance.

Returns:

Donor-interaction distance for backward compatibility

Return type:

float

property angle: float

Legacy property for interaction angle.

Returns:

Donor-interaction-acceptor angle for backward compatibility

Return type:

float

property donor: Atom

Property accessor for donor atom.

property acceptor: Atom

Property accessor for acceptor atom.

get_donor() → Atom | NPVec3D

Get the donor atom or virtual atom.

Returns:

The donor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D

Get the acceptor atom or virtual atom.

Returns:

The acceptor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D

Get the interaction mediating atom or point.

Returns:

The mediating atom (e.g., hydrogen) or virtual point (e.g., π center)

Return type:

Union[Atom, NPVec3D]

get_donor_residue() → str

Get the donor residue identifier.

Returns:

String identifier for the donor residue

Return type:

str

get_acceptor_residue() → str

Get the acceptor residue identifier.

Returns:

String identifier for the acceptor residue

Return type:

str

get_interaction_type() → str

Get the interaction type.

Returns:

String identifier for the interaction type

Return type:

str

get_donor_interaction_distance() → float

Distance from donor to hydrogen.

get_donor_acceptor_distance() → float

Distance from donor to acceptor.

get_donor_interaction_acceptor_angle() → float

D-H…A angle.

is_donor_interaction_bonded() → bool

Check if hydrogen is bonded to donor.

For hydrogen bonds, the hydrogen must be covalently bonded to the donor atom. This method assumes the bond has been validated during creation.

Returns:

True (assumes validation was done during creation)

Return type:

bool

property donor_acceptor_properties: str

Get the donor-acceptor property description.

Returns:

Property description string

Return type:

str

get_backbone_sidechain_interaction() → str

Get simplified backbone/sidechain interaction description.

Returns:

Interaction type (B-B, B-S, S-B, S-S)

Return type:

str

class hbat.core.interactions.HalogenBond(halogen: Atom, _acceptor: Atom, distance: float, angle: float, bond_type: str, _halogen_residue: str, _acceptor_residue: str, _donor: Atom)

Bases: MolecularInteraction

Represents a halogen bond interaction.

This class stores information about a detected halogen bond, where a halogen atom (Cl, Br, I) acts as an electrophilic center interacting with nucleophilic acceptors. HBAT uses updated default parameters with a 150° angle cutoff for improved detection of biologically relevant halogen bonds.

Parameters:

• halogen (Atom) – The halogen atom (F, Cl, Br, I)

• _acceptor (Atom) – The electron donor/acceptor atom

• distance (float) – X…A distance in Angstroms

• angle (float) – C-X…A angle in radians (default cutoff: 150°)

• bond_type (str) – Classification of the halogen bond type

• _halogen_residue (str) – Identifier for halogen-containing residue

• _acceptor_residue (str) – Identifier for acceptor residue

• _donor (Atom) – The donor atom (typically carbon) bonded to the halogen

__init__(halogen: Atom, _acceptor: Atom, distance: float, angle: float, bond_type: str, _halogen_residue: str, _acceptor_residue: str, _donor: Atom)

Initialize a HalogenBond object.

Parameters:

• halogen (Atom) – The halogen atom (F, Cl, Br, I)

• _acceptor (Atom) – The electron donor/acceptor atom

• distance (float) – X…A distance in Angstroms

• angle (float) – C-X…A angle in radians

• bond_type (str) – Classification of the halogen bond type

• _halogen_residue (str) – Identifier for halogen-containing residue

• _acceptor_residue (str) – Identifier for acceptor residue

• _donor (Atom) – The donor atom (typically carbon) bonded to the halogen

property distance: float

Legacy property for interaction distance.

Returns:

Donor-interaction distance for backward compatibility

Return type:

float

property angle: float

Legacy property for interaction angle.

Returns:

Donor-interaction-acceptor angle for backward compatibility

Return type:

float

property halogen_residue: str

Legacy property for halogen residue.

property donor: Atom

Property accessor for donor atom (halogen).

property donor_atom: Atom

Property accessor for donor atom (carbon bonded to halogen).

property acceptor: Atom

Property accessor for acceptor atom.

get_donor() → Atom | NPVec3D

Get the donor atom or virtual atom.

Returns:

The donor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D

Get the acceptor atom or virtual atom.

Returns:

The acceptor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D

Get the interaction mediating atom or point.

Returns:

The mediating atom (e.g., hydrogen) or virtual point (e.g., π center)

Return type:

Union[Atom, NPVec3D]

get_donor_residue() → str

Get the donor residue identifier.

Returns:

String identifier for the donor residue

Return type:

str

get_acceptor_residue() → str

Get the acceptor residue identifier.

Returns:

String identifier for the acceptor residue

Return type:

str

get_interaction_type() → str

Get the interaction type.

Returns:

String identifier for the interaction type

Return type:

str

get_donor_interaction_distance() → float

Distance from donor to interaction point (0 for halogen bonds).

get_donor_acceptor_distance() → float

Distance from halogen to acceptor.

get_donor_interaction_acceptor_angle() → float

C-X…A angle.

is_donor_interaction_bonded() → bool

Check if halogen is bonded to donor carbon.

For halogen bonds, the halogen atom must be covalently bonded to a carbon atom. The halogen serves as both the donor and interaction point.

Returns:

True (assumes validation was done during creation)

Return type:

bool

property donor_acceptor_properties: str

Get the donor-acceptor property description.

Returns:

Property description string

Return type:

str

get_backbone_sidechain_interaction() → str

Get simplified backbone/sidechain interaction description.

Returns:

Interaction type (B-B, B-S, S-B, S-S)

Return type:

str

class hbat.core.interactions.PiInteraction(_donor: Atom, hydrogen: Atom, pi_center: NPVec3D, distance: float, angle: float, _donor_residue: str, _pi_residue: str)

Bases: MolecularInteraction

Represents a D-X…π interaction.

This class stores information about a detected D-X…π interaction, where a donor atom with an interaction atom (H, F, Cl, Br, I) interacts with an aromatic π system. Supports multiple subtypes: - C-H…π, N-H…π, O-H…π, S-H…π (hydrogen-π interactions) - C-Cl…π, C-Br…π, C-I…π (halogen-π interactions)

Parameters:

• _donor (Atom) – The donor atom (C, N, O, S)

• hydrogen (Atom) – The interaction atom (H, F, Cl, Br, I) - name kept for backward compatibility

• pi_center (NPVec3D) – Center of the aromatic π system

• distance (float) – X…π distance in Angstroms

• angle (float) – D-X…π angle in radians

• _donor_residue (str) – Identifier for donor residue

• _pi_residue (str) – Identifier for π-containing residue

__init__(_donor: Atom, hydrogen: Atom, pi_center: NPVec3D, distance: float, angle: float, _donor_residue: str, _pi_residue: str)

Initialize a PiInteraction object.

Parameters:

• _donor (Atom) – The donor atom (C, N, O, S)

• hydrogen (Atom) – The interaction atom (H, F, Cl, Br, I) - name kept for backward compatibility

• pi_center (NPVec3D) – Center of the aromatic π system

• distance (float) – X…π distance in Angstroms

• angle (float) – D-X…π angle in radians

• _donor_residue (str) – Identifier for donor residue

• _pi_residue (str) – Identifier for π-containing residue

property distance: float

Legacy property for interaction distance.

Returns:

Donor-interaction distance for backward compatibility

Return type:

float

property angle: float

Legacy property for interaction angle.

Returns:

Donor-interaction-acceptor angle for backward compatibility

Return type:

float

property pi_residue: str

Legacy property for π residue.

property donor: Atom

Property accessor for donor atom.

get_donor() → Atom | NPVec3D

Get the donor atom or virtual atom.

Returns:

The donor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D

Get the acceptor atom or virtual atom.

Returns:

The acceptor atom or virtual atom position

Return type:

Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D

Get the interaction mediating atom or point.

Returns:

The mediating atom (e.g., hydrogen) or virtual point (e.g., π center)

Return type:

Union[Atom, NPVec3D]

get_donor_residue() → str

Get the donor residue identifier.

Returns:

String identifier for the donor residue

Return type:

str

get_acceptor_residue() → str

Get the acceptor residue identifier.

Returns:

String identifier for the acceptor residue

Return type:

str

get_interaction_type() → str

Get the interaction type.

Returns:

String identifier for the interaction type

Return type:

str

get_donor_interaction_distance() → float

Distance from donor to interaction atom.

get_donor_acceptor_distance() → float

Distance from donor to π center.

get_donor_interaction_acceptor_angle() → float

D-H…π angle.

is_donor_interaction_bonded() → bool

Check if hydrogen is bonded to donor.

For X-H…π interactions, the hydrogen must be covalently bonded to the donor atom.

Returns:

True (assumes validation was done during creation)

Return type:

bool

property donor_acceptor_properties: str

Get the donor-acceptor property description.

Returns:

Property description string

Return type:

str

get_backbone_sidechain_interaction() → str

Get simplified backbone/sidechain interaction description.

Returns:

Interaction type (B-S, S-S, etc.)

Return type:

str

get_interaction_type_display() → str

Get the interaction type for display purposes.

Generates display strings for different π interaction subtypes:

Hydrogen-π interactions: - “C-H…π” for carbon-hydrogen to π system - “N-H…π” for nitrogen-hydrogen to π system - “O-H…π” for oxygen-hydrogen to π system - “S-H…π” for sulfur-hydrogen to π system

Halogen-π interactions: - “C-Cl…π” for carbon-chlorine to π system - “C-Br…π” for carbon-bromine to π system - “C-I…π” for carbon-iodine to π system

Returns:

Display format showing donor-interaction…π pattern

Return type:

str

class hbat.core.interactions.PiPiInteraction(ring1_atoms: List[Atom], ring2_atoms: List[Atom], ring1_center: NPVec3D, ring2_center: NPVec3D, distance: float, plane_angle: float, offset: float, stacking_type: str, ring1_type: str, ring2_type: str, ring1_residue: str, ring2_residue: str)

Bases: MolecularInteraction

Represents a π-π stacking interaction between aromatic rings.

This class stores information about detected π-π interactions, which are important for protein stability, molecular recognition, and drug binding. Interactions are classified as parallel, T-shaped, or offset based on the angle between ring planes and the lateral displacement.

Parameters:

• ring1_atoms (List[Atom]) – Atoms in the first aromatic ring

• ring2_atoms (List[Atom]) – Atoms in the second aromatic ring

• ring1_center (NPVec3D) – Centroid of the first ring

• ring2_center (NPVec3D) – Centroid of the second ring

• distance (float) – Centroid-to-centroid distance in Angstroms

• plane_angle (float) – Angle between ring planes in degrees

• offset (float) – Lateral displacement in Angstroms (for parallel stacking)

• stacking_type (str) – Classification (“parallel”, “T-shaped”, or “offset”)

• ring1_type (str) – Type of first ring (e.g., PHE, TYR, TRP, HIS)

• ring2_type (str) – Type of second ring (e.g., PHE, TYR, TRP, HIS)

• ring1_residue (str) – Identifier for first ring’s residue

• ring2_residue (str) – Identifier for second ring’s residue

__init__(ring1_atoms: List[Atom], ring2_atoms: List[Atom], ring1_center: NPVec3D, ring2_center: NPVec3D, distance: float, plane_angle: float, offset: float, stacking_type: str, ring1_type: str, ring2_type: str, ring1_residue: str, ring2_residue: str)

Initialize a PiPiInteraction object.

Parameters:

• ring1_atoms (List[Atom]) – Atoms in the first aromatic ring

• ring2_atoms (List[Atom]) – Atoms in the second aromatic ring

• ring1_center (NPVec3D) – Centroid of the first ring

• ring2_center (NPVec3D) – Centroid of the second ring

• distance (float) – Centroid-to-centroid distance in Angstroms

• plane_angle (float) – Angle between ring planes in degrees

• offset (float) – Lateral displacement in Angstroms

• stacking_type (str) – Classification (“parallel”, “T-shaped”, or “offset”)

• ring1_type (str) – Type of first ring (e.g., PHE, TYR, TRP, HIS)

• ring2_type (str) – Type of second ring (e.g., PHE, TYR, TRP, HIS)

• ring1_residue (str) – Identifier for first ring’s residue

• ring2_residue (str) – Identifier for second ring’s residue

property distance: float

Centroid-to-centroid distance.

property angle: float

Angle between ring planes in radians (for consistency with other interactions).

property interaction_classification: str

Get the stacking classification (for consistency with other interaction types).

Returns:

The stacking type (“parallel”, “T-shaped”, or “offset”)

Return type:

str

get_donor() → Atom | NPVec3D

Get the first ring centroid (arbitrarily designated as donor).

Returns:

Centroid of the first aromatic ring

Return type:

NPVec3D

get_acceptor() → Atom | NPVec3D

Get the second ring centroid (arbitrarily designated as acceptor).

Returns:

Centroid of the second aromatic ring

Return type:

NPVec3D

get_interaction() → Atom | NPVec3D

Get the interaction point (midpoint between centroids).

Returns:

Midpoint between the two ring centroids

Return type:

NPVec3D

get_donor_residue() → str

Get the first ring’s residue identifier.

Returns:

Residue identifier for the first ring

Return type:

str

get_acceptor_residue() → str

Get the second ring’s residue identifier.

Returns:

Residue identifier for the second ring

Return type:

str

get_interaction_type() → str

Get the interaction type identifier.

Returns:

“Pi-Pi” as the interaction type

Return type:

str

get_stacking_type() → str

Get the specific stacking geometry classification.

Returns:

“parallel”, “T-shaped”, or “offset”

Return type:

str

get_donor_interaction_distance() → float

Distance from first ring centroid to midpoint.

Returns:

Half of the centroid-to-centroid distance

Return type:

float

get_donor_acceptor_distance() → float

Distance between ring centroids.

Returns:

Centroid-to-centroid distance

Return type:

float

get_donor_interaction_acceptor_angle() → float

Angle between ring planes in radians.

For π-π interactions, this represents the dihedral angle between the two aromatic ring planes.

Returns:

Angle between planes in radians

Return type:

float

is_donor_interaction_bonded() → bool

Check if bonding requirement is satisfied.

π-π interactions are non-covalent and don’t require bonding between the interacting rings.

Returns:

False (no bonding requirement for π-π stacking)

Return type:

bool

get_ring_atoms(ring_num: int) → List[Atom]

Get atoms of a specific ring.

Parameters:

ring_num (int) – Ring number (1 or 2)

Returns:

List of atoms in the specified ring

Return type:

List[Atom]

__str__() → str

String representation of the π-π interaction.

Returns:

Human-readable description of the interaction

Return type:

str

class hbat.core.interactions.CarbonylInteraction(donor_carbon: Atom, donor_oxygen: Atom, acceptor_carbon: Atom, acceptor_oxygen: Atom, distance: float, burgi_dunitz_angle: float, is_backbone: bool, donor_residue: str, acceptor_residue: str)

Bases: MolecularInteraction

Represents a carbonyl-carbonyl n→π* interaction between C=O groups.

This class stores information about detected n→π* interactions between carbonyl groups, which are important for protein stability and secondary structure formation. The interaction follows the Bürgi-Dunitz trajectory where the donor oxygen approaches the acceptor carbon.

Parameters:

• donor_carbon (Atom) – C atom of the donor C=O group

• donor_oxygen (Atom) – O atom of the donor C=O group

• acceptor_carbon (Atom) – C atom of the acceptor C=O group

• acceptor_oxygen (Atom) – O atom of the acceptor C=O group

• distance (float) – O···C distance in Angstroms

• burgi_dunitz_angle (float) – O···C=O angle in degrees (typically 95-125°)

• is_backbone (bool) – Whether both carbonyls are from backbone amides

• donor_residue (str) – Identifier for donor residue

• acceptor_residue (str) – Identifier for acceptor residue

__init__(donor_carbon: Atom, donor_oxygen: Atom, acceptor_carbon: Atom, acceptor_oxygen: Atom, distance: float, burgi_dunitz_angle: float, is_backbone: bool, donor_residue: str, acceptor_residue: str)

Initialize a CarbonylInteraction object.

Parameters:

• donor_carbon (Atom) – C atom of the donor C=O group

• donor_oxygen (Atom) – O atom of the donor C=O group

• acceptor_carbon (Atom) – C atom of the acceptor C=O group

• acceptor_oxygen (Atom) – O atom of the acceptor C=O group

• distance (float) – O···C distance in Angstroms

• burgi_dunitz_angle (float) – O···C=O angle in degrees

• is_backbone (bool) – Whether both carbonyls are from backbone amides

• donor_residue (str) – Identifier for donor residue

• acceptor_residue (str) – Identifier for acceptor residue

property distance: float

O···C distance in Angstroms.

property angle: float

Bürgi-Dunitz angle in radians (for consistency with other interactions).

property carbonyl_type: str

Get the carbonyl interaction type (for GUI compatibility).

get_donor() → Atom | NPVec3D

Get the donor oxygen atom.

The donor oxygen contributes its lone pair electrons to the interaction.

Returns:

Donor oxygen atom

Return type:

Atom

get_acceptor() → Atom | NPVec3D

Get the acceptor carbon atom.

The acceptor carbon receives electron density in the n→π* interaction.

Returns:

Acceptor carbon atom

Return type:

Atom

get_interaction() → Atom | NPVec3D

Get the interaction point (donor oxygen).

For carbonyl interactions, the donor oxygen is both the electron donor and the interaction point.

Returns:

Donor oxygen atom

Return type:

Atom

get_donor_residue() → str

Get the donor residue identifier.

Returns:

Residue identifier containing the donor carbonyl

Return type:

str

get_acceptor_residue() → str

Get the acceptor residue identifier.

Returns:

Residue identifier containing the acceptor carbonyl

Return type:

str

get_interaction_type() → str

Get the interaction type identifier.

Returns:

“Carbonyl-Carbonyl” as the interaction type

Return type:

str

is_backbone_interaction() → bool

Check if this is a backbone-backbone interaction.

Returns:

True if both carbonyls are from backbone amides

Return type:

bool

get_donor_interaction_distance() → float

Distance from donor carbon to donor oxygen.

Returns:

C=O bond length (approximately 1.2-1.3 Å)

Return type:

float

get_donor_acceptor_distance() → float

Distance from donor oxygen to acceptor carbon.

Returns:

O···C distance in Angstroms

Return type:

float

get_donor_interaction_acceptor_angle() → float

Bürgi-Dunitz angle in radians.

This is the O···C=O angle that defines the trajectory of approach for the n→π* interaction.

Returns:

Bürgi-Dunitz angle in radians

Return type:

float

is_donor_interaction_bonded() → bool

Check if the donor oxygen is bonded to the donor carbon.

For carbonyl interactions, the donor oxygen must be covalently bonded to the donor carbon in a C=O group.

Returns:

True (oxygen is bonded to carbon in C=O)

Return type:

bool

get_carbonyl_atoms(carbonyl_type: str) → tuple

Get atoms of a specific carbonyl group.

Parameters:

carbonyl_type (str) – “donor” or “acceptor”

Returns:

Tuple of (carbon, oxygen) atoms

Return type:

tuple

__str__() → str

String representation of the carbonyl interaction.

Returns:

Human-readable description of the interaction

Return type:

str

class hbat.core.interactions.NPiInteraction(lone_pair_atom: Atom, pi_center: NPVec3D, pi_atoms: List[Atom], distance: float, angle_to_plane: float, subtype: str, donor_residue: str, acceptor_residue: str)

Bases: MolecularInteraction

Represents a general n→π* interaction between lone pairs and π systems.

This class stores information about detected n→π* interactions where lone pair electrons from atoms (O, N, S) interact with aromatic π systems. These interactions are important in molecular recognition, enzyme active sites, and protein-ligand binding.

Parameters:

• lone_pair_atom (Atom) – Donor atom with lone pair electrons (O, N, S)

• pi_center (NPVec3D) – Center of the π system

• pi_atoms (List[Atom]) – Atoms constituting the π system

• distance (float) – Lone pair to π center distance in Angstroms

• angle_to_plane (float) – Angle to π plane normal in degrees

• subtype (str) – Interaction subtype classification

• donor_residue (str) – Identifier for residue containing lone pair

• acceptor_residue (str) – Identifier for residue containing π system

__init__(lone_pair_atom: Atom, pi_center: NPVec3D, pi_atoms: List[Atom], distance: float, angle_to_plane: float, subtype: str, donor_residue: str, acceptor_residue: str)

Initialize an NPiInteraction object.

Parameters:

• lone_pair_atom (Atom) – Donor atom with lone pair electrons (O, N, S)

• pi_center (NPVec3D) – Center of the π system

• pi_atoms (List[Atom]) – Atoms constituting the π system

• distance (float) – Lone pair to π center distance in Angstroms

• angle_to_plane (float) – Angle to π plane normal in degrees

• subtype (str) – Interaction subtype classification

• donor_residue (str) – Identifier for residue containing lone pair

• acceptor_residue (str) – Identifier for residue containing π system

property distance: float

Lone pair to π center distance in Angstroms.

property angle: float

Angle to π plane in radians (for consistency with other interactions).

property interaction_classification: str

Get the interaction subtype classification (for consistency with other interaction types).

Returns:

The subtype classification

Return type:

str

get_donor() → Atom | NPVec3D

Get the lone pair donor atom.

The lone pair atom contributes electron density to the π system.

Returns:

Lone pair donor atom

Return type:

Atom

get_acceptor() → Atom | NPVec3D

Get the π system center.

The π system center represents the electron-deficient acceptor.

Returns:

π system centroid

Return type:

NPVec3D

get_interaction() → Atom | NPVec3D

Get the interaction point (lone pair atom).

For n→π* interactions, the lone pair atom is the interaction point that donates electron density to the π system.

Returns:

Lone pair donor atom

Return type:

Atom

get_donor_residue() → str

Get the donor residue identifier.

Returns:

Residue identifier containing the lone pair donor

Return type:

str

get_acceptor_residue() → str

Get the acceptor residue identifier.

Returns:

Residue identifier containing the π system

Return type:

str

get_interaction_type() → str

Get the interaction type identifier.

Returns:

“n-Pi” as the interaction type

Return type:

str

get_subtype() → str

Get the specific n→π* interaction subtype.

Returns:

Subtype classification (e.g., “carbonyl-aromatic”, “amine-aromatic”)

Return type:

str

get_donor_element() → str

Get the donor atom element.

Returns:

Element symbol of the lone pair donor (O, N, or S)

Return type:

str

get_donor_interaction_distance() → float

Distance from lone pair atom to π center (same as total distance).

For n→π* interactions, there’s no intermediate atom, so this is the same as the donor-acceptor distance.

Returns:

Lone pair to π center distance

Return type:

float

get_donor_acceptor_distance() → float

Distance from lone pair donor to π system center.

Returns:

Lone pair to π center distance in Angstroms

Return type:

float

get_donor_interaction_acceptor_angle() → float

Angle to π plane normal in radians.

This represents the angle between the lone pair vector and the normal to the π system plane.

Returns:

Angle to π plane normal in radians

Return type:

float

is_donor_interaction_bonded() → bool

Check if bonding requirement is satisfied.

n→π* interactions are direct interactions between the lone pair and π system, so no intermediate bonding is required.

Returns:

False (no bonding requirement for n→π* interactions)

Return type:

bool

get_pi_atoms() → List[Atom]

Get atoms constituting the π system.

Returns:

List of atoms in the π system

Return type:

List[Atom]

is_carbonyl_donor() → bool

Check if the donor is a carbonyl oxygen.

Returns:

True if donor is carbonyl oxygen

Return type:

bool

is_amine_donor() → bool

Check if the donor is an amine nitrogen.

Returns:

True if donor is amine nitrogen

Return type:

bool

is_sulfur_donor() → bool

Check if the donor is a sulfur atom.

Returns:

True if donor is sulfur atom

Return type:

bool

__str__() → str

String representation of the n→π* interaction.

Returns:

Human-readable description of the interaction

Return type:

str

class hbat.core.interactions.CooperativityChain(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str)

Bases: MolecularInteraction

Represents a chain of cooperative molecular interactions.

This class represents a series of linked molecular interactions where the acceptor of one interaction acts as the donor of the next, creating cooperative effects.

Parameters:

• interactions (List[Union[HydrogenBond, HalogenBond, PiInteraction]]) – List of interactions in the chain

• chain_length (int) – Number of interactions in the chain

• chain_type (str) – Description of the interaction types in the chain

__init__(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str)

Initialize a CooperativityChain object.

Parameters:

• interactions (List[Union[HydrogenBond, HalogenBond, PiInteraction]]) – List of interactions in the chain

• chain_length (int) – Number of interactions in the chain

• chain_type (str) – Description of the interaction types in the chain

get_donor() → Atom | NPVec3D

Get the donor of the first interaction in the chain.

get_acceptor() → Atom | NPVec3D

Get the acceptor of the last interaction in the chain.

get_interaction() → Atom | NPVec3D

Get the center point of the chain (middle interaction point).

get_donor_residue() → str

Get the donor residue of the first interaction.

get_acceptor_residue() → str

Get the acceptor residue of the last interaction.

get_interaction_type() → str

Get the interaction type.

Returns:

String identifier for the interaction type

Return type:

str

get_donor_interaction_distance() → float

Get the distance from chain start to middle interaction.

get_donor_acceptor_distance() → float

Get the distance from chain start to end.

get_donor_interaction_acceptor_angle() → float

Get the angle across the chain (donor-middle-acceptor).

is_donor_interaction_bonded() → bool

Check if interactions in the chain satisfy bonding requirements.

For cooperativity chains, each individual interaction must satisfy its own bonding requirements.

Returns:

True if all interactions in chain are properly bonded

Return type:

bool