openmc.model.pack_spheres(radius, region, pf=None, num_spheres=None, initial_pf=0.3, contraction_rate=0.001, seed=None)[source]

Generate a random, non-overlapping configuration of spheres within a container.

  • radius (float) – Outer radius of spheres.

  • region (openmc.Region) – Container in which the spheres are packed. Supported shapes are rectangular prism, cylinder, sphere, and spherical shell.

  • pf (float) – Packing fraction of the spheres. One of ‘pf’ and ‘num_spheres’ must be specified; the other will be calculated. If both are specified, ‘pf’ takes precedence over ‘num_spheres’.

  • num_spheres (int) – Number of spheres to pack in the domain. One of ‘num_spheres’ and ‘pf’ must be specified; the other will be calculated.

  • initial_pf (float, optional) – Packing fraction used to initialize the configuration of spheres in the domain. Default value is 0.3. It is not recommended to set the initial packing fraction much higher than 0.3 as the random sequential packing algorithm becomes prohibitively slow as it approaches its limit (~0.38).

  • contraction_rate (float, optional) – Contraction rate of the outer diameter. Higher packing fractions can be reached using a smaller contraction rate, but the algorithm will take longer to converge.

  • seed (int, optional) – Pseudorandom number generator seed passed to random.seed()


Cartesian coordinates of sphere centers.

Return type



The sphere configuration is generated using a combination of random sequential packing (RSP) and close random packing (CRP). RSP performs better than CRP for lower packing fractions (pf), but it becomes prohibitively slow as it approaches its packing limit (~0.38). CRP can achieve higher pf of up to ~0.64 and scales better with increasing pf.

If the desired pf is below some threshold for which RSP will be faster than CRP (‘initial_packing_fraction’), only RSP is used. If a higher pf is required, spheres with a radius smaller than the desired final radius (and therefore with a smaller pf) are initialized within the domain using RSP. This initial configuration of spheres is then used as a starting point for CRP using Jodrey and Tory’s algorithm 1.

In RSP, sphere centers are placed one by one at random, and placement attempts for a sphere are made until the sphere is not overlapping any others. This implementation of the algorithm uses a mesh over the domain to speed up the nearest neighbor search by only searching for a sphere’s neighbors within that mesh cell.

In CRP, each sphere is assigned two diameters, an inner and an outer, which approach each other during the simulation. The inner diameter, defined as the minimum center-to-center distance, is the true diameter of the spheres and defines the pf. At each iteration the worst overlap between spheres based on outer diameter is eliminated by moving the spheres apart along the line joining their centers. Iterations continue until the two diameters converge or until the desired pf is reached.



W. S. Jodrey and E. M. Tory, “Computer simulation of close random packing of equal spheres”, Phys. Rev. A 32 (1985) 2347-2351.