pyfracval.experimental.soft_relaxation ====================================== .. py:module:: pyfracval.experimental.soft_relaxation .. autoapi-nested-parse:: 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 --------------- .. py:function:: compute_forces(coords, radii, k_repulsion = 10.0, cm_target = None, k_gamma = 1.0, gamma_target = 0.0) Compute forces on all particles. :param coords: Nx3 array of particle coordinates. :type coords: np.ndarray :param radii: N array of particle radii. :type radii: np.ndarray :param k_repulsion: Spring constant for harmonic repulsion (default 10.0). :type k_repulsion: float :param cm_target: Target center of mass position for gamma constraint. :type cm_target: np.ndarray, optional :param k_gamma: Spring constant for gamma constraint (default 1.0). :type k_gamma: float :param gamma_target: Target gamma distance (not used directly, only for CM constraint). :type gamma_target: float :returns: * **forces** (*np.ndarray*) -- Nx3 array of forces. * **max_overlap** (*float*) -- Maximum overlap fraction. * **total_energy** (*float*) -- Total potential energy. .. py:function:: 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) Relax configuration using gradient descent on soft potential. :param coords: Nx3 array of initial coordinates. :type coords: np.ndarray :param radii: N array of particle radii. :type radii: np.ndarray :param cm_target: Target center of mass position. :type cm_target: np.ndarray :param k_repulsion: Spring constant for repulsion (default 10.0). :type k_repulsion: float :param k_gamma: Spring constant for gamma constraint (default 1.0). :type k_gamma: float :param max_iters: Maximum gradient descent iterations. :type max_iters: int :param tol_overlap: Convergence tolerance for max overlap. :type tol_overlap: float :param tol_force: Convergence tolerance for max force magnitude. :type tol_force: float :param learning_rate: Gradient descent step size (default 0.1). :type learning_rate: float :param verbose: Print progress information. :type verbose: bool :returns: * **coords** (*np.ndarray*) -- Relaxed coordinates. * **success** (*bool*) -- True if converged within tolerances. * **info** (*dict*) -- Diagnostics (iterations, final energy, max overlap, etc.). .. py:function:: 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) 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. :param coords1: Coordinates of clusters 1 and 2. :type coords1: np.ndarray :param coords2: Coordinates of clusters 1 and 2. :type coords2: np.ndarray :param radii1: Radii of clusters 1 and 2. :type radii1: np.ndarray :param radii2: Radii of clusters 1 and 2. :type radii2: np.ndarray :param gamma_pc: Target distance between cluster centers. :type gamma_pc: float :param cm1: Current centers of mass. :type cm1: np.ndarray :param cm2: Current centers of mass. :type cm2: np.ndarray :param candidate_particle_idx1: Indices of particles that should be brought into contact. :type candidate_particle_idx1: int :param candidate_particle_idx2: Indices of particles that should be brought into contact. :type candidate_particle_idx2: int :param k_repulsion: Repulsion spring constant. :type k_repulsion: float :param k_gamma: Gamma constraint spring constant. :type k_gamma: float :param gamma_tolerance: Allowed fractional deviation from gamma_pc (default 5%). :type gamma_tolerance: float :param max_iters: Maximum relaxation iterations. :type max_iters: int :param tol_overlap: Overlap convergence tolerance. :type tol_overlap: float :param learning_rate: Gradient descent step size. :type learning_rate: float :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.