jaxdem.utils.packingUtils#

Utility functions for calculating and changing the packing fraction.

Functions

compute_packing_fraction(state, system)

compute_particle_volume(state)

Return the total particle volume.

quasistatic_compress_to_packing_fraction(...)

Quasi-statically compress (or decompress) toward target_phi.

scale_to_packing_fraction(state, system, ...)

jaxdem.utils.packingUtils.compute_particle_volume(state: State) → jax.Array[source]#

Return the total particle volume.

jaxdem.utils.packingUtils.compute_packing_fraction(state: State, system: System) → jax.Array[source]#
jaxdem.utils.packingUtils.scale_to_packing_fraction(state: State, system: System, new_packing_fraction: float) → tuple[State, System][source]#
jaxdem.utils.packingUtils.quasistatic_compress_to_packing_fraction(state: State, system: System, target_phi: float, *, step: float = 0.001, phi_tolerance: float = 1e-10, pe_tol: float = 1e-16, pe_diff_tol: float = 1e-16, max_n_min_steps_per_outer: int = 1000000, max_n_outer_steps: int = 1000000, progress: bool = False) → tuple[State, System, jax.Array, jax.Array][source]#

Quasi-statically compress (or decompress) toward target_phi.

Alternates scale_to_packing_fraction() with minimize() in steps no larger than step in packing fraction. The final step is truncated so the target is hit exactly (within phi_tolerance). Works in both directions: if target_phi > current_phi the box shrinks and particles are pushed closer; if target_phi < current_phi the box grows and the system relaxes.

The state is minimized once up front, so a non-equilibrium input is safe. Above the jamming point the minimizer may exit with residual PE — the final PE is returned so the caller can detect this.

Parameters:

  • state – Current state/system; any domain type that scale_to_packing_fraction() supports is allowed.

  • system – Current state/system; any domain type that scale_to_packing_fraction() supports is allowed.

  • target_phi – Target packing fraction.

  • step – Maximum magnitude of the per-outer-step increment in phi. Smaller values are more quasistatic (costlier); 1e-3 is a reasonable default for dense compressions.

  • phi_tolerance – Absolute tolerance on the terminal packing fraction.

  • pe_tol – Minimizer convergence tolerances.

  • pe_diff_tol – Minimizer convergence tolerances.

  • max_n_min_steps_per_outer – FIRE iterations allowed per minimization (per outer step).

  • max_n_outer_steps – Hard cap on outer iterations (safety net).

  • progress – If True and tqdm is importable, wraps the outer loop in a progress bar. Otherwise silent.

Returns:

final_phi is compute_packing_fraction(state, system) at exit; final_pe is the PE after the last minimization.

Return type:

state, system, final_phi, final_pe