pyfracval.experimental.fft_docking
==================================

.. py:module:: pyfracval.experimental.fft_docking

.. autoapi-nested-parse::

   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
---------------

.. py:function:: sample_so3_rotations(n_rotations = 70)

   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.

   :param n_rotations: Number of rotation matrices to generate.
   :type n_rotations: int

   :rtype: List of (3, 3) rotation matrices.


.. py:function:: voxelize_cluster(coords, radii, cm, grid_size, voxel_size, mode = 0)

   Convert a particle cluster to a 3D voxel grid.

   :param coords:
   :type coords: (N, 3) particle centres.
   :param radii:
   :type radii: (N,) particle radii.
   :param cm:
   :type cm: (3,) centre-of-mass (grid will be centred here).
   :param grid_size:
   :type grid_size: int, side length of the cubic grid.
   :param voxel_size:
   :type voxel_size: float, size of each voxel in simulation units.
   :param mode:
   :type 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*)


.. py:function:: compute_fft_correlation(grid1, grid2)

   Compute 3D cross-correlation via FFT.

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

   :param grid1:
   :type grid1: (gx, gy, gz) receptor grid (cluster 1).
   :param grid2:
   :type grid2: (gx, gy, gz) ligand grid (cluster 2, already rotated).

   :returns: **corr**
   :rtype: (gx, gy, gz) float64 correlation surface.


.. py:function:: extract_top_k_peaks(corr, k = 10, min_distance = 3)

   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.


.. py:function:: validate_placement(coords1, radii1, coords2, radii2, cm1, cm2_target, gamma_pc, gamma_real, tol_ov, gamma_tolerance = 0.1)

   Validate a candidate placement for sticking.

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

   :param coords1:
   :type coords1: cluster 1 particles
   :param radii1:
   :type radii1: cluster 1 particles
   :param coords2:
   :type coords2: cluster 2 particles (already placed at candidate position)
   :param radii2:
   :type radii2: cluster 2 particles (already placed at candidate position)
   :param cm1:
   :type cm1: centre-of-mass of cluster 1
   :param cm2_target:
   :type cm2_target: centre-of-mass of cluster 2 at candidate position
   :param gamma_pc:
   :type gamma_pc: target inter-cluster distance
   :param gamma_real:
   :type gamma_real: whether gamma_pc is physically meaningful
   :param tol_ov:
   :type tol_ov: maximum allowable overlap fraction
   :param gamma_tolerance:
   :type gamma_tolerance: relative tolerance on gamma_pc distance check

   :rtype: (valid, distance, max_overlap)


.. py:function:: 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)

   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

   :param coords1:
   :type coords1: cluster 1 particles
   :param radii1:
   :type radii1: cluster 1 particles
   :param coords2:
   :type coords2: cluster 2 particles
   :param radii2:
   :type radii2: cluster 2 particles
   :param cm1:
   :type cm1: centres-of-mass of clusters 1 and 2
   :param cm2:
   :type cm2: centres-of-mass of clusters 1 and 2
   :param gamma_pc:
   :type gamma_pc: target inter-cluster distance for sticking
   :param gamma_real:
   :type gamma_real: whether gamma_pc is physically valid
   :param tol_ov:
   :type tol_ov: maximum allowable overlap fraction
   :param grid_size:
   :type grid_size: side length of cubic voxel grid
   :param num_rotations:
   :type num_rotations: number of SO(3) rotation samples
   :param top_k_peaks:
   :type top_k_peaks: number of translation candidates to evaluate per rotation
   :param gamma_tolerance:
   :type gamma_tolerance: relative tolerance for gamma_pc distance check
   :param min_peak_distance:
   :type min_peak_distance: minimum grid-cell distance between peaks

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