jaxdem.utils.randomSphereConfiguration#

Generates a random, energy-minimized configurations of spheres in 2D or 3D.

Functions

minimize_sphere_configuration(...[, ...])

Minimize a user-supplied sphere configuration at a target packing fraction.

random_sphere_configuration(particle_radii, ...)

Generate one or more random sphere packings at a target packing fraction.
jaxdem.utils.randomSphereConfiguration.random_sphere_configuration(particle_radii: Sequence[float] | Sequence[Sequence[float]], phi: float | Sequence[float], dim: int, seed: int | None = None, collider_type: str = 'naive', box_aspect: Sequence[float] | Sequence[Sequence[float]] | None = None, max_avg_pe: float | None = 1e-16, domain_type: str = 'periodic') → tuple[Array, Array][source]#

Generate one or more random sphere packings at a target packing fraction.

This builds periodic systems with spherical particles, initializes particle positions uniformly at random inside a rectangular periodic box, and then minimizes the potential energy to obtain a mechanically stable configuration.

The function supports batching over multiple independent “systems” by treating the leading axis as the system index and broadcasting any length-1 inputs to match the maximum number of systems inferred from the inputs.

Parameters:

  • particle_radii –

    Particle radii for one system or multiple systems.

    • Single system: a 1D sequence of length N (radii for each particle).

    • Multiple systems: a 2D sequence with shape (S, N) (one radii list per system).

    Internally, this is converted to a JAX array with shape (S, N).

  • phi –

    Target packing fraction(s).

    • Scalar: a single float applied to all systems.

    • Per-system: a 1D sequence of length S.

    Internally, this is converted to a JAX array with shape (S, 1) and then broadcast/padded to match the inferred number of systems.

  • dim – Spatial dimension (e.g. 2 or 3).

  • seed –

    RNG seed used to initialize particle positions. If None, a random seed is drawn via NumPy.

    Note: a single JAX PRNGKey is used to generate the full position array of shape (S, N, dim).

  • collider_type – Collision detection backend. Must be one of "naive" or "celllist".

  • box_aspect –

    Box aspect ratios for the periodic domain.

    • If None, defaults to jnp.ones(dim).

    • Otherwise must be a 1D sequence of length dim.

    Internally broadcast/padded to shape (S, dim).

    (Even though the type annotation allows a sequence-of-sequences, the current implementation asserts len(box_aspect) == dim before broadcasting, so per-system (S, dim) input is not accepted here.)

  • max_avg_pe – Maximum potential energy per particle allowed in the configuration. The minimizer will attempt to adjust the sphere positions until this is met. If far above the jamming density, the minimizer will likely run for the maximum number of steps, and may take unnecessarily long to terminate.

Returns:

  • pos – Particle positions after minimization.

    • If S > 1: shape (S, N, dim).

    • If S == 1: shape (N, dim) due to squeeze().

  • box_size – Periodic box size vectors.

    • If S > 1: shape (S, dim).

    • If S == 1: shape (dim,) due to squeeze().

Notes

  • Broadcasting rule: any input provided for a single system (leading dimension 1) is replicated to match the maximum S inferred from particle_radii, phi, and box_aspect.

  • The final squeeze() calls can also drop other singleton dimensions (e.g. if N == 1). If you need stable rank/shape, remove the squeezes.

jaxdem.utils.randomSphereConfiguration.minimize_sphere_configuration(particle_radii: Sequence[float] | Sequence[Sequence[float]] | Array, pos: Sequence[Sequence[float]] | Sequence[Sequence[Sequence[float]]] | Array, phi: float | Sequence[float] | Array, dim: int, collider_type: str = 'naive', box_aspect: Sequence[float] | Sequence[Sequence[float]] | None = None, max_avg_pe: float | None = 1e-16, domain_type: str = 'periodic') → tuple[Array, Array][source]#

Minimize a user-supplied sphere configuration at a target packing fraction.

Builds a periodic box whose volume is sum(particle_volume) / phi (with the requested aspect ratio), places the particles at pos in that box, and FIRE-minimizes the potential energy.

Parameters:

  • particle_radii –

    Particle radii for one or multiple systems.

    • Single system: 1D sequence of length N.

    • Multiple systems: 2D sequence of shape (S, N).

  • pos – Particle centers in absolute coordinates (same frame as the final box anchored at the origin). Shape (N, dim) or (S, N, dim). Positions outside the computed box are wrapped by the periodic domain during minimization.

  • phi – Target packing fraction. Scalar or 1D sequence of length S.

  • dim – Spatial dimension (2 or 3).

  • collider_type – Collision-detection backend, "naive" or "celllist".

  • box_aspect – Aspect ratios of the periodic box. None defaults to jnp.ones(dim). Shape (dim,); broadcast to (S, dim).

  • max_avg_pe – Convergence tolerance used for both pe_tol and pe_diff_tol.

  • domain_type – Boundary condition for the analogue sphere system. Must be a registered Domain type (e.g. "periodic" or "reflect"). Default "periodic".

Returns:

  • pos – Minimized particle positions (shape (S, N, dim), squeezed if S == 1).

  • box_size – Periodic box size vector(s) (shape (S, dim), squeezed if S == 1).