jaxdem.utils.random_sphere_configuration#

Generate random, energy-minimized sphere configurations 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.random_sphere_configuration.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, force_tol: float = 1e-12, domain_type: str = 'periodic') → tuple[Array, Array][source]#

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

The function builds systems of spherical particles, draws particle positions uniformly at random inside a rectangular box, and then minimizes the potential energy to get a mechanically stable configuration.

The function supports batching over multiple independent “systems”. It treats the leading axis as the system index and broadcasts 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).

    The function converts this 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.

    The function converts this to a JAX array with shape (S, 1) and then broadcasts/pads it 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: the function uses a single JAX PRNGKey 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.

    The function broadcasts/pads this 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.)

  • force_tol – Absolute tolerance on the maximum free-sphere force norm.

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

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.

Raises:

RuntimeError – If any sphere system fails mechanical relaxation.

jaxdem.utils.random_sphere_configuration.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, force_tol: float = 1e-12, domain_type: str = 'periodic') → tuple[Array, Array][source]#

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

The function builds a 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). A periodic domain wraps positions outside the computed box 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).

  • force_tol – Absolute tolerance on the maximum free-sphere force norm.

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

Raises:

RuntimeError – If any sphere system fails mechanical relaxation.