Generate loose packings of spheres in orthorhombic domains, in 2 and 3 dimensions.

• Fill a domain with spheres from a given distribution of radii to reach a target packing fraction, or from already-sampled radii.
• Control minimum allowed distance between spheres.
• Decide whether spheres can cross through domain boundaries or not.

BubbleBath.jl just employs the trivial brute-force method, with the only peculiarity that spheres are introduced in order of decreasing radius. Dense packings are obtained with reasonable performance, but spatial correlations between sphere sizes are introduced.

This is not an algorithm to generate tight, space-filling packings.

The package exports a Sphere{D} type, which is just a wrapper around a position pos::NTuple{D,Float64} and a radius radius::Float64, and the bubblebath function, which creates a loose packing of spheres in a domain.

To generate a (2D) distribution of spheres with radii uniformly distributed within 1 and 5, in a rectangular domain of edges 100 and 50, with a packing fraction 0.4, we can do

using BubbleBath
using Distributions: Uniform

radius_pdf = Uniform(1,5)
extent = (100, 50)
ϕ_max = 0.4
bath = bubblebath(radius_pdf, ϕ_max, extent)

If we want to impose a minimal distance between the surface of spheres, the min_distance keyword can be used

radius_pdf = Uniform(1,5)
extent = (100, 50)
ϕ_max = 0.4
min_distance = 2.0
bath = bubblebath(radius_pdf, ϕ_max, extent; min_distance)

Again, the procedure in 3D is identical

radius_pdf = Uniform(10,25)
extent = (100, 100, 100)
ϕ_max = 0.3
min_distance = 10.0
bath = bubblebath(radius_pdf, ϕ_max, extent; min_distance)

We can verify that the generated radii closely match the chosen distribution, even at relatively high packing fractions.

using Distributions: Exponential
θ = 3.0 # average radius
radius_pdf = Exponential(θ)
extent = ntuple(_->300, 3)
bath1 = bubblebath(radius_pdf, 0.3, extent)
# this can take a while
bath2 = bubblebath(radius_pdf, 0.6, extent)
r1 = map(s -> s.radius, bath1)
r2 = map(s -> s.radius, bath2)

Finally, bubblebath also has an in-place version bubblebath!, which can operate on pre-initialised vectors of Spheres. For example, to produce the BubbleBath.jl logo:

using Distributions: Exponential
# initialise vector with three spheres at desired locations
Lx = 400
Ly = 400
extent = (Lx,Ly)
R = 50
D = 60
spheres = [
    Sphere((Lx/2-D,Ly/2-D), R),
    Sphere((Lx/2+D,Ly/2-D), R),
    Sphere((Lx/2,Ly/2+3D/4), R)
]
# add new spheres with exponential distribution of radii
radius_pdf = Exponential(2.0)
ϕ_max = 0.25 - packing_fraction(spheres, extent)
min_distance = 2.0
bubblebath!(spheres, radius_pdf, ϕ_max, extent; min_distance)