pyfracval.cca_kernels
=====================

.. py:module:: pyfracval.cca_kernels

.. autoapi-nested-parse::

   CCA-specific JIT kernels for PyFracVAL.

   JIT-compiled helper functions used during CCA sticking and retry operations.

   These kernels accelerate retry and overlap stages in the CCA procedure from
   :cite:p:`Moran2019FracVAL`.

   Constants
   ---------
   _GOLDEN_RATIO
       Golden ratio constant used for Fibonacci spiral rotations.
   _TWO_PI
       2 * pi constant for angle calculations.

   Functions
   ---------
   _cca_reintento_kernel
       JIT kernel for the CCA "reintento" (retry) overlap check.
   batch_check_overlaps_cca
       JIT parallel overlap checker for CCA batch rotation.
   batch_rotate_cluster_cca
       Rotate all positions in a CCA cluster around its centre of mass.





Module Contents
---------------

.. py:function:: batch_check_overlaps_cca(coords1, radii1, coords2_batch, radii2, tolerance)

   Check overlap for batch of cluster2 configurations (CCA).

   Uses Numba parallel loops to evaluate multiple cluster configurations simultaneously.

   :param coords1: Cluster 1 coordinates (n1, 3)
   :type coords1: np.ndarray
   :param radii1: Cluster 1 radii (n1,)
   :type radii1: np.ndarray
   :param coords2_batch: Batch of cluster 2 configurations (n_batch, n2, 3)
   :type coords2_batch: np.ndarray
   :param radii2: Cluster 2 radii (n2,) - same for all configurations
   :type radii2: np.ndarray
   :param tolerance: Overlap tolerance
   :type tolerance: float

   :returns: (n_batch,) array of max overlap values for each configuration
   :rtype: np.ndarray


.. py:function:: batch_rotate_cluster_cca(coords2_in, cm2, cand2_idx, vec_0, i_vec, j_vec, angles)

   Batch rotate cluster2 for multiple angles (CCA).

   For each angle, calculates the target position on the intersection circle,
   then rotates the entire cluster to align the candidate particle with that target.

   :param coords2_in: Cluster 2 coordinates (n2, 3)
   :type coords2_in: np.ndarray
   :param cm2: Center of mass of cluster 2 (3,)
   :type cm2: np.ndarray
   :param cand2_idx: Index of candidate particle in cluster 2
   :type cand2_idx: int
   :param vec_0: [x0, y0, z0, r0] - center and radius of intersection circle
   :type vec_0: np.ndarray
   :param i_vec: First basis vector (3,)
   :type i_vec: np.ndarray
   :param j_vec: Second basis vector (3,)
   :type j_vec: np.ndarray
   :param angles: Array of rotation angles (n_angles,)
   :type angles: np.ndarray

   :returns: (n_angles, n2, 3) array of rotated cluster configurations
   :rtype: np.ndarray


.. py:function:: cca_sticking_v1_kernel(coords1_in, radii1, cm1, coords2_in, radii2, cm2_in, cand1_idx, cand2_idx, gamma_pc, theta_a, theta_b)

   Fused ``ext_case=0`` sticking placement.

   The interpreted version of this spends most of its time on numpy
   dispatch for 3-vectors rather than on arithmetic: per N=1024
   aggregate it drove ~30k norm calls, ~24k array allocations and ~20k
   zeros. Fusing the whole placement into one compiled function removes
   all of that, and lets the two cluster transforms run as tight loops.

   Randomness is hoisted out: the two angles the sphere-sphere
   intersections would have sampled are passed in, so this stays pure
   and the caller keeps sole ownership of the RNG stream (which is what
   makes runs reproducible).

   Returns ``(coords1_out, coords2_out, cm2_out, vec0, i_vec, j_vec,
   ok)``; ``ok`` is False when either intersection has no solution, in
   which case the arrays are meaningless and the caller must skip them.