Module Overview

Module Overview#

The core package is organized into specialized modules:

np_analyzer: Molecular interaction analysis engine
interactions: Data structures for molecular interactions
structure: Molecular structure classes (Atom, Bond, Residue)
pdb_parser: PDB file parsing and structure handling
pdb_fixer: PDB structure enhancement and fixing
np_vector: NumPy-based 3D vector mathematics for high-performance calculations

Main Analysis Engine#

Molecular Interaction Analyzer#

High-performance molecular interaction analyzer for HBAT.

This module provides the main analyzer using NumPy for vectorized calculations of molecular interactions in protein structures.

class hbat.core.np_analyzer.NPMolecularInteractionAnalyzer(parameters: AnalysisParameters | None = None)[source]#

Bases: object

High-performance analyzer for molecular interactions.

This analyzer uses vectorized NumPy operations for efficient analysis of molecular interactions in protein structures. Supports comprehensive detection of:

Hydrogen bonds: Classical N-H···O, O-H···O, N-H···N interactions
Weak hydrogen bonds: C-H···O interactions (important in protein-ligand binding)
Halogen bonds: C-X···A interactions where X is Cl, Br, I (default angle: 150°)
π interactions: Multiple subtypes including:
- Hydrogen-π: C-H···π, N-H···π, O-H···π, S-H···π
- Halogen-π: C-Cl···π, C-Br···π, C-I···π
Cooperativity chains: Networks of linked interactions

Parameters:: parameters (Optional[AnalysisParameters]) – Analysis parameters with subtype-specific cutoffs

__init__(parameters: AnalysisParameters | None = None)[source]#: Initialize analyzer with parameters.

analyze_file(pdb_file: str) → bool[source]#

Analyze a PDB file for molecular interactions.

Performs comprehensive analysis of hydrogen bonds, weak hydrogen bonds (C-H···O), halogen bonds, π interactions (including subtypes: C-H···π, N-H···π, O-H···π, S-H···π, C-Cl···π, C-Br···π, C-I···π), and cooperativity chains in the provided PDB structure. Optionally applies PDB fixing to add missing atoms if enabled in parameters.

Parameters:: pdb_file (str) – Path to PDB file to analyze
Returns:: True if analysis completed successfully, False if parsing failed
Return type:: bool
Raises:: Exception – If PDB fixing fails when enabled

get_summary() → Dict[str, Any][source]#

Get comprehensive analysis summary with statistics, PDB fixing info, and timing.

Returns a dictionary containing interaction counts, averages, bond type distributions, PDB fixing information (if applied), and analysis timing.

Returns:: Dictionary containing comprehensive analysis summary
Return type:: Dict[str, Any]

class hbat.core.np_analyzer.NPMolecularInteractionAnalyzer(parameters: AnalysisParameters | None = None)[source]#

Bases: object

High-performance analyzer for molecular interactions.

This analyzer uses vectorized NumPy operations for efficient analysis of molecular interactions in protein structures. Supports comprehensive detection of:

Hydrogen bonds: Classical N-H···O, O-H···O, N-H···N interactions
Weak hydrogen bonds: C-H···O interactions (important in protein-ligand binding)
Halogen bonds: C-X···A interactions where X is Cl, Br, I (default angle: 150°)
π interactions: Multiple subtypes including:
- Hydrogen-π: C-H···π, N-H···π, O-H···π, S-H···π
- Halogen-π: C-Cl···π, C-Br···π, C-I···π
Cooperativity chains: Networks of linked interactions

Parameters:: parameters (Optional[AnalysisParameters]) – Analysis parameters with subtype-specific cutoffs

High-performance molecular interaction analysis engine using vectorized NumPy operations.

Key Features:

Hydrogen bond detection with geometric and chemical criteria
Halogen bond identification with σ-hole directionality
π-π stacking and X-H…π interaction analysis
Cooperative interaction chain detection
Comprehensive statistics and PDB fixing integration
35x performance improvement through spatial grid optimization

Usage Example:

from hbat.core.np_analyzer import NPMolecularInteractionAnalyzer
from hbat.constants.parameters import AnalysisParameters

# Initialize analyzer with parameters
params = AnalysisParameters()
params.fix_pdb_enabled = True
analyzer = NPMolecularInteractionAnalyzer(params)

# Analyze PDB file (includes optional PDB fixing)
success = analyzer.analyze_file("structure.pdb")

# Get comprehensive summary with statistics and timing
summary = analyzer.get_summary()
print(f"Found {summary['hydrogen_bonds']['count']} hydrogen bonds")
print(f"Analysis completed in {summary['timing']['analysis_duration_seconds']} seconds")

__init__(parameters: AnalysisParameters | None = None)[source]#: Initialize analyzer with parameters.

analyze_file(pdb_file: str) → bool[source]#

Analyze a PDB file for molecular interactions.

Parameters:: pdb_file (str) – Path to PDB file to analyze
Returns:: True if analysis completed successfully, False if parsing failed
Return type:: bool
Raises:: Exception – If PDB fixing fails when enabled

get_summary() → Dict[str, Any][source]#

Get comprehensive analysis summary with statistics, PDB fixing info, and timing.

Returns a dictionary containing interaction counts, averages, bond type distributions, PDB fixing information (if applied), and analysis timing.

Returns:: Dictionary containing comprehensive analysis summary
Return type:: Dict[str, Any]

Interaction Data Structures#

Molecular Interaction Classes#

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[source]#

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[source]#

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[source]#

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[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

abstractmethod get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

abstractmethod get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

abstractmethod get_donor_interaction_distance() → float[source]#

Get the donor to interaction distance.

Returns:: Distance from donor to interaction point in Angstroms
Return type:: float

abstractmethod get_donor_acceptor_distance() → float[source]#

Get the donor to acceptor distance.

Returns:: Distance from donor to acceptor in Angstroms
Return type:: float

abstractmethod get_donor_interaction_acceptor_angle() → float[source]#

Get the donor-interaction-acceptor angle.

Returns:: Angle in radians
Return type:: float

abstractmethod is_donor_interaction_bonded() → bool[source]#

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[source]#

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[source]#

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)[source]#

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)[source]#

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[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Distance from donor to hydrogen.

get_donor_acceptor_distance() → float[source]#: Distance from donor to acceptor.

get_donor_interaction_acceptor_angle() → float[source]#: D-H…A angle.

is_donor_interaction_bonded() → bool[source]#

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[source]#

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)[source]#

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

__init__(halogen: Atom, _acceptor: Atom, distance: float, angle: float, bond_type: str, _halogen_residue: str, _acceptor_residue: str)[source]#

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

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 acceptor: Atom#: Property accessor for acceptor atom.

get_donor() → Atom | NPVec3D[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Distance from donor to interaction point (0 for halogen bonds).

get_donor_acceptor_distance() → float[source]#: Distance from halogen to acceptor.

get_donor_interaction_acceptor_angle() → float[source]#: C-X…A angle.

is_donor_interaction_bonded() → bool[source]#

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[source]#

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)[source]#

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)[source]#

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[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Distance from donor to interaction atom.

get_donor_acceptor_distance() → float[source]#: Distance from donor to π center.

get_donor_interaction_acceptor_angle() → float[source]#: D-H…π angle.

is_donor_interaction_bonded() → bool[source]#

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[source]#

Get simplified backbone/sidechain interaction description.

Returns:: Interaction type (B-S, S-S, etc.)
Return type:: str

get_interaction_type_display() → str[source]#

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.CooperativityChain(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str)[source]#

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)[source]#

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[source]#: Get the donor of the first interaction in the chain.

get_acceptor() → Atom | NPVec3D[source]#: Get the acceptor of the last interaction in the chain.

get_interaction() → Atom | NPVec3D[source]#: Get the center point of the chain (middle interaction point).

get_donor_residue() → str[source]#: Get the donor residue of the first interaction.

get_acceptor_residue() → str[source]#: Get the acceptor residue of the last interaction.

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Get the distance from chain start to middle interaction.

get_donor_acceptor_distance() → float[source]#: Get the distance from chain start to end.

get_donor_interaction_acceptor_angle() → float[source]#: Get the angle across the chain (donor-middle-acceptor).

is_donor_interaction_bonded() → bool[source]#

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

Base Interaction Class#

class hbat.core.interactions.MolecularInteraction[source]#

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.

Abstract base class for all molecular interactions, providing common interface and validation.

