pyfracval.experimental.fft_docking#

FFT-based rigid-body docking for CCA sticking.

Implements the Katchalski-Katzir cross-correlation algorithm adapted for fractal aggregate sticking. Replaces the stochastic Fibonacci search with deterministic translation evaluation via 3D FFT.

The module voxellises two clusters onto a 3D grid, computes FFT cross-correlation for each rotation of cluster 2, extracts top-K peaks, and validates each candidate with exact overlap + gamma_pc checks.

Reference: Katchalski-Katzir et al., PNAS 89(6):2195-2199, 1992.

Module Contents#

pyfracval.experimental.fft_docking.sample_so3_rotations(n_rotations=70)[source]#

Generate near-uniform rotation matrices on SO(3).

Uses the Hopf fibration approach: sample points on S2 for the rotation axis direction, then Niño et al. twist angles.

For n_rotations ~ 70 this gives roughly 15-degree resolution.

Parameters:

n_rotations (int) – Number of rotation matrices to generate.

Return type:

List of (3, 3) rotation matrices.

pyfracval.experimental.fft_docking.voxelize_cluster(coords, radii, cm, grid_size, voxel_size, mode=0)[source]#

Convert a particle cluster to a 3D voxel grid.

Parameters:

  • coords ((N, 3) particle centres.)

  • radii ((N,) particle radii.)

  • cm ((3,) centre-of-mass (grid will be centred here).)

  • grid_size (int, side length of the cubic grid.)

  • voxel_size (float, size of each voxel in simulation units.)

  • mode (0 = surface shell only (+1); 1 = interior (-1), surface (+1).)

Returns:

  • grid ((grid_size, grid_size, grid_size) int8 array)

  • origin ((3,) real-coordinate of grid[0,0,0] corner)

pyfracval.experimental.fft_docking.compute_fft_correlation(grid1, grid2)[source]#

Compute 3D cross-correlation via FFT.

Uses the convolution theorem: correlation(A, B) = IFFT(FFT(A) * conj(FFT(B))).

Parameters:

  • grid1 ((gx, gy, gz) receptor grid (cluster 1).)

  • grid2 ((gx, gy, gz) ligand grid (cluster 2, already rotated).)

Returns:

corr

Return type:

(gx, gy, gz) float64 correlation surface.

pyfracval.experimental.fft_docking.extract_top_k_peaks(corr, k=10, min_distance=3)[source]#

Extract top-k peaks from a 3D correlation surface.

A peak must be the local maximum within a min_distance cube. Returns list of (score, dx, dy, dz) sorted by score descending, where (dx, dy, dz) is the translation offset in grid units.

pyfracval.experimental.fft_docking.validate_placement(coords1, radii1, coords2, radii2, cm1, cm2_target, gamma_pc, gamma_real, tol_ov, gamma_tolerance=0.1)[source]#

Validate a candidate placement for sticking.

Checks: 1. Distance between CMs is approximately gamma_pc. 2. No particle overlap beyond tolerance.

Parameters:

  • coords1 (cluster 1 particles)

  • radii1 (cluster 1 particles)

  • coords2 (cluster 2 particles (already placed at candidate position))

  • radii2 (cluster 2 particles (already placed at candidate position))

  • cm1 (centre-of-mass of cluster 1)

  • cm2_target (centre-of-mass of cluster 2 at candidate position)

  • gamma_pc (target inter-cluster distance)

  • gamma_real (whether gamma_pc is physically meaningful)

  • tol_ov (maximum allowable overlap fraction)

  • gamma_tolerance (relative tolerance on gamma_pc distance check)

Return type:

(valid, distance, max_overlap)

pyfracval.experimental.fft_docking.fft_dock_sticking(coords1, radii1, coords2, radii2, cm1, cm2, gamma_pc, gamma_real, tol_ov, grid_size=64, num_rotations=70, top_k_peaks=10, gamma_tolerance=0.1, min_peak_distance=3)[source]#

Attempt FFT-based rigid-body docking for two clusters.

For each rotation of cluster 2: 1. Voxelize both clusters onto 3D grids 2. Compute FFT cross-correlation 3. Extract top-K translation peaks 4. Validate each candidate with exact overlap + gamma_pc checks

Parameters:

  • coords1 (cluster 1 particles)

  • radii1 (cluster 1 particles)

  • coords2 (cluster 2 particles)

  • radii2 (cluster 2 particles)

  • cm1 (centres-of-mass of clusters 1 and 2)

  • cm2 (centres-of-mass of clusters 1 and 2)

  • gamma_pc (target inter-cluster distance for sticking)

  • gamma_real (whether gamma_pc is physically valid)

  • tol_ov (maximum allowable overlap fraction)

  • grid_size (side length of cubic voxel grid)

  • num_rotations (number of SO(3) rotation samples)

  • top_k_peaks (number of translation candidates to evaluate per rotation)

  • gamma_tolerance (relative tolerance for gamma_pc distance check)

  • min_peak_distance (minimum grid-cell distance between peaks)

Return type:

(combined_coords, combined_radii) if sticking succeeds, None otherwise.