Hull

Convex hull construction and per-frame pocket volume computation.

This module contains the ConvexHull class used for two distinct purposes in POVME:

1. Pocket detection by building a convex hull around the protein so that grid points outside the protein surface can be discarded.
2. Per-frame volume calculation that removes grid points that clash with receptor atoms, optionally excludes points outside the convex hull, enforces pocket contiguity, and computes the final pocket volume.

ConvexHull(pts)

A class to handle convex-hull calculations.

seg_dict is a dictionary object that contains information about segments within the convex hull.

• The keys are 2x3 tuples, which represent two ends of a segment in space.
• The values of seg_dict are the number of times a segment has been part of a triangle, either 1 or 2. 0 times would mean that the segment doesn't exist in the dictionary yet.

Initializes the ConvexHull class.

hull = self.gift_wrapping_3d(akl_toussaint_pts)

akl_toussaint(points)

The Akl-Toussaint Heuristic.

Given a set of points, this definition will create an octahedron whose corners are the extremes in x, y, and z directions. Every point within this octahedron will be removed because they are not part of the convex hull. This causes any expected running time for a convex hull algorithm to be reduced to linear time.

PARAMETER	DESCRIPTION
points	An nx3 array of x,y,z coordinates. TYPE: NDArray[float64]

RETURNS	DESCRIPTION
NDArray[float64]	All members of original set of points that fall outside the Akl-Toussaint octahedron.

get_seg_dict_num(seg_dict, seg_index)

This function looks up and returns the value of a seg_index from seg_dict.

PARAMETER	DESCRIPTION
seg_dict	The dictionary of segment 2x3 tuples as keys, integers as values. TYPE: dict[tuple[tuple[float64, ...], ...], int]
seg_index	the key of the dictionary member we are going to retrieve TYPE: tuple[tuple[float64, ...], ...]

RETURNS	DESCRIPTION
int	If seg_index exists in the keys of seg_dict, return the value. Otherwise, return 0.

gift_wrapping_3d(raw_points)

Gift wrapping for 3d convex hull.

PARAMETER	DESCRIPTION
raw_points	A nx3 array of points, where each row corresponds to an x,y,z point coordinate. TYPE: NDArray[float64]

RETURNS	DESCRIPTION
list[NDArray[float64]]	A convex hull represented by a list of triangles. Each triangle is a 3x3 array, where each row is an x,y,z coordinate in space. The 3 rows describe the location of the 3 corners of the triangle. Each of the 3 points are arranged so that a cross product will point outwards from the hull.

increment_seg_dict(seg_dict, seg_index)

This function increments the values within seg_dict, or initiates them if they dont exist yet.

PARAMETER	DESCRIPTION
seg_dict	the dictionary of segment 2x3 tuples as keys, integers as values. TYPE: dict[tuple[tuple[float64, ...], ...], int]
seg_index	the key of the dictionary member we are going to increment. TYPE: tuple[tuple[float64, ...], ...]

inside_hull(our_point)

Determines if a point is inside the hull

PARAMETER	DESCRIPTION
our_point	An x,y,z array

RETURNS	DESCRIPTION
	A boolean, True if the point is inside the hull, False otherwise.

outside_hull(point, triangles, epsilon=1e-05)

Given the hull as defined by a list of triangles, this definition will return whether a point is within these or not.

PARAMETER	DESCRIPTION
point	an x,y,z array that is being tested to see whether it exists inside the hull or not. TYPE: list[float]
triangles	a list of triangles that define the hull. TYPE: list[NDArray[float64]]
epsilon	needed for imprecisions in the floating-point operations. TYPE: float DEFAULT: 1e-05

RETURNS	DESCRIPTION
bool	True if our_point exists outside of the hull, False otherwise

volume(frame_indx, pdb, pts, regions_contig, output_prefix, config)

Compute the pocket volume for a single trajectory frame.

1. Discard receptor atoms too far from the grid to matter.
2. Build a KDTree on the remaining atom coordinates and use query_ball_point to identify grid points that clash with any atom's van der Waals sphere (plus config.distance_cutoff).
3. Optionally exclude points outside the convex hull of non-hydrogen receptor atoms.
4. Optionally enforce contiguous-pocket constraints using a KD-tree-based BFS flood fill.
5. Compute the volume as N_surviving_points x grid_spacing^3.

PARAMETER	DESCRIPTION
frame_indx	1-based frame index within the trajectory.
pdb	A pymolecule.Molecule instance holding one frame.
pts	An (N, 3) array of grid points defining the pocket-encompassing region.
regions_contig	A list of Region objects defining the contiguous-pocket seed region(s). May be empty if contiguity is not enforced.
output_prefix	Directory/filename prefix for output files.
config	A PocketVolumeConfig instance controlling algorithmic parameters.

RETURNS	DESCRIPTION
	The input frame index (for bookkeeping).
	The pocket volume.
	A dict that may contain the key "SaveVolumetricDensityMap" mapping to the surviving point array (if the user requested a density map).

TaskCalcVolume

Bases: RayTaskGeneral

A class for calculating the volume.

process_item(item)

Calculate the volume.

PARAMETER	DESCRIPTION
item	A list or tuple containing necessary input data.

RETURNS	DESCRIPTION
	A tuple with frame index, calculated volume, and any extra data.

flood_fill_contiguous_kdtree(pts, contig_seed_pts, grid_spacing)

Identify pocket points contiguous with a seed region using BFS.

1. Builds a single KDTree over all surviving pocket points.
2. Pre-computes the full neighbor-list for every point in one query_ball_point call, stored as a Python list of lists.
3. Finds which pocket points coincide with seed points using a second KD-tree query.
4. Runs a breadth-first search (BFS) over the neighbor graph, expanding from the seed set.

PARAMETER	DESCRIPTION
pts	An array of shape (n, 3) containing the surviving pocket points (already pruned by clash detection and neighbor filtering). TYPE: NDArray[float64]
contig_seed_pts	An array of shape (m, 3) containing the grid points inside the user-defined contiguous-pocket seed region(s). TYPE: NDArray[float64]
grid_spacing	The POVME grid spacing in Angstroms. Used to derive the neighbor cutoff (diagonal of a grid cell). TYPE: float

RETURNS	DESCRIPTION
NDArray[float64]	An array of shape (k, 3) containing the subset of pts that are reachable from the seed region through contiguous grid neighbors. Returns an empty array if no seed points overlap with surviving pocket points.

unique_rows(a)

Identifies unique points (rows) in an array of points.

PARAMETER	DESCRIPTION
a	A nx3 np.array representing 3D points.

RETURNS	DESCRIPTION
	A nx2 np.array containing the 3D points that are unique.