jaxdem.utils.randomSphereConfiguration#

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

Functions

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) → Tuple[Array, Array][source][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.