pyfracval.experimental.soft_relaxation#

Soft potential relaxation for cluster-cluster aggregation.

Implements force-driven relaxation using harmonic repulsion potentials as an alternative to rigid-body docking for hard regimes (Df≥2.25).

The approach: 1. Initial placement at target gamma_pc distance 2. Compute repulsive forces from overlapping particles 3. Add restoring force to maintain gamma_pc constraint 4. Gradient descent until convergence 5. Return relaxed configuration

Module Contents#

pyfracval.experimental.soft_relaxation.compute_forces(coords, radii, k_repulsion=10.0, cm_target=None, k_gamma=1.0, gamma_target=0.0)[source]#

Compute forces on all particles.

Parameters:

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

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

  • k_repulsion (float) – Spring constant for harmonic repulsion (default 10.0).

  • cm_target (np.ndarray, optional) – Target center of mass position for gamma constraint.

  • k_gamma (float) – Spring constant for gamma constraint (default 1.0).

  • gamma_target (float) – Target gamma distance (not used directly, only for CM constraint).

Returns:

  • forces (np.ndarray) – Nx3 array of forces.

  • max_overlap (float) – Maximum overlap fraction.

  • total_energy (float) – Total potential energy.

pyfracval.experimental.soft_relaxation.soft_relaxation(coords, radii, cm_target, k_repulsion=10.0, k_gamma=1.0, max_iters=100, tol_overlap=0.0001, tol_force=0.001, learning_rate=0.1, verbose=False)[source]#

Relax configuration using gradient descent on soft potential.

Parameters:

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

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

  • cm_target (np.ndarray) – Target center of mass position.

  • k_repulsion (float) – Spring constant for repulsion (default 10.0).

  • k_gamma (float) – Spring constant for gamma constraint (default 1.0).

  • max_iters (int) – Maximum gradient descent iterations.

  • tol_overlap (float) – Convergence tolerance for max overlap.

  • tol_force (float) – Convergence tolerance for max force magnitude.

  • learning_rate (float) – Gradient descent step size (default 0.1).

  • verbose (bool) – Print progress information.

Returns:

  • coords (np.ndarray) – Relaxed coordinates.

  • success (bool) – True if converged within tolerances.

  • info (dict) – Diagnostics (iterations, final energy, max overlap, etc.).

pyfracval.experimental.soft_relaxation.soft_sticking(coords1, radii1, coords2, radii2, gamma_pc, cm1, cm2, candidate_particle_idx1, candidate_particle_idx2, k_repulsion=10.0, k_gamma=1.0, gamma_tolerance=0.05, max_iters=100, tol_overlap=0.0001, learning_rate=0.1)[source]#

Stick two clusters using soft potential relaxation.

This is an alternative to rigid-body docking that allows small deviations from exact gamma_pc distance to resolve overlaps.

Parameters:

  • coords1 (np.ndarray) – Coordinates of clusters 1 and 2.

  • coords2 (np.ndarray) – Coordinates of clusters 1 and 2.

  • radii1 (np.ndarray) – Radii of clusters 1 and 2.

  • radii2 (np.ndarray) – Radii of clusters 1 and 2.

  • gamma_pc (float) – Target distance between cluster centers.

  • cm1 (np.ndarray) – Current centers of mass.

  • cm2 (np.ndarray) – Current centers of mass.

  • candidate_particle_idx1 (int) – Indices of particles that should be brought into contact.

  • candidate_particle_idx2 (int) – Indices of particles that should be brought into contact.

  • k_repulsion (float) – Repulsion spring constant.

  • k_gamma (float) – Gamma constraint spring constant.

  • gamma_tolerance (float) – Allowed fractional deviation from gamma_pc (default 5%).

  • max_iters (int) – Maximum relaxation iterations.

  • tol_overlap (float) – Overlap convergence tolerance.

  • learning_rate (float) – Gradient descent step size.

Returns:

  • new_coords1, new_coords2 (np.ndarray) – Relaxed coordinates for both clusters.

  • success (bool) – True if relaxation converged within tolerances.

  • info (dict) – Diagnostics including final gamma error.