pyfracval.utils#

Utility functions for vector operations and array manipulation.

Module Contents#

pyfracval.utils.shuffle_array(arr)[source]#

Randomly shuffle elements of a 1D array in-place (Fisher-Yates).

Modifies the input array directly. Mimics Fortran randsample behavior.

Parameters:

arr – The 1D NumPy array to shuffle.

Returns:

The input arr, modified in-place.

pyfracval.utils.sort_clusters(i_orden)[source]#

Sort cluster information array i_orden by cluster size (count).

Parameters:

i_orden (np.ndarray) – The Mx3 NumPy array [start_idx, end_idx, count].

Returns:

A new Mx3 array sorted by the ‘count’ column (column index 2).

Return type:

np.ndarray

Raises:

ValueError – If i_orden is not an Mx3 array.

pyfracval.utils.cross_product(a, b)[source]#

Calculate the cross product of two 3D vectors.

Parameters:

  • a (np.ndarray) – The first 3D vector.

  • b (np.ndarray) – The second 3D vector.

Returns:

The 3D cross product vector.

Return type:

np.ndarray

See also

numpy.cross

NumPy’s implementation.

pyfracval.utils.normalize(v)[source]#

Normalize a vector to unit length.

Returns a zero vector if the input vector’s norm is close to zero.

Parameters:

v (np.ndarray) – The vector (1D array) to normalize.

Returns:

The normalized vector, or a zero vector if the norm is negligible.

Return type:

np.ndarray

pyfracval.utils.calculate_mass(radii)[source]#

Calculate particle mass from radii assuming constant density (prop. to R^3).

Parameters:

radii (np.ndarray) – Array of particle radii.

Returns:

Array of corresponding particle masses.

Return type:

np.ndarray

pyfracval.utils.calculate_rg(radii, npp, df, kf)[source]#

Calculate the radius of gyration using the fractal scaling law.

Implements the formula Rg = a * (N / kf)^(1/Df), where ‘a’ is the geometric mean radius calculated from the input radii array. See [Morán et al., 2019].

Parameters:

  • radii (np.ndarray) – Array of radii of particles in the cluster/aggregate.

  • npp (int) – Number of primary particles (N) in the cluster.

  • df (float) – Fractal dimension (Df).

  • kf (float) – Fractal prefactor (kf).

Returns:

The calculated radius of gyration (Rg). Returns 0.0 if npp is 0, kf or df is zero, or if calculation fails (e.g., log error).

Return type:

float

pyfracval.utils.calculate_cluster_properties(coords, radii, df, kf)[source]#

Calculate aggregate properties: total mass, Rg, center of mass, Rmax.

Parameters:

  • coords (np.ndarray) – Nx3 array of particle coordinates.

  • radii (np.ndarray) – N array of particle radii.

  • df (float) – Fractal dimension used for Rg calculation.

  • kf (float) – Fractal prefactor used for Rg calculation.

Returns:

A tuple containing:

  • total_mass (float): Sum of individual particle masses.

  • rg (float | None): Radius of gyration calculated via calculate_rg, or None if calculation failed.

  • cm (np.ndarray | None): 3D center of mass coordinates, or None if calculation failed.

  • r_max (float): Maximum distance from the center of mass to any particle center in the aggregate.

Returns (0.0, 0.0, np.zeros(3), 0.0) for empty inputs (N=0).

Return type:

tuple[float, float | None, np.ndarray | None, float]

pyfracval.utils.rodrigues_rotation(vectors, axis, angle)[source]#

Rotate vector(s) around an axis using Rodrigues’ rotation formula.

Parameters:

  • vectors (np.ndarray) – A single 3D vector or an Nx3 array of vectors to rotate.

  • axis (np.ndarray) – The 3D rotation axis (does not need to be normalized).

  • angle (float) – The rotation angle in radians.

Returns:

The rotated vector or Nx3 array of rotated vectors. Returns the original vectors if the axis norm is near zero.

Return type:

np.ndarray

Raises:

ValueError – If input vectors is not 1D (3,) or 2D (N, 3).

pyfracval.utils.two_sphere_intersection(sphere_1, sphere_2)[source]#

Find the intersection circle of two spheres and pick a random point.

Calculates the center (x0, y0, z0) and radius (r0) of the intersection circle, defines basis vectors (i_vec, j_vec) for the circle’s plane, and returns a random point (x, y, z) on that circle based on a random angle (theta).

Handles edge cases: spheres too far, one contained, coincidence, touching.

Parameters:

  • sphere_1 (np.ndarray) – Definition of the first sphere: [x1, y1, z1, r1].

  • sphere_2 (np.ndarray) – Definition of the second sphere: [x2, y2, z2, r2].

Returns:

A tuple containing:

  • x, y, z (float): Coordinates of a random point on the intersection.

  • theta (float): Random angle (radians) used to generate the point.

  • vec_0 (np.ndarray): [x0, y0, z0, r0] - center and radius of the intersection circle (r0=0 if spheres touch at a point).

  • i_vec (np.ndarray): First basis vector of the intersection plane.

  • j_vec (np.ndarray): Second basis vector of the intersection plane.

  • valid (bool): True if a valid intersection (circle or point) exists, False otherwise (e.g., separate, contained, coincident).

Return type:

tuple[float, float, float, float, np.ndarray, np.ndarray, np.ndarray, bool]

pyfracval.utils.calculate_max_overlap_cca(coords1, radii1, coords2, radii2)[source]#

Calculate max overlap between two particle clusters (Numba optimized).

Overlap is defined as 1 - distance / (radius1 + radius2) for overlapping pairs, max(0).

Parameters:

  • coords1 (np.ndarray) – Nx3 coordinates of cluster 1.

  • radii1 (np.ndarray) – N radii of cluster 1.

  • coords2 (np.ndarray) – Mx3 coordinates of cluster 2.

  • radii2 (np.ndarray) – M radii of cluster 2.

Returns:

Maximum overlap fraction found between any particle in cluster 1 and any particle in cluster 2. Returns 0.0 if no overlap.

Return type:

float

pyfracval.utils.calculate_max_overlap_pca(coords_agg, radii_agg, coord_new, radius_new)[source]#

Calculate max overlap between a new particle and an aggregate (Numba).

Overlap is defined as 1 - distance / (radius_new + radius_agg) for overlapping pairs, max(0).

Parameters:

  • coords_agg (np.ndarray) – Nx3 coordinates of the existing aggregate.

  • radii_agg (np.ndarray) – N radii of the aggregate particles.

  • coord_new (np.ndarray) – 3D coordinates of the new particle.

  • radius_new (float) – Radius of the new particle.

Returns:

Maximum overlap fraction found between the new particle and any particle in the aggregate. Returns 0.0 if no overlap.

Return type:

float