jaxdem.utils.randomSphereConfiguration#

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='naive', box_aspect: Sequence[float] | Sequence[Sequence[float]] | None = None) → 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.)

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.