jaxdem.utils.packing_utils#

Utility functions for calculating and changing the packing fraction.

Functions

compute_packing_fraction(state, system)

Return the packing fraction total_particle_volume / box_volume.

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, ...)

Rescale the box to new_packing_fraction, preserving its aspect ratio.

Classes

CompressionReason(*values)

Why quasistatic compression stopped.

CompressionResult(state, system, ...)

Compression output; four-value unpacking remains supported.
jaxdem.utils.packing_utils.compute_particle_volume(state: State) → jax.Array[source]#

Return the total particle volume.

jaxdem.utils.packing_utils.compute_packing_fraction(state: State, system: System) → jax.Array[source]#

Return the packing fraction total_particle_volume / box_volume.

The box volume is prod(system.domain.box_size), independent of its anchor.

jaxdem.utils.packing_utils.scale_to_packing_fraction(state: State, system: System, new_packing_fraction: float) → tuple[State, System][source]#

Rescale the box to new_packing_fraction, preserving its aspect ratio.

class jaxdem.utils.packing_utils.CompressionReason(*values)[source]#

Bases: IntEnum

Why quasistatic compression stopped.

MAX_STEPS = 0#
TARGET_REACHED = 1#
MINIMIZATION_FAILED = 2#
class jaxdem.utils.packing_utils.CompressionResult(state: State, system: System, packing_fraction: jax.Array, energy: jax.Array, steps: int, reason: CompressionReason, minimizer_reason: TerminationReason)#

Bases: object

Compression output; four-value unpacking remains supported.

minimizer_reason distinguishes exhaustion, nonfinite values, and search overflow when reason is MINIMIZATION_FAILED. If the first relaxation fails, no accepted energy exists and energy is NaN.

state: State#
system: System#
packing_fraction: jax.Array#
energy: jax.Array#
steps: int#
reason: CompressionReason#
minimizer_reason: TerminationReason#
jaxdem.utils.packing_utils.quasistatic_compress_to_packing_fraction(state: State, system: System, target_phi: float, *, step: float = 0.001, phi_tolerance: float = 1e-10, force_tol: float = 1e-12, torque_tol: float | None = None, max_n_min_steps_per_outer: int = 1000000, max_n_outer_steps: int = 1000000, progress: bool = False) → CompressionResult[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 the particles move closer. If target_phi < current_phi the box grows and the system relaxes.

The function minimizes the state once up front and after each change of packing fraction. The returned potential energy can remain positive at mechanical equilibrium above jamming.

Parameters:

  • state – Current state/system. Any domain type that scale_to_packing_fraction supports works.

  • system – Current state/system. Any domain type that scale_to_packing_fraction supports works.

  • target_phi – Target packing fraction.

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

  • phi_tolerance – Absolute tolerance on the terminal packing fraction.

  • force_tol – Absolute force and torque tolerances for mechanical relaxation.

  • torque_tol – Absolute force and torque tolerances for mechanical relaxation.

  • 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, wrap the outer loop in a progress bar. Otherwise silent.

Returns:

Inspect reason and minimizer_reason before accepting a packing. Failure returns the last accepted state/system. Four-value unpacking remains available. final_phi is compute_packing_fraction(state, system) at exit. final_pe is the PE after the last minimization.

Return type:

CompressionResult