GridCalculator API

docksuitex.grid_calculator

Grid box calculator for molecular docking.

Provides a unified :class:GridCalculator that supports two modes:

• "blind" — computes a bounding box encompassing all receptor heavy atoms.
• "p2rank" — runs P2Rank to predict binding pockets and computes a per-pocket bounding box from residue atom coordinates.

GridCalculator

Unified grid box calculator for molecular docking.

Supports two modes:

"blind" Computes a single box enclosing all receptor heavy atoms.

"p2rank" Runs P2Rank to predict binding pockets, then computes a per-pocket bounding box from residue atom coordinates.

Both modes return a list[dict]. Each dict contains: - rank (int): Pocket rank (1 = best). - probability (float): Predicted binding probability (0–1). For blind mode this is always 1.0. - center (tuple[float, float, float]): Grid centre (x, y, z) Å. - grid_size (tuple[float, float, float] | None): Box dimensions Å.

__init__

__init__(
    receptor: Union[str, Path],
    mode: str = "p2rank",
    _cpu: int = (os.cpu_count() or 2) - 1,
    padding: float = DEFAULT_PADDING,
)

Initialise GridCalculator.

Parameters:

Name	Type	Description	Default
receptor	Union[str, Path]	Path to a receptor .pdb or .pdbqt file.	required
mode	str	"blind" or "p2rank". Defaults to "p2rank".	'p2rank'
_cpu	int	CPU cores for P2Rank (ignored in blind mode). Defaults to cpu_count - 1.	(cpu_count() or 2) - 1
padding	float	Padding in Å added to the bounding box. Defaults to 10.0.	DEFAULT_PADDING

Raises:

Type	Description
ValueError	If mode is not "blind" or "p2rank", or if the receptor file format is unsupported.
FileNotFoundError	If the receptor file does not exist.

run

run(save_to: Union[str, Path, None] = None) -> List[Dict]

Compute the grid box(es).

Parameters:

Name	Type	Description	Default
save_to	Union[str, Path, None]	Output directory for P2Rank files (P2Rank mode only). Defaults to ./p2rank_results_<filename> in P2Rank mode.	None

Returns:

Type	Description
List[Dict]	A list[dict], each with keys rank, probability,
List[Dict]	center, grid_size. Blind mode returns a single-element
List[Dict]	list.

compute_blind_box

compute_blind_box(
    pdb_file: Union[str, Path], padding: float = 10.0
) -> tuple[
    tuple[float, float, float], tuple[float, float, float]
]

Compute a grid box enclosing all non-hydrogen atoms of a receptor.

Reads ATOM / HETATM records directly from a PDB or PDBQT file (no BioPython needed — plain column parsing is sufficient and fast).

Parameters:

Name	Type	Description	Default
pdb_file	Union[str, Path]	Path to a PDB or PDBQT file.	required
padding	float	Extra space in Å added to each dimension. Defaults to 10.0.	10.0

Returns:

Type	Description
tuple[tuple[float, float, float], tuple[float, float, float]]	(center, size) — each a 3-tuple of floats in Å.

Raises:

Type	Description
ValueError	If no heavy-atom coordinates are found.