Volume

Pocket volume calculation for single structures and MD trajectories.

This module provides the PocketVolume class, which orchestrates the end-to-end POVME volume-measurement workflow:

1. Generate (or load) the pocket-encompassing point field from user-defined inclusion/exclusion regions.
2. Distribute per-frame volume calculations across workers using RayManager.
3. Collect results and optionally write trajectory PDBs and volumetric density maps.

PocketVolume(config=None)

The main class to run POVME.

Initialize POVME.

PARAMETER	DESCRIPTION
config	Pocket volume calculation configuration. TYPE: PocketVolumeConfig | None DEFAULT: None

config = config

gen_points(config)

Generate the pocket-encompassing point field.

Constructs a regular grid of 3D points by unioning all inclusion-region grids and then subtracting all exclusion-region grids.

PARAMETER	DESCRIPTION
config	The volume-calculation configuration, which specifies inclusion/exclusion spheres and boxes and the grid spacing.

RETURNS	DESCRIPTION
	An (K, 3) array of unique grid points that lie inside at least one inclusion region and outside all exclusion regions.

run(path_pdb, output_prefix=None, chunk_size=10)

Start POVME

PARAMETER	DESCRIPTION
path_pdb	Path to PDB file. This will overwrite the configuration file. TYPE: str
output_prefix	Path to output directory including directories. TYPE: str | None DEFAULT: None

write_points(pts, output_prefix, config)

write_points_contig(regions_contig, output_prefix, config)

write_vol_dens(results, output_prefix, config)

write_vol_traj(results_vol, output_prefix, config)

TaskComputeVolumeFromPDBLines

Bases: RayTaskGeneral

process_item(item)

collect_pdb_frames_in_chunks(filename, chunk_size)

Read a multi-frame PDB and yield frames in chunks.

Frames are delimited by lines starting with END. Frames are accumulated into chunks of chunk_size before being yielded, reducing the overhead of task submission when using parallel workers.

PARAMETER	DESCRIPTION
filename	Path to the multi-frame PDB file. TYPE: str
chunk_size	Maximum number of frames per yielded chunk. TYPE: int

YIELDS	DESCRIPTION
list[tuple[int, str]]	Lists of (frame_index, pdb_frame_string) tuples. The frame_index is 1-based. The final yielded chunk may contain fewer than chunk_size frames.

get_unique_rows(a)

Return the unique rows of a 2-D array.

Each row is treated as an opaque byte string so that numpy.unique can identify duplicates without floating-point tolerance issues (the input is assumed to be snapped to a grid).

PARAMETER	DESCRIPTION
a	An array of shape (n, d) (typically d = 3).

RETURNS	DESCRIPTION
	An array of shape (m, d) (m <= n) containing only the
	unique rows, in sorted order.

remove_exclusion_points(pts, pts_exclusion)

Remove inclusion points that coincide with exclusion points.

Both point sets are assumed to lie on the same regular grid (i.e., their coordinates are exact multiples of the grid spacing after snapping). Instead of computing a full pairwise distance matrix with cdist, this function performs a set-difference using NumPy's structured-array view trick.

1. Each (x, y, z) row is reinterpreted as a single opaque np.void element.
2. numpy.isin performs a hash-based membership test.

PARAMETER	DESCRIPTION
pts	An (N, 3) array of inclusion grid points. TYPE: ndarray
pts_exclusion	An (M, 3) array of exclusion grid points. TYPE: ndarray

RETURNS	DESCRIPTION
ndarray	An (K, 3) array (K <= N) containing only those rows of pts that do not appear in pts_exclusion.