abstractmethod get_donor() → Atom | NPVec3D[source]#

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[source]#

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[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

abstractmethod get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

abstractmethod get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

abstractmethod get_donor_interaction_distance() → float[source]#

Get the donor to interaction distance.

Returns:: Distance from donor to interaction point in Angstroms
Return type:: float

abstractmethod get_donor_acceptor_distance() → float[source]#

Get the donor to acceptor distance.

Returns:: Distance from donor to acceptor in Angstroms
Return type:: float

abstractmethod get_donor_interaction_acceptor_angle() → float[source]#

Get the donor-interaction-acceptor angle.

Returns:: Angle in radians
Return type:: float

abstractmethod is_donor_interaction_bonded() → bool[source]#

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[source]#

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[source]#

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

Specific Interaction Types#

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

Dataclass representing a hydrogen bond with donor-hydrogen-acceptor geometry.

Geometric Parameters:

Distance (D-A): Donor to acceptor distance
Angle (D-H…A): Donor-hydrogen-acceptor angle
Energy estimation based on distance and angle

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[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Distance from donor to hydrogen.

get_donor_acceptor_distance() → float[source]#: Distance from donor to acceptor.

get_donor_interaction_acceptor_angle() → float[source]#: D-H…A angle.

is_donor_interaction_bonded() → bool[source]#

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[source]#

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)[source]#

Bases: MolecularInteraction

Represents a halogen bond interaction.

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

Dataclass representing a halogen bond with carbon-halogen…acceptor geometry.

Geometric Parameters:

Distance (X…A): Halogen to acceptor distance
Angle (C-X…A): Carbon-halogen-acceptor angle
σ-hole directionality validation

__init__(halogen: Atom, _acceptor: Atom, distance: float, angle: float, bond_type: str, _halogen_residue: str, _acceptor_residue: str)[source]#

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

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 acceptor: Atom#: Property accessor for acceptor atom.

get_donor() → Atom | NPVec3D[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Distance from donor to interaction point (0 for halogen bonds).

get_donor_acceptor_distance() → float[source]#: Distance from halogen to acceptor.

get_donor_interaction_acceptor_angle() → float[source]#: C-X…A angle.

is_donor_interaction_bonded() → bool[source]#

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[source]#

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)[source]#

Bases: MolecularInteraction

Represents a D-X…π interaction.

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

Dataclass representing π interactions including π-π stacking and X-H…π contacts.

Geometric Parameters:

Centroid distance: Distance between aromatic centroids
Ring angles: Angle between ring planes
Offset parameters: Lateral displacement measurements

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

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[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_interaction() → Atom | NPVec3D[source]#

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[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Distance from donor to interaction atom.

get_donor_acceptor_distance() → float[source]#: Distance from donor to π center.

get_donor_interaction_acceptor_angle() → float[source]#: D-H…π angle.

is_donor_interaction_bonded() → bool[source]#

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[source]#

Get simplified backbone/sidechain interaction description.

Returns:: Interaction type (B-S, S-S, etc.)
Return type:: str

get_interaction_type_display() → str[source]#

Get the interaction type for display purposes.

Generates display strings for different π interaction subtypes:

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.CooperativityChain(interactions: List[HydrogenBond | HalogenBond | PiInteraction], chain_length: int, chain_type: str)[source]#

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

Dataclass representing chains of cooperative molecular interactions.

Chain Analysis:

Sequential interaction connectivity
Cumulative interaction strength
Chain topology classification

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

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[source]#: Get the donor of the first interaction in the chain.

get_acceptor() → Atom | NPVec3D[source]#: Get the acceptor of the last interaction in the chain.

get_interaction() → Atom | NPVec3D[source]#: Get the center point of the chain (middle interaction point).

get_donor_residue() → str[source]#: Get the donor residue of the first interaction.

get_acceptor_residue() → str[source]#: Get the acceptor residue of the last interaction.

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_donor_interaction_distance() → float[source]#: Get the distance from chain start to middle interaction.

get_donor_acceptor_distance() → float[source]#: Get the distance from chain start to end.

get_donor_interaction_acceptor_angle() → float[source]#: Get the angle across the chain (donor-middle-acceptor).

is_donor_interaction_bonded() → bool[source]#

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

PDB Structure Handling#

PDB File Parser#

PDB file parser for molecular structure analysis using pdbreader.

This module provides functionality to parse PDB (Protein Data Bank) files and extract atomic coordinates and molecular information using the pdbreader library.

class hbat.core.pdb_parser.PDBParser[source]#

Bases: object

Parser for PDB format files using pdbreader.

This class handles parsing of PDB (Protein Data Bank) format files and converts them into HBAT’s internal atom and residue representations. Uses the pdbreader library for robust PDB format handling.

__init__() → None[source]#

Initialize PDB parser.

Creates a new parser instance with empty atom and residue lists.

parse_file(filename: str) → bool[source]#

Parse a PDB file.

Reads and parses a PDB format file, extracting all ATOM and HETATM records and converting them to HBAT’s internal representation.

Parameters:: filename (str) – Path to the PDB file to parse
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool
Raises:: IOError if file cannot be read

parse_lines(lines: List[str]) → bool[source]#

Parse PDB format lines.

Parses PDB format content provided as a list of strings, useful for processing in-memory PDB data.

Parameters:: lines (List[str]) – List of PDB format lines
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool

get_atoms_by_element(element: str) → List[Atom][source]#

Get all atoms of specific element.

Parameters:: element (str) – Element symbol (e.g., ‘C’, ‘N’, ‘O’)
Returns:: List of atoms matching the element
Return type:: List[Atom]

get_atoms_by_residue(res_name: str) → List[Atom][source]#

Get all atoms from residues with specific name.

Parameters:: res_name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
Returns:: List of atoms from matching residues
Return type:: List[Atom]

get_hydrogen_atoms() → List[Atom][source]#

Get all hydrogen atoms.

Returns:: List of all hydrogen and deuterium atoms
Return type:: List[Atom]

has_hydrogens() → bool[source]#

Check if structure contains hydrogen atoms.

Determines if the structure has a reasonable number of hydrogen atoms compared to heavy atoms, indicating explicit hydrogen modeling.

Returns:: True if structure appears to contain explicit hydrogens
Return type:: bool

get_residue_list() → List[Residue][source]#

Get list of all residues.

Returns:: List of all residues in the structure
Return type:: List[Residue]

get_chain_ids() → List[str][source]#

Get list of unique chain IDs.

Returns:: List of unique chain identifiers in the structure
Return type:: List[str]

get_statistics() → Dict[str, Any][source]#

Get basic statistics about the structure.

Provides counts of atoms, residues, chains, and element composition.

Returns:: Dictionary containing structure statistics
Return type:: Dict[str, Any]

get_bonds() → List[Bond][source]#

Get list of all bonds.

Returns:: List of all bonds in the structure
Return type:: List[Bond]

get_bonds_for_atom(serial: int) → List[Bond][source]#

Get all bonds involving a specific atom.

Parameters:: serial (int) – Atom serial number
Returns:: List of bonds involving this atom
Return type:: List[Bond]

get_bonded_atoms(serial: int) → List[int][source]#

Get serial numbers of atoms bonded to the specified atom.

Parameters:: serial (int) – Atom serial number
Returns:: List of bonded atom serial numbers
Return type:: List[int]

get_bond_detection_statistics() → Dict[str, int][source]#

Get statistics about bond detection methods used.

Returns a dictionary with counts of bonds detected by each method.

class hbat.core.pdb_parser.PDBParser[source]#

Bases: object

Parser for PDB format files using pdbreader.

High-performance PDB file parser using the pdbreader library.

Features:

Robust parsing with error handling
Automatic bond detection and validation
Structure statistics and validation
Element mapping with utility functions

Usage Example:

from hbat.core.pdb_parser import PDBParser

# Parse PDB file
parser = PDBParser()
atoms, residues, bonds = parser.parse_file("structure.pdb")

# Get structure statistics
stats = parser.get_statistics()
print(f"Parsed {len(atoms)} atoms in {len(residues)} residues")

__init__() → None[source]#

Initialize PDB parser.

Creates a new parser instance with empty atom and residue lists.

parse_file(filename: str) → bool[source]#

Parse a PDB file.

Reads and parses a PDB format file, extracting all ATOM and HETATM records and converting them to HBAT’s internal representation.

Parameters:: filename (str) – Path to the PDB file to parse
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool
Raises:: IOError if file cannot be read

parse_lines(lines: List[str]) → bool[source]#

Parse PDB format lines.

Parses PDB format content provided as a list of strings, useful for processing in-memory PDB data.

Parameters:: lines (List[str]) – List of PDB format lines
Returns:: True if parsing completed successfully, False otherwise
Return type:: bool

get_atoms_by_element(element: str) → List[Atom][source]#

Get all atoms of specific element.

Parameters:: element (str) – Element symbol (e.g., ‘C’, ‘N’, ‘O’)
Returns:: List of atoms matching the element
Return type:: List[Atom]

get_atoms_by_residue(res_name: str) → List[Atom][source]#

Get all atoms from residues with specific name.

Parameters:: res_name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
Returns:: List of atoms from matching residues
Return type:: List[Atom]

get_hydrogen_atoms() → List[Atom][source]#

Get all hydrogen atoms.

Returns:: List of all hydrogen and deuterium atoms
Return type:: List[Atom]

has_hydrogens() → bool[source]#

Check if structure contains hydrogen atoms.

Determines if the structure has a reasonable number of hydrogen atoms compared to heavy atoms, indicating explicit hydrogen modeling.

Returns:: True if structure appears to contain explicit hydrogens
Return type:: bool

get_residue_list() → List[Residue][source]#

Get list of all residues.

Returns:: List of all residues in the structure
Return type:: List[Residue]

get_chain_ids() → List[str][source]#

Get list of unique chain IDs.

Returns:: List of unique chain identifiers in the structure
Return type:: List[str]

get_statistics() → Dict[str, Any][source]#

Get basic statistics about the structure.

Provides counts of atoms, residues, chains, and element composition.

Returns:: Dictionary containing structure statistics
Return type:: Dict[str, Any]

get_bonds() → List[Bond][source]#

Get list of all bonds.

Returns:: List of all bonds in the structure
Return type:: List[Bond]

get_bonds_for_atom(serial: int) → List[Bond][source]#

Get all bonds involving a specific atom.

Parameters:: serial (int) – Atom serial number
Returns:: List of bonds involving this atom
Return type:: List[Bond]

get_bonded_atoms(serial: int) → List[int][source]#

Get serial numbers of atoms bonded to the specified atom.

Parameters:: serial (int) – Atom serial number
Returns:: List of bonded atom serial numbers
Return type:: List[int]

get_bond_detection_statistics() → Dict[str, int][source]#

Get statistics about bond detection methods used.

Returns a dictionary with counts of bonds detected by each method.

Molecular Data Structures#

class hbat.core.structure.Atom(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: NPVec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str, residue_type: str = 'L', backbone_sidechain: str = 'S', aromatic: str = 'N')[source]#

Bases: object

Represents an atom from a PDB file.

This class stores all atomic information parsed from PDB format including coordinates, properties, and residue information.

Parameters:

serial (int) – Atom serial number
name (str) – Atom name
alt_loc (str) – Alternate location indicator
res_name (str) – Residue name
chain_id (str) – Chain identifier
res_seq (int) – Residue sequence number
i_code (str) – Insertion code
coords (NPVec3D) – 3D coordinates
occupancy (float) – Occupancy factor
temp_factor (float) – Temperature factor
element (str) – Element symbol
charge (str) – Formal charge
record_type (str) – PDB record type (ATOM or HETATM)
residue_type (str) – Residue type classification (P=Protein, D=DNA, R=RNA, L=Ligand)
backbone_sidechain (str) – Backbone/sidechain classification (B=Backbone, S=Sidechain)
aromatic (str) – Aromatic classification (A=Aromatic, N=Non-aromatic)

Class representing an atom with comprehensive PDB information and calculated properties. Supports iteration, dictionary conversion, and field introspection.

__init__(serial: int, name: str, alt_loc: str, res_name: str, chain_id: str, res_seq: int, i_code: str, coords: NPVec3D, occupancy: float, temp_factor: float, element: str, charge: str, record_type: str, residue_type: str = 'L', backbone_sidechain: str = 'S', aromatic: str = 'N') → None[source]#

Initialize an Atom object.

Parameters:

serial (int) – Atom serial number
name (str) – Atom name
alt_loc (str) – Alternate location indicator
res_name (str) – Residue name
chain_id (str) – Chain identifier
res_seq (int) – Residue sequence number
i_code (str) – Insertion code
coords (NPVec3D) – 3D coordinates
occupancy (float) – Occupancy factor
temp_factor (float) – Temperature factor
element (str) – Element symbol
charge (str) – Formal charge
record_type (str) – PDB record type (ATOM or HETATM)
residue_type (str) – Residue type classification (P=Protein, D=DNA, R=RNA, L=Ligand)
backbone_sidechain (str) – Backbone/sidechain classification (B=Backbone, S=Sidechain)
aromatic (str) – Aromatic classification (A=Aromatic, N=Non-aromatic)

is_hydrogen() → bool[source]#

Check if atom is hydrogen.

Returns:: True if atom is hydrogen or deuterium
Return type:: bool

is_metal() → bool[source]#

Check if atom is a metal.

Returns:: True if atom is a common metal ion
Return type:: bool

__iter__() → Iterator[Tuple[str, Any]][source]#

Iterate over atom attributes as (name, value) pairs.

Returns:: Iterator of (attribute_name, value) tuples
Return type:: Iterator[Tuple[str, Any]]

to_dict() → Dict[str, Any][source]#

Convert atom to dictionary.

Returns:: Dictionary representation of the atom
Return type:: Dict[str, Any]

classmethod fields() → List[str][source]#

Get list of field names.

Returns:: List of field names
Return type:: List[str]

__repr__() → str[source]#: String representation of the atom.

__eq__(other: object) → bool[source]#: Check equality with another Atom.

class hbat.core.structure.Residue(name: str, chain_id: str, seq_num: int, i_code: str, atoms: List[Atom])[source]#

Bases: object

Represents a residue containing multiple atoms.

This class groups atoms belonging to the same residue and provides methods for accessing and analyzing residue-level information.

Parameters:

name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
chain_id (str) – Chain identifier
seq_num (int) – Residue sequence number
i_code (str) – Insertion code
atoms (List[Atom]) – List of atoms in this residue

Class representing a residue with atom collections and residue-level properties. Includes aromatic center calculation and atom management.

__init__(name: str, chain_id: str, seq_num: int, i_code: str, atoms: List[Atom]) → None[source]#

Initialize a Residue object.

Parameters:

name (str) – Residue name (e.g., ‘ALA’, ‘GLY’)
chain_id (str) – Chain identifier
seq_num (int) – Residue sequence number
i_code (str) – Insertion code
atoms (List[Atom]) – List of atoms in this residue

get_atom(atom_name: str) → Atom | None[source]#

Get specific atom by name.

Parameters:: atom_name (str) – Name of the atom to find
Returns:: The atom if found, None otherwise
Return type:: Optional[Atom]

get_atoms_by_element(element: str) → List[Atom][source]#

Get all atoms of specific element.

Parameters:: element (str) – Element symbol (e.g., ‘C’, ‘N’, ‘O’)
Returns:: List of atoms matching the element
Return type:: List[Atom]

center_of_mass() → NPVec3D[source]#

Calculate center of mass of residue.

Computes the mass-weighted centroid of all atoms in the residue.

Returns:: Center of mass coordinates
Return type:: NPVec3D

get_aromatic_center() → NPVec3D | None[source]#

Calculate aromatic ring center if residue is aromatic.

For aromatic residues (PHE, TYR, TRP, HIS), calculates the geometric center of the aromatic ring atoms.

Returns:: Center coordinates of aromatic ring, None if not aromatic
Return type:: Optional[NPVec3D]

__iter__() → Iterator[Tuple[str, Any]][source]#

Iterate over residue attributes as (name, value) pairs.

Returns:: Iterator of (attribute_name, value) tuples
Return type:: Iterator[Tuple[str, Any]]

to_dict() → Dict[str, Any][source]#

Convert residue to dictionary.

Returns:: Dictionary representation of the residue
Return type:: Dict[str, Any]

classmethod fields() → List[str][source]#

Get list of field names.

Returns:: List of field names
Return type:: List[str]

__repr__() → str[source]#: String representation of the residue.

__eq__(other: object) → bool[source]#: Check equality with another Residue.

class hbat.core.structure.Bond(atom1_serial: int, atom2_serial: int, bond_type: str = 'covalent', distance: float | None = None, detection_method: str = 'distance_based')[source]#

Bases: object

Represents a chemical bond between two atoms.

This class stores information about atomic bonds, including the atoms involved and bond type/origin.

Parameters:

atom1_serial (int) – Serial number of first atom
atom2_serial (int) – Serial number of second atom
bond_type (str) – Type of bond (‘covalent’, ‘explicit’, etc.)
distance (Optional[float]) – Distance between bonded atoms in Angstroms
detection_method (str) – Method used to detect this bond

Class representing a chemical bond between two atoms with bond properties. Provides methods for bond analysis and atom involvement checking.

__init__(atom1_serial: int, atom2_serial: int, bond_type: str = 'covalent', distance: float | None = None, detection_method: str = 'distance_based') → None[source]#

Initialize a Bond object.

Parameters:

atom1_serial (int) – Serial number of first atom
atom2_serial (int) – Serial number of second atom
bond_type (str) – Type of bond (‘covalent’, ‘explicit’, etc.)
distance (Optional[float]) – Distance between bonded atoms in Angstroms
detection_method (str) – Method used to detect this bond

involves_atom(serial: int) → bool[source]#

Check if bond involves the specified atom.

Parameters:: serial (int) – Atom serial number
Returns:: True if bond involves this atom
Return type:: bool

get_partner(serial: int) → int | None[source]#

Get the bonding partner of the specified atom.

Parameters:: serial (int) – Atom serial number
Returns:: Serial number of bonding partner, None if atom not in bond
Return type:: Optional[int]

__iter__() → Iterator[Tuple[str, Any]][source]#

Iterate over bond attributes as (name, value) pairs.

Returns:: Iterator of (attribute_name, value) tuples
Return type:: Iterator[Tuple[str, Any]]

to_dict() → Dict[str, Any][source]#

Convert bond to dictionary.

Returns:: Dictionary representation of the bond
Return type:: Dict[str, Any]

classmethod fields() → List[str][source]#

Get list of field names.

Returns:: List of field names
Return type:: List[str]

__repr__() → str[source]#: String representation of the bond.

__eq__(other: object) → bool[source]#: Check equality with another Bond.

PDB Structure Enhancement#

PDB Structure Fixer#

PDB structure fixing module for adding missing hydrogen atoms.

This module provides functionality to add missing hydrogen atoms to PDB structures using either OpenBabel or PDBFixer tools. It integrates with HBAT’s internal data structures and provides a clean interface for structure enhancement.

exception hbat.core.pdb_fixer.PDBFixerError[source]#

Bases: Exception

Exception raised when PDB fixing operations fail.

class hbat.core.pdb_fixer.PDBFixer[source]#

Bases: object

Fix PDB structures by adding missing hydrogen atoms.

This class provides methods to add missing hydrogen atoms to protein structures using either OpenBabel or PDBFixer with OpenMM. It works with HBAT’s internal atom and residue data structures.

__init__() → None[source]#: Initialize PDB fixer.

add_missing_hydrogens(atoms: List[Atom], method: str = 'openbabel', pH: float = 7.0, **kwargs: Any) → List[Atom][source]#

Add missing hydrogen atoms to a list of atoms.

Takes a list of HBAT Atom objects and returns a new list with missing hydrogen atoms added using the specified method.

Parameters:

atoms (List[Atom]) – List of atoms to process
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
pH (float) – pH value for protonation (pdbfixer only)
kwargs (Any) – Additional parameters for the fixing method

Returns:

List of atoms with hydrogens added

Return type:

List[Atom]

Raises:

PDBFixerError if fixing fails

add_missing_heavy_atoms(atoms: List[Atom], method: str = 'pdbfixer', **kwargs: Any) → List[Atom][source]#

Add missing heavy atoms to a structure.

Uses PDBFixer to identify and add missing heavy atoms in residues. This is particularly useful for structures with incomplete side chains.

Parameters:

atoms (List[Atom]) – List of atoms to process
method (str) – Method to use (only ‘pdbfixer’ supports this)
kwargs (Any) – Additional parameters

Returns:

List of atoms with missing heavy atoms added

Return type:

List[Atom]

Raises:

PDBFixerError if fixing fails

convert_nonstandard_residues(atoms: List[Atom], custom_replacements: Dict[str, str] | None = None) → List[Atom][source]#

Convert non-standard residues to their standard equivalents using PDBFixer.

This method uses PDBFixer’s built-in findNonstandardResidues() and replaceNonstandardResidues() methods to properly handle non-standard residues.

Parameters:

atoms (List[Atom]) – List of atoms to process
custom_replacements (Optional[Dict[str, str]]) – Custom residue replacements to apply

Returns:

List of atoms with converted residue names

Return type:

List[Atom]

remove_heterogens(atoms: List[Atom], keep_water: bool = True) → List[Atom][source]#

Remove unwanted heterogens from the structure using PDBFixer.

Uses PDBFixer’s built-in removeHeterogens() method to properly handle heterogen removal with the option to keep water molecules.

Parameters:

atoms (List[Atom]) – List of atoms to process
keep_water (bool) – Whether to keep water molecules

Returns:

List of atoms with heterogens removed

Return type:

List[Atom]

fix_structure_file(input_path: str, output_path: str | None = None, method: str = 'openbabel', pH: float = 7.0, overwrite: bool = False, **kwargs: Any) → str[source]#

Fix a PDB file by adding missing hydrogen atoms.

Parameters:

input_path (str) – Path to input PDB file
output_path (Optional[str]) – Path for output file (optional)
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
pH (float) – pH value for protonation (pdbfixer only)
overwrite (bool) – Whether to overwrite existing output file
kwargs (Any) – Additional parameters for the fixing method

Returns:

Path to the output file

Return type:

str

Raises:

PDBFixerError if fixing fails

fix_pdb_file_to_file(input_pdb_path: str, output_pdb_path: str, method: str = 'openbabel', add_hydrogens: bool = True, add_heavy_atoms: bool = False, convert_nonstandard: bool = False, remove_heterogens: bool = False, keep_water: bool = True, pH: float = 7.0, **kwargs: Any) → bool[source]#

Fix a PDB file and save the result to another file.

This method processes the original PDB file directly and saves the fixed structure to a new file, preserving proper PDB formatting.

Parameters:

input_pdb_path (str) – Path to the original PDB file
output_pdb_path (str) – Path where the fixed PDB should be saved
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
add_hydrogens (bool) – Whether to add missing hydrogen atoms
add_heavy_atoms (bool) – Whether to add missing heavy atoms (pdbfixer only)
convert_nonstandard (bool) – Whether to convert nonstandard residues (pdbfixer only)
remove_heterogens (bool) – Whether to remove heterogens (pdbfixer only)
keep_water (bool) – Whether to keep water molecules when removing heterogens
pH (float) – pH value for protonation (pdbfixer only)
kwargs (Any) – Additional parameters

Returns:

True if fixing succeeded, False otherwise

Return type:

bool

Raises:

PDBFixerError if fixing fails

get_missing_hydrogen_info(atoms: List[Atom]) → Dict[str, Any][source]#

Analyze structure for missing hydrogen information.

Parameters:: atoms (List[Atom]) – List of atoms to analyze
Returns:: Dictionary with hydrogen analysis information
Return type:: Dict[str, Any]

hbat.core.pdb_fixer.add_missing_hydrogens(atoms: List[Atom], method: str = 'openbabel', pH: float = 7.0, **kwargs: Any) → List[Atom][source]#

Convenience function to add missing hydrogen atoms.

Parameters:

atoms (List[Atom]) – List of atoms to process
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
pH (float) – pH value for protonation (pdbfixer only)
kwargs (Any) – Additional parameters for the fixing method

Returns:

List of atoms with hydrogens added

Return type:

List[Atom]

hbat.core.pdb_fixer.fix_pdb_file(input_path: str, output_path: str | None = None, method: str = 'openbabel', pH: float = 7.0, overwrite: bool = False, **kwargs: Any) → str[source]#

Convenience function to fix a PDB file.

Parameters:

input_path (str) – Path to input PDB file
output_path (Optional[str]) – Path for output file (optional)
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
pH (float) – pH value for protonation (pdbfixer only)
overwrite (bool) – Whether to overwrite existing output file
kwargs (Any) – Additional parameters for the fixing method

Returns:

Path to the output file

Return type:

str

hbat.core.pdb_fixer.add_missing_heavy_atoms(atoms: List[Atom], method: str = 'pdbfixer', **kwargs: Any) → List[Atom][source]#

Convenience function to add missing heavy atoms.

Parameters:

atoms (List[Atom]) – List of atoms to process
method (str) – Method to use (only ‘pdbfixer’ supports this)
kwargs (Any) – Additional parameters

Returns:

List of atoms with missing heavy atoms added

Return type:

List[Atom]

hbat.core.pdb_fixer.convert_nonstandard_residues(atoms: List[Atom], custom_replacements: Dict[str, str] | None = None) → List[Atom][source]#

Convenience function to convert non-standard residues using PDBFixer.

Uses PDBFixer’s built-in findNonstandardResidues() and replaceNonstandardResidues() methods to properly handle non-standard residue conversion.

Parameters:

atoms (List[Atom]) – List of atoms to process
custom_replacements (Optional[Dict[str, str]]) – Custom residue replacements to apply

Returns:

List of atoms with converted residue names

Return type:

List[Atom]

hbat.core.pdb_fixer.remove_heterogens(atoms: List[Atom], keep_water: bool = True) → List[Atom][source]#

Convenience function to remove unwanted heterogens using PDBFixer.

Uses PDBFixer’s built-in removeHeterogens() method which only supports the option to keep or remove water molecules.

Parameters:

atoms (List[Atom]) – List of atoms to process
keep_water (bool) – Whether to keep water molecules

Returns:

List of atoms with heterogens removed

Return type:

List[Atom]

class hbat.core.pdb_fixer.PDBFixer[source]#

Bases: object

Fix PDB structures by adding missing hydrogen atoms.

This class provides methods to add missing hydrogen atoms to protein structures using either OpenBabel or PDBFixer with OpenMM. It works with HBAT’s internal atom and residue data structures.

Comprehensive PDB structure enhancement and fixing utility.

Fixing Capabilities:

Missing hydrogen atom addition (OpenBabel/PDBFixer)
Missing heavy atom reconstruction (PDBFixer only)
Non-standard residue conversion (PDBFixer only)
Hetrogen removal and filtering (PDBFixer only)
Direct file-to-file processing for preserved formatting

Usage Example:

from hbat.core.pdb_fixer import PDBFixer

# Initialize fixer
fixer = PDBFixer()

# Fix structure directly from file to file
success = fixer.fix_pdb_file_to_file(
    input_pdb_path="input.pdb",
    output_pdb_path="input_fixed.pdb",
    method="openbabel",
    add_hydrogens=True
)

# Or use atom-based processing
fixed_atoms = fixer.add_missing_hydrogens(atoms, method="pdbfixer")

__init__() → None[source]#: Initialize PDB fixer.

add_missing_hydrogens(atoms: List[Atom], method: str = 'openbabel', pH: float = 7.0, **kwargs: Any) → List[Atom][source]#

Add missing hydrogen atoms to a list of atoms.

Takes a list of HBAT Atom objects and returns a new list with missing hydrogen atoms added using the specified method.

Parameters:

atoms (List[Atom]) – List of atoms to process
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
pH (float) – pH value for protonation (pdbfixer only)
kwargs (Any) – Additional parameters for the fixing method

Returns:

List of atoms with hydrogens added

Return type:

List[Atom]

Raises:

PDBFixerError if fixing fails

add_missing_heavy_atoms(atoms: List[Atom], method: str = 'pdbfixer', **kwargs: Any) → List[Atom][source]#

Add missing heavy atoms to a structure.

Uses PDBFixer to identify and add missing heavy atoms in residues. This is particularly useful for structures with incomplete side chains.

Parameters:

atoms (List[Atom]) – List of atoms to process
method (str) – Method to use (only ‘pdbfixer’ supports this)
kwargs (Any) – Additional parameters

Returns:

List of atoms with missing heavy atoms added

Return type:

List[Atom]

Raises:

PDBFixerError if fixing fails

convert_nonstandard_residues(atoms: List[Atom], custom_replacements: Dict[str, str] | None = None) → List[Atom][source]#

Convert non-standard residues to their standard equivalents using PDBFixer.

This method uses PDBFixer’s built-in findNonstandardResidues() and replaceNonstandardResidues() methods to properly handle non-standard residues.

Parameters:

atoms (List[Atom]) – List of atoms to process
custom_replacements (Optional[Dict[str, str]]) – Custom residue replacements to apply

Returns:

List of atoms with converted residue names

Return type:

List[Atom]

remove_heterogens(atoms: List[Atom], keep_water: bool = True) → List[Atom][source]#

Remove unwanted heterogens from the structure using PDBFixer.

Uses PDBFixer’s built-in removeHeterogens() method to properly handle heterogen removal with the option to keep water molecules.

Parameters:

atoms (List[Atom]) – List of atoms to process
keep_water (bool) – Whether to keep water molecules

Returns:

List of atoms with heterogens removed

Return type:

List[Atom]

fix_structure_file(input_path: str, output_path: str | None = None, method: str = 'openbabel', pH: float = 7.0, overwrite: bool = False, **kwargs: Any) → str[source]#

Fix a PDB file by adding missing hydrogen atoms.

Parameters:

input_path (str) – Path to input PDB file
output_path (Optional[str]) – Path for output file (optional)
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
pH (float) – pH value for protonation (pdbfixer only)
overwrite (bool) – Whether to overwrite existing output file
kwargs (Any) – Additional parameters for the fixing method

Returns:

Path to the output file

Return type:

str

Raises:

PDBFixerError if fixing fails

Fix a PDB file and save the result to another file.

This method processes the original PDB file directly and saves the fixed structure to a new file, preserving proper PDB formatting.

Parameters:

input_pdb_path (str) – Path to the original PDB file
output_pdb_path (str) – Path where the fixed PDB should be saved
method (str) – Method to use (‘openbabel’ or ‘pdbfixer’)
add_hydrogens (bool) – Whether to add missing hydrogen atoms
add_heavy_atoms (bool) – Whether to add missing heavy atoms (pdbfixer only)
convert_nonstandard (bool) – Whether to convert nonstandard residues (pdbfixer only)
remove_heterogens (bool) – Whether to remove heterogens (pdbfixer only)
keep_water (bool) – Whether to keep water molecules when removing heterogens
pH (float) – pH value for protonation (pdbfixer only)
kwargs (Any) – Additional parameters

Returns:

True if fixing succeeded, False otherwise

Return type:

bool

Raises:

PDBFixerError if fixing fails

get_missing_hydrogen_info(atoms: List[Atom]) → Dict[str, Any][source]#

Analyze structure for missing hydrogen information.

Parameters:: atoms (List[Atom]) – List of atoms to analyze
Returns:: Dictionary with hydrogen analysis information
Return type:: Dict[str, Any]

class hbat.core.pdb_fixer.PDBFixerError[source]#

Bases: Exception

Exception raised when PDB fixing operations fail.

Exception class for PDB fixing operations with detailed error reporting.

3D Vector Mathematics#

NumPy Vector Operations#

NumPy-based 3D vector mathematics for molecular analysis.

This module provides efficient vector operations for high-performance molecular geometry calculations, supporting both single vectors and batch operations on multiple vectors simultaneously.

Bases: object

NumPy-based 3D vector class for molecular calculations.

This class provides comprehensive 3D vector operations using NumPy, enabling efficient batch processing of multiple vectors simultaneously.

Parameters:

coords (Union[float, np.ndarray]) – Either x,y,z coordinates or numpy array of shape (3,) or (N,3)
y (Optional[float]) – Y coordinate (only if coords is a float)
z (Optional[float]) – Z coordinate (only if coords is a float)

__init__(coords: float | ndarray | List[float] | Tuple[float, float, float] = 0.0, y: float | None = None, z: float | None = None)[source]#: Initialize a 3D vector or batch of vectors.

property x: float | ndarray#: X coordinate(s).

property y: float | ndarray#: Y coordinate(s).

property z: float | ndarray#: Z coordinate(s).

property shape: Tuple[int, ...]#: Shape of the underlying array.

property is_batch: bool#: Whether this represents multiple vectors.

__add__(other: NPVec3D | ndarray) → NPVec3D[source]#: Vector addition.

__sub__(other: NPVec3D | ndarray) → NPVec3D[source]#: Vector subtraction.

__mul__(scalar: float | ndarray) → NPVec3D[source]#: Scalar multiplication.

__rmul__(scalar: float | ndarray) → NPVec3D[source]#: Reverse scalar multiplication.

__truediv__(scalar: float | ndarray) → NPVec3D[source]#: Scalar division.

__eq__(other: object) → bool[source]#: Vector equality comparison.

__getitem__(index: int | slice | ndarray) → float | NPVec3D[source]#: Get component or subset.

dot(other: NPVec3D) → float | ndarray[source]#

Dot product with another vector.

Parameters:: other (NPVec3D) – The other vector(s)
Returns:: Dot product result(s)
Return type:: Union[float, np.ndarray]

cross(other: NPVec3D) → NPVec3D[source]#

Cross product with another vector.

Parameters:: other (NPVec3D) – The other vector(s)
Returns:: Cross product vector(s)
Return type:: NPVec3D

length() → float | ndarray[source]#

Calculate vector length/magnitude.

Returns:: Euclidean length of the vector(s)
Return type:: Union[float, np.ndarray]

magnitude() → float | ndarray[source]#: Alias for length().

normalize() → NPVec3D[source]#

Return normalized unit vector(s).

Returns:: Unit vector(s) in the same direction
Return type:: NPVec3D

unit_vector() → NPVec3D[source]#: Alias for normalize().

distance_to(other: NPVec3D) → float | ndarray[source]#

Calculate distance to another vector.

Parameters:: other (NPVec3D) – The target vector(s)
Returns:: Euclidean distance(s) between vectors
Return type:: Union[float, np.ndarray]

angle_to(other: NPVec3D) → float | ndarray[source]#

Calculate angle to another vector in radians.

Parameters:: other (NPVec3D) – The target vector(s)
Returns:: Angle(s) between vectors in radians
Return type:: Union[float, np.ndarray]

to_array() → ndarray[source]#

Convert to numpy array.

Returns:: Numpy array of coordinates
Return type:: np.ndarray

to_list() → List[float][source]#

Convert to list [x, y, z] (single vector only).

Returns:: Vector components as a list
Return type:: List[float]

to_tuple() → Tuple[float, float, float][source]#

Convert to tuple (x, y, z) (single vector only).

Returns:: Vector components as a tuple
Return type:: Tuple[float, float, float]

classmethod from_list(coords: List[float]) → NPVec3D[source]#

Create vector from list [x, y, z].

Parameters:: coords (List[float]) – List of coordinates
Returns:: New NPVec3D instance
Return type:: NPVec3D

classmethod from_tuple(coords: Tuple[float, ...]) → NPVec3D[source]#

Create vector from tuple (x, y, z).

Parameters:: coords (Tuple[float, ...]) – Tuple of coordinates
Returns:: New NPVec3D instance
Return type:: NPVec3D

classmethod from_atoms(atoms: List) → NPVec3D[source]#

Create batch vector from list of atoms.

Parameters:: atoms (List) – List of atoms with x, y, z attributes
Returns:: Batch NPVec3D instance
Return type:: NPVec3D

hbat.core.np_vector.compute_distance_matrix(coords1: ndarray, coords2: ndarray | None = None) → ndarray[source]#

Compute pairwise distance matrix between two sets of coordinates.

Parameters:

coords1 (np.ndarray) – First set of coordinates, shape (N, 3)
coords2 (Optional[np.ndarray]) – Second set of coordinates, shape (M, 3). If None, computes self-distances

Returns:

Distance matrix of shape (N, M) or (N, N)

Return type:

np.ndarray

hbat.core.np_vector.batch_angle_between(a: NPVec3D, b: NPVec3D, c: NPVec3D | None = None) → float | ndarray[source]#

Calculate angles between vectors (optimized for batches).

If c is provided: Calculate angle ABC where B is the vertex. If c is None: Calculate angle between vectors a and b.

Parameters:

a (NPVec3D) – First vector(s) or point(s) A
b (NPVec3D) – Second vector(s) or vertex point(s) B
c (Optional[NPVec3D]) – Optional third point(s) C for angle ABC

Returns:

Angle(s) in radians

Return type:

Union[float, np.ndarray]

hbat.core.np_vector.batch_dihedral_angle(a: NPVec3D, b: NPVec3D, c: NPVec3D, d: NPVec3D) → float | ndarray[source]#

Calculate dihedral angles between planes ABC and BCD (optimized for batches).

Parameters:

a (NPVec3D) – First point(s) defining plane ABC
b (NPVec3D) – Second point(s) defining both planes
c (NPVec3D) – Third point(s) defining both planes
d (NPVec3D) – Fourth point(s) defining plane BCD

Returns:

Dihedral angle(s) in radians

Return type:

Union[float, np.ndarray]

Bases: object

NumPy-based 3D vector class for molecular calculations.

This class provides comprehensive 3D vector operations using NumPy, enabling efficient batch processing of multiple vectors simultaneously.

Parameters:

coords (Union[float, np.ndarray]) – Either x,y,z coordinates or numpy array of shape (3,) or (N,3)
y (Optional[float]) – Y coordinate (only if coords is a float)
z (Optional[float]) – Z coordinate (only if coords is a float)

High-performance 3D vector class using NumPy for molecular geometry calculations.

Mathematical Operations:

Standard arithmetic: addition, subtraction, multiplication, division
Vector operations: dot product, cross product, normalization
Geometric calculations: distances, angles, projections
NumPy array compatibility and vectorized operations

Usage Example:

from hbat.core.np_vector import NPVec3D

# Create vectors
v1 = NPVec3D(1.0, 0.0, 0.0)
v2 = NPVec3D(0.0, 1.0, 0.0)

# Vector operations
cross_product = v1.cross(v2)  # Returns NPVec3D(0.0, 0.0, 1.0)
angle = v1.angle_to(v2)       # Returns π/2 radians
distance = v1.distance_to(v2) # Returns √2

__init__(coords: float | ndarray | List[float] | Tuple[float, float, float] = 0.0, y: float | None = None, z: float | None = None)[source]#: Initialize a 3D vector or batch of vectors.

property x: float | ndarray#: X coordinate(s).

property y: float | ndarray#: Y coordinate(s).

property z: float | ndarray#: Z coordinate(s).

property shape: Tuple[int, ...]#: Shape of the underlying array.

property is_batch: bool#: Whether this represents multiple vectors.

__add__(other: NPVec3D | ndarray) → NPVec3D[source]#: Vector addition.

__sub__(other: NPVec3D | ndarray) → NPVec3D[source]#: Vector subtraction.

__mul__(scalar: float | ndarray) → NPVec3D[source]#: Scalar multiplication.

__rmul__(scalar: float | ndarray) → NPVec3D[source]#: Reverse scalar multiplication.

__truediv__(scalar: float | ndarray) → NPVec3D[source]#: Scalar division.

__eq__(other: object) → bool[source]#: Vector equality comparison.

__getitem__(index: int | slice | ndarray) → float | NPVec3D[source]#: Get component or subset.

dot(other: NPVec3D) → float | ndarray[source]#

Dot product with another vector.

Parameters:: other (NPVec3D) – The other vector(s)
Returns:: Dot product result(s)
Return type:: Union[float, np.ndarray]

cross(other: NPVec3D) → NPVec3D[source]#

Cross product with another vector.

Parameters:: other (NPVec3D) – The other vector(s)
Returns:: Cross product vector(s)
Return type:: NPVec3D

length() → float | ndarray[source]#

Calculate vector length/magnitude.

Returns:: Euclidean length of the vector(s)
Return type:: Union[float, np.ndarray]

magnitude() → float | ndarray[source]#: Alias for length().

normalize() → NPVec3D[source]#

Return normalized unit vector(s).

Returns:: Unit vector(s) in the same direction
Return type:: NPVec3D

unit_vector() → NPVec3D[source]#: Alias for normalize().

distance_to(other: NPVec3D) → float | ndarray[source]#

Calculate distance to another vector.

Parameters:: other (NPVec3D) – The target vector(s)
Returns:: Euclidean distance(s) between vectors
Return type:: Union[float, np.ndarray]

angle_to(other: NPVec3D) → float | ndarray[source]#

Calculate angle to another vector in radians.

Parameters:: other (NPVec3D) – The target vector(s)
Returns:: Angle(s) between vectors in radians
Return type:: Union[float, np.ndarray]

to_array() → ndarray[source]#

Convert to numpy array.

Returns:: Numpy array of coordinates
Return type:: np.ndarray

to_list() → List[float][source]#

Convert to list [x, y, z] (single vector only).

Returns:: Vector components as a list
Return type:: List[float]

to_tuple() → Tuple[float, float, float][source]#

Convert to tuple (x, y, z) (single vector only).

Returns:: Vector components as a tuple
Return type:: Tuple[float, float, float]

classmethod from_list(coords: List[float]) → NPVec3D[source]#

Create vector from list [x, y, z].

Parameters:: coords (List[float]) – List of coordinates
Returns:: New NPVec3D instance
Return type:: NPVec3D

classmethod from_tuple(coords: Tuple[float, ...]) → NPVec3D[source]#

Create vector from tuple (x, y, z).

Parameters:: coords (Tuple[float, ...]) – Tuple of coordinates
Returns:: New NPVec3D instance
Return type:: NPVec3D

classmethod from_atoms(atoms: List) → NPVec3D[source]#

Create batch vector from list of atoms.

Parameters:: atoms (List) – List of atoms with x, y, z attributes
Returns:: Batch NPVec3D instance
Return type:: NPVec3D

Utility Functions#

hbat.core.np_vector.compute_distance_matrix(coords1: ndarray, coords2: ndarray | None = None) → ndarray[source]#

Compute pairwise distance matrix between two sets of coordinates.

Parameters:

coords1 (np.ndarray) – First set of coordinates, shape (N, 3)
coords2 (Optional[np.ndarray]) – Second set of coordinates, shape (M, 3). If None, computes self-distances

Returns:

Distance matrix of shape (N, M) or (N, N)

Return type:

np.ndarray

Compute distance matrix between two sets of coordinates using vectorized operations.

hbat.core.np_vector.batch_angle_between(a: NPVec3D, b: NPVec3D, c: NPVec3D | None = None) → float | ndarray[source]#

Calculate angles between vectors (optimized for batches).

If c is provided: Calculate angle ABC where B is the vertex. If c is None: Calculate angle between vectors a and b.

Parameters:

a (NPVec3D) – First vector(s) or point(s) A
b (NPVec3D) – Second vector(s) or vertex point(s) B
c (Optional[NPVec3D]) – Optional third point(s) C for angle ABC

Returns:

Angle(s) in radians

Return type:

Union[float, np.ndarray]

Calculate angle between three points with vectorized NumPy operations.

Legacy Compatibility#

Analysis Module (Backward Compatibility)#

Core analysis engine for hydrogen bond and molecular interaction analysis.

This module implements the main computational logic for detecting and analyzing molecular interactions including hydrogen bonds, halogen bonds, and X-H…π interactions.

For better maintainability, this module has been split into several focused modules: - interactions.py: Interaction data classes - parameters.py: Analysis parameters - analyzer.py: Main analysis engine

This file maintains backward compatibility by re-exporting all classes.

This module provides backward compatibility by re-exporting classes from the refactored modules.

Re-exported Classes:

NPMolecularInteractionAnalyzer from np_analyzer.py
AnalysisParameters from constants.parameters
All interaction classes from interactions.py

Migration Note:

For new code, import directly from the specific modules:

# Recommended for new code
from hbat.core.np_analyzer import NPMolecularInteractionAnalyzer
from hbat.core.interactions import HydrogenBond

# Still works (backward compatibility)
from hbat.core.analysis import NPMolecularInteractionAnalyzer, HydrogenBond

hbat.core.analysis.MolecularInteractionAnalyzer#: alias of NPMolecularInteractionAnalyzer

class hbat.core.analysis.NPMolecularInteractionAnalyzer(parameters: AnalysisParameters | None = None)[source]#

Bases: object

High-performance analyzer for molecular interactions.

This analyzer uses vectorized NumPy operations for efficient analysis of molecular interactions in protein structures. Supports comprehensive detection of:

Hydrogen bonds: Classical N-H···O, O-H···O, N-H···N interactions
Weak hydrogen bonds: C-H···O interactions (important in protein-ligand binding)
Halogen bonds: C-X···A interactions where X is Cl, Br, I (default angle: 150°)
π interactions: Multiple subtypes including:
- Hydrogen-π: C-H···π, N-H···π, O-H···π, S-H···π
- Halogen-π: C-Cl···π, C-Br···π, C-I···π
Cooperativity chains: Networks of linked interactions

Parameters:: parameters (Optional[AnalysisParameters]) – Analysis parameters with subtype-specific cutoffs

__init__(parameters: AnalysisParameters | None = None)[source]#: Initialize analyzer with parameters.

analyze_file(pdb_file: str) → bool[source]#

Analyze a PDB file for molecular interactions.

Parameters:: pdb_file (str) – Path to PDB file to analyze
Returns:: True if analysis completed successfully, False if parsing failed
Return type:: bool
Raises:: Exception – If PDB fixing fails when enabled

get_summary() → Dict[str, Any][source]#

Get comprehensive analysis summary with statistics, PDB fixing info, and timing.

Returns a dictionary containing interaction counts, averages, bond type distributions, PDB fixing information (if applied), and analysis timing.

Returns:: Dictionary containing comprehensive analysis summary
Return type:: Dict[str, Any]

hbat.core.analysis.HBondAnalyzer#: alias of NPMolecularInteractionAnalyzer

class hbat.core.analysis.AnalysisParameters(hb_distance_cutoff: float = 2.5, hb_angle_cutoff: float = 120.0, hb_donor_acceptor_cutoff: float = 3.5, whb_distance_cutoff: float = 3.6, whb_angle_cutoff: float = 150.0, whb_donor_acceptor_cutoff: float = 3.5, xb_distance_cutoff: float = 3.9, xb_angle_cutoff: float = 150.0, pi_distance_cutoff: float = 3.5, pi_angle_cutoff: float = 110.0, pi_ccl_distance_cutoff: float = 3.5, pi_ccl_angle_cutoff: float = 145, pi_cbr_distance_cutoff: float = 3.5, pi_cbr_angle_cutoff: float = 155, pi_ci_distance_cutoff: float = 3.6, pi_ci_angle_cutoff: float = 165.0, pi_ch_distance_cutoff: float = 3.5, pi_ch_angle_cutoff: float = 110.0, pi_nh_distance_cutoff: float = 3.2, pi_nh_angle_cutoff: float = 115.0, pi_oh_distance_cutoff: float = 3.0, pi_oh_angle_cutoff: float = 115.0, pi_sh_distance_cutoff: float = 3.8, pi_sh_angle_cutoff: float = 105.0, covalent_cutoff_factor: float = 0.85, analysis_mode: str = 'complete', fix_pdb_enabled: bool = True, fix_pdb_method: str = 'pdbfixer', fix_pdb_add_hydrogens: bool = True, fix_pdb_add_heavy_atoms: bool = False, fix_pdb_replace_nonstandard: bool = False, fix_pdb_remove_heterogens: bool = False, fix_pdb_keep_water: bool = True, **kwargs)[source]#

Bases: object

Parameters for comprehensive molecular interaction analysis.

This class contains all configurable parameters for detecting and analyzing molecular interactions in protein structures. Supports multiple interaction types with subtype-specific parameters.

Hydrogen Bonds (Classical): - Strong N-H···O, O-H···O, N-H···N interactions - Default: 2.5Å H···A distance, 120° D-H···A angle

Weak Hydrogen Bonds (C-H···O): - Carbon-hydrogen donor interactions with oxygen acceptors - Default: 3.6Å H···A distance, 150° D-H···A angle - Important in protein-ligand binding and aromatic interactions

Halogen Bonds: - C-X···A interactions where X is Cl, Br, I - Default: 3.9Å X···A distance, 150° C-X···A angle (updated default)

π Interactions (Multiple Subtypes): - Hydrogen-π: C-H···π, N-H···π, O-H···π, S-H···π - Halogen-π: C-Cl···π, C-Br···π, C-I···π - Each subtype has optimized distance/angle cutoffs

Parameters:

hb_distance_cutoff (float) – Maximum H…A distance for hydrogen bonds (Å)
hb_angle_cutoff (float) – Minimum D-H…A angle for hydrogen bonds (degrees)
hb_donor_acceptor_cutoff (float) – Maximum D…A distance for hydrogen bonds (Å)
whb_distance_cutoff (float) – Maximum H…A distance for weak hydrogen bonds (Å)
whb_angle_cutoff (float) – Minimum D-H…A angle for weak hydrogen bonds (degrees)
whb_donor_acceptor_cutoff (float) – Maximum D…A distance for weak hydrogen bonds (Å)
xb_distance_cutoff (float) – Maximum X…A distance for halogen bonds (Å)
xb_angle_cutoff (float) – Minimum C-X…A angle for halogen bonds (degrees, default: 150°)
pi_distance_cutoff (float) – Maximum H…π distance for π interactions (Å, legacy)
pi_angle_cutoff (float) – Minimum D-H…π angle for π interactions (degrees, legacy)
pi_ccl_distance_cutoff (float) – Maximum C-Cl…π distance for halogen-π interactions (Å)
pi_ccl_angle_cutoff (float) – Minimum C-Cl…π angle for halogen-π interactions (degrees)
pi_cbr_distance_cutoff (float) – Maximum C-Br…π distance for halogen-π interactions (Å)
pi_cbr_angle_cutoff (float) – Minimum C-Br…π angle for halogen-π interactions (degrees)
pi_ci_distance_cutoff (float) – Maximum C-I…π distance for halogen-π interactions (Å)
pi_ci_angle_cutoff (float) – Minimum C-I…π angle for halogen-π interactions (degrees)
pi_ch_distance_cutoff (float) – Maximum C-H…π distance for hydrogen-π interactions (Å)
pi_ch_angle_cutoff (float) – Minimum C-H…π angle for hydrogen-π interactions (degrees)
pi_nh_distance_cutoff (float) – Maximum N-H…π distance for hydrogen-π interactions (Å)
pi_nh_angle_cutoff (float) – Minimum N-H…π angle for hydrogen-π interactions (degrees)
pi_oh_distance_cutoff (float) – Maximum O-H…π distance for hydrogen-π interactions (Å)
pi_oh_angle_cutoff (float) – Minimum O-H…π angle for hydrogen-π interactions (degrees)
pi_sh_distance_cutoff (float) – Maximum S-H…π distance for hydrogen-π interactions (Å)
pi_sh_angle_cutoff (float) – Minimum S-H…π angle for hydrogen-π interactions (degrees)
covalent_cutoff_factor (float) – Factor for covalent bond detection
analysis_mode (str) – Analysis mode (‘local’ or ‘global’)
fix_pdb_enabled (bool) – Enable PDB structure fixing
fix_pdb_method (str) – PDB fixing method (‘openbabel’ or ‘pdbfixer’)
fix_pdb_add_hydrogens (bool) – Add missing hydrogen atoms (both methods)
fix_pdb_add_heavy_atoms (bool) – Add missing heavy atoms (PDBFixer only)
fix_pdb_replace_nonstandard (bool) – Replace nonstandard residues (PDBFixer only)
fix_pdb_remove_heterogens (bool) – Remove heterogens (PDBFixer only)
fix_pdb_keep_water (bool) – Keep water when removing heterogens (PDBFixer only)

__eq__(other) → bool[source]#

Compare two AnalysisParameters objects for equality.

Parameters:: other (AnalysisParameters) – Other AnalysisParameters object to compare
Returns:: True if all parameters are equal
Return type:: bool

__hash__() → int[source]#

Return hash of the parameters object for use in sets/dicts.

Returns:: Hash value based on all parameters
Return type:: int

__init__(hb_distance_cutoff: float = 2.5, hb_angle_cutoff: float = 120.0, hb_donor_acceptor_cutoff: float = 3.5, whb_distance_cutoff: float = 3.6, whb_angle_cutoff: float = 150.0, whb_donor_acceptor_cutoff: float = 3.5, xb_distance_cutoff: float = 3.9, xb_angle_cutoff: float = 150.0, pi_distance_cutoff: float = 3.5, pi_angle_cutoff: float = 110.0, pi_ccl_distance_cutoff: float = 3.5, pi_ccl_angle_cutoff: float = 145, pi_cbr_distance_cutoff: float = 3.5, pi_cbr_angle_cutoff: float = 155, pi_ci_distance_cutoff: float = 3.6, pi_ci_angle_cutoff: float = 165.0, pi_ch_distance_cutoff: float = 3.5, pi_ch_angle_cutoff: float = 110.0, pi_nh_distance_cutoff: float = 3.2, pi_nh_angle_cutoff: float = 115.0, pi_oh_distance_cutoff: float = 3.0, pi_oh_angle_cutoff: float = 115.0, pi_sh_distance_cutoff: float = 3.8, pi_sh_angle_cutoff: float = 105.0, covalent_cutoff_factor: float = 0.85, analysis_mode: str = 'complete', fix_pdb_enabled: bool = True, fix_pdb_method: str = 'pdbfixer', fix_pdb_add_hydrogens: bool = True, fix_pdb_add_heavy_atoms: bool = False, fix_pdb_replace_nonstandard: bool = False, fix_pdb_remove_heterogens: bool = False, fix_pdb_keep_water: bool = True, **kwargs)[source]#

Initialize analysis parameters.

Parameters:

hb_distance_cutoff (float) – Maximum H…A distance for hydrogen bonds (Å)
hb_angle_cutoff (float) – Minimum D-H…A angle for hydrogen bonds (degrees)
hb_donor_acceptor_cutoff (float) – Maximum D…A distance for hydrogen bonds (Å)
whb_distance_cutoff (float) – Maximum H…A distance for weak hydrogen bonds (Å)
whb_angle_cutoff (float) – Minimum D-H…A angle for weak hydrogen bonds (degrees)
whb_donor_acceptor_cutoff (float) – Maximum D…A distance for weak hydrogen bonds (Å)
xb_distance_cutoff (float) – Maximum X…A distance for halogen bonds (Å)
xb_angle_cutoff (float) – Minimum C-X…A angle for halogen bonds (degrees)
pi_distance_cutoff (float) – Maximum H…π distance for π interactions (Å)
pi_angle_cutoff (float) – Minimum D-H…π angle for π interactions (degrees)
covalent_cutoff_factor (float) – Factor for covalent bond detection
analysis_mode (str) – Analysis mode (‘local’ or ‘global’)
fix_pdb_enabled (bool) – Enable PDB structure fixing
fix_pdb_method (str) – PDB fixing method (‘openbabel’ or ‘pdbfixer’)
fix_pdb_add_hydrogens (bool) – Add missing hydrogen atoms (both methods)
fix_pdb_add_heavy_atoms (bool) – Add missing heavy atoms (PDBFixer only)
fix_pdb_replace_nonstandard (bool) – Replace nonstandard residues (PDBFixer only)
fix_pdb_remove_heterogens (bool) – Remove heterogens (PDBFixer only)
fix_pdb_keep_water (bool) – Keep water when removing heterogens (PDBFixer only)
kwargs (dict) – Additional parameters (for future extensibility)

__repr__() → str[source]#

Return string representation of the parameters object.

Returns:: String representation showing all parameters
Return type:: str

classmethod from_dict(data: dict) → AnalysisParameters[source]#

Create AnalysisParameters object from dictionary.

Parameters:: data (dict) – Dictionary containing parameter values
Returns:: New AnalysisParameters object
Return type:: AnalysisParameters

to_dict() → dict[source]#

Convert parameters to dictionary format.

Returns:: Dictionary representation of all parameters
Return type:: dict

validate() → List[str][source]#

Validate parameter values and return list of validation errors.

Checks all parameter values for validity and logical consistency. Returns a list of validation error messages, empty list if all valid.

Returns:: List of validation error messages
Return type:: List[str]

class hbat.core.analysis.MolecularInteraction[source]#

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.

property acceptor: Atom | NPVec3D#: Property accessor for acceptor.

property acceptor_residue: str#: Property accessor for acceptor residue.

property angle: float#

Legacy property for interaction angle.

Returns:: Donor-interaction-acceptor angle for backward compatibility
Return type:: float

property distance: float#

Legacy property for interaction distance.

Returns:: Donor-interaction distance for backward compatibility
Return type:: float

property donor: Atom | NPVec3D#: Property accessor for donor.

property donor_acceptor_distance: float#: Property accessor for donor-acceptor distance.

property donor_interaction_acceptor_angle: float#: Property accessor for donor-interaction-acceptor angle.

property donor_interaction_distance: float#: Property accessor for donor-interaction distance.

property donor_residue: str#: Property accessor for donor residue.

abstractmethod get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor_atom() → Atom | None[source]#

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]

abstractmethod get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

abstractmethod get_donor() → Atom | NPVec3D[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

abstractmethod get_donor_acceptor_distance() → float[source]#

Get the donor to acceptor distance.

Returns:: Distance from donor to acceptor in Angstroms
Return type:: float

get_donor_atom() → Atom | None[source]#

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]

abstractmethod get_donor_interaction_acceptor_angle() → float[source]#

Get the donor-interaction-acceptor angle.

Returns:: Angle in radians
Return type:: float

abstractmethod get_donor_interaction_distance() → float[source]#

Get the donor to interaction distance.

Returns:: Distance from donor to interaction point in Angstroms
Return type:: float

abstractmethod get_donor_residue() → str[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

abstractmethod get_interaction() → Atom | NPVec3D[source]#

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_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

property interaction: Atom | NPVec3D#: Property accessor for interaction.

property interaction_type: str#: Property accessor for interaction type.

abstractmethod is_donor_interaction_bonded() → bool[source]#

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

class hbat.core.analysis.HydrogenBond(_donor: Atom, hydrogen: Atom, _acceptor: Atom, distance: float, angle: float, _donor_acceptor_distance: float, bond_type: str, _donor_residue: str, _acceptor_residue: str)[source]#

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

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 acceptor: Atom#: Property accessor for acceptor atom.

property angle: float#

Legacy property for interaction angle.

Returns:: Donor-interaction-acceptor angle for backward compatibility
Return type:: float

property distance: float#

Legacy property for interaction distance.

Returns:: Donor-interaction distance for backward compatibility
Return type:: float

property donor: Atom#: Property accessor for donor atom.

property donor_acceptor_properties: str#

Get the donor-acceptor property description.

Returns:: Property description string
Return type:: str

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_backbone_sidechain_interaction() → str[source]#

Get simplified backbone/sidechain interaction description.

Returns:: Interaction type (B-B, B-S, S-B, S-S)
Return type:: str

get_donor() → Atom | NPVec3D[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_donor_acceptor_distance() → float[source]#: Distance from donor to acceptor.

get_donor_interaction_acceptor_angle() → float[source]#: D-H…A angle.

get_donor_interaction_distance() → float[source]#: Distance from donor to hydrogen.

get_donor_residue() → str[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_interaction() → Atom | NPVec3D[source]#

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_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

is_donor_interaction_bonded() → bool[source]#

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

class hbat.core.analysis.HalogenBond(halogen: Atom, _acceptor: Atom, distance: float, angle: float, bond_type: str, _halogen_residue: str, _acceptor_residue: str)[source]#

Bases: MolecularInteraction

Represents a halogen bond interaction.

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

__init__(halogen: Atom, _acceptor: Atom, distance: float, angle: float, bond_type: str, _halogen_residue: str, _acceptor_residue: str)[source]#

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

property acceptor: Atom#: Property accessor for acceptor atom.

property angle: float#

Legacy property for interaction angle.

Returns:: Donor-interaction-acceptor angle for backward compatibility
Return type:: float

property distance: float#

Legacy property for interaction distance.

Returns:: Donor-interaction distance for backward compatibility
Return type:: float

property donor: Atom#: Property accessor for donor atom (halogen).

property donor_acceptor_properties: str#

Get the donor-acceptor property description.

Returns:: Property description string
Return type:: str

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_backbone_sidechain_interaction() → str[source]#

Get simplified backbone/sidechain interaction description.

Returns:: Interaction type (B-B, B-S, S-B, S-S)
Return type:: str

get_donor() → Atom | NPVec3D[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_donor_acceptor_distance() → float[source]#: Distance from halogen to acceptor.

get_donor_interaction_acceptor_angle() → float[source]#: C-X…A angle.

get_donor_interaction_distance() → float[source]#: Distance from donor to interaction point (0 for halogen bonds).

get_donor_residue() → str[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_interaction() → Atom | NPVec3D[source]#

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_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

property halogen_residue: str#: Legacy property for halogen residue.

is_donor_interaction_bonded() → bool[source]#

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

class hbat.core.analysis.PiInteraction(_donor: Atom, hydrogen: Atom, pi_center: NPVec3D, distance: float, angle: float, _donor_residue: str, _pi_residue: str)[source]#

Bases: MolecularInteraction

Represents a D-X…π interaction.

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)[source]#

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 angle: float#

Legacy property for interaction angle.

Returns:: Donor-interaction-acceptor angle for backward compatibility
Return type:: float

property distance: float#

Legacy property for interaction distance.

Returns:: Donor-interaction distance for backward compatibility
Return type:: float

property donor: Atom#: Property accessor for donor atom.

property donor_acceptor_properties: str#

Get the donor-acceptor property description.

Returns:: Property description string
Return type:: str

get_acceptor() → Atom | NPVec3D[source]#

Get the acceptor atom or virtual atom.

Returns:: The acceptor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_acceptor_residue() → str[source]#

Get the acceptor residue identifier.

Returns:: String identifier for the acceptor residue
Return type:: str

get_backbone_sidechain_interaction() → str[source]#

Get simplified backbone/sidechain interaction description.

Returns:: Interaction type (B-S, S-S, etc.)
Return type:: str

get_donor() → Atom | NPVec3D[source]#

Get the donor atom or virtual atom.

Returns:: The donor atom or virtual atom position
Return type:: Union[Atom, NPVec3D]

get_donor_acceptor_distance() → float[source]#: Distance from donor to π center.

get_donor_interaction_acceptor_angle() → float[source]#: D-H…π angle.

get_donor_interaction_distance() → float[source]#: Distance from donor to interaction atom.

get_donor_residue() → str[source]#

Get the donor residue identifier.

Returns:: String identifier for the donor residue
Return type:: str

get_interaction() → Atom | NPVec3D[source]#

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_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

get_interaction_type_display() → str[source]#

Get the interaction type for display purposes.

Generates display strings for different π interaction subtypes:

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

is_donor_interaction_bonded() → bool[source]#

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 pi_residue: str#: Legacy property for π residue.

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

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)[source]#

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_acceptor() → Atom | NPVec3D[source]#: Get the acceptor of the last interaction in the chain.

get_acceptor_residue() → str[source]#: Get the acceptor residue of the last interaction.

get_donor() → Atom | NPVec3D[source]#: Get the donor of the first interaction in the chain.

get_donor_acceptor_distance() → float[source]#: Get the distance from chain start to end.

get_donor_interaction_acceptor_angle() → float[source]#: Get the angle across the chain (donor-middle-acceptor).

get_donor_interaction_distance() → float[source]#: Get the distance from chain start to middle interaction.

get_donor_residue() → str[source]#: Get the donor residue of the first interaction.

get_interaction() → Atom | NPVec3D[source]#: Get the center point of the chain (middle interaction point).

get_interaction_type() → str[source]#

Get the interaction type.

Returns:: String identifier for the interaction type
Return type:: str

is_donor_interaction_bonded() → bool[source]#

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

Performance Notes#

Optimization Features:

Efficient Parsing: pdbreader integration for fast PDB processing
Spatial Grid: O(n) bond detection using spatial grid partitioning (35x speedup)
Memory Management: Class structures optimized for large-scale analysis
Vectorized Operations: NumPy-accelerated vector mathematics and distance calculations
Direct File Processing: PDB fixing with preserved formatting
Bond Adjacency Maps: O(1) bond lookups for interaction analysis

Scalability:

Handles large protein complexes (>100k atoms)
Memory-efficient data structures with optimized indexing
Spatial partitioning for sub-linear interaction detection
Comprehensive timing and performance metrics

Module Overview

Contents

Module Overview#

Main Analysis Engine#

Molecular Interaction Analyzer#

Interaction Data Structures#

Molecular Interaction Classes#

Base Interaction Class#

Specific Interaction Types#

PDB Structure Handling#

PDB File Parser#

Molecular Data Structures#

PDB Structure Enhancement#

PDB Structure Fixer#

3D Vector Mathematics#

NumPy Vector Operations#

Utility Functions#

Legacy Compatibility#

Analysis Module (Backward Compatibility)#

Performance Notes#