pyfracval.pca_kernels
=====================

.. py:module:: pyfracval.pca_kernels

.. autoapi-nested-parse::

   PCA-specific JIT kernels for PyFracVAL.

   JIT-compiled batch functions for PCA position calculation and overlap checking.

   These kernels support the PCA stage in the FracVAL-style aggregation pipeline
   :cite:p:`Moran2019FracVAL`.

   Functions
   ---------
   batch_calculate_positions_pca
       JIT batch calculation of particle positions during PCA.
   batch_check_overlaps_pca
       JIT parallel overlap checker for PCA batch operations.





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

.. py:function:: batch_calculate_positions_pca(vec_0, i_vec, j_vec, angles)

   Calculate batch of positions on intersection circle for PCA.

   Uses Numba parallel loops to compute multiple rotation positions simultaneously.

   :param vec_0: [x0, y0, z0, r0] - center and radius of intersection circle
   :type vec_0: np.ndarray
   :param i_vec: First basis vector (3D)
   :type i_vec: np.ndarray
   :param j_vec: Second basis vector (3D)
   :type j_vec: np.ndarray
   :param angles: Array of rotation angles (1D)
   :type angles: np.ndarray

   :returns: (N, 3) array of positions, one per angle
   :rtype: np.ndarray


.. py:function:: batch_check_overlaps_pca(coords_agg, radii_agg, candidate_positions, radius_new, tolerance)

   Check overlap for batch of candidate positions (PCA).

   Uses Numba parallel loops to evaluate multiple positions simultaneously.

   :param coords_agg: Current aggregate coordinates (n_agg, 3)
   :type coords_agg: np.ndarray
   :param radii_agg: Current aggregate radii (n_agg,)
   :type radii_agg: np.ndarray
   :param candidate_positions: Batch of candidate positions to test (n_candidates, 3)
   :type candidate_positions: np.ndarray
   :param radius_new: Radius of new particle
   :type radius_new: float
   :param tolerance: Overlap tolerance
   :type tolerance: float

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