Compute properties of hard particle configurations.

class hoomd.hpmc.analyze.sdf(mc, filename, xmax, dx, navg, period, overwrite=False, phase=0)

Compute the scale distribution function.

  • mc (hoomd.hpmc.integrate) – MC integrator.
  • filename (str) – Output file name.
  • xmax (float) – Maximum x value at the right hand side of the rightmost bin (distance units).
  • dx (float) – Bin width (distance units).
  • navg (int) – Number of times to average before writing the histogram to the file.
  • period (int) – Number of timesteps between histogram evaluations.
  • overwrite (bool) – Set to True to overwrite filename instead of appending to it.
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.

sdf computes a distribution function of scale parameters \(x\). For each particle, it finds the smallest scale factor \(1+x\) that would cause the particle to touch one of its neighbors and records that in the histogram \(s(x)\). The histogram is discrete and \(s(x_i) = s[i]\) where \(x_i = i \cdot dx + dx/2\).

In an NVT simulation, the extrapolation of \(s(x)\) to \(x = 0\), \(s(0+)\) is related to the pressure.

\[\frac{P}{kT} = \rho \left(1 + \frac{s(0+)}{2d} \right)\]

where \(d\) is the dimensionality of the system and \(\rho\) is the number density.

Extrapolating \(s(0+)\) is not trivial. Here are some suggested parameters, but they may not work in all cases.

  • xmax = 0.02
  • dx = 1e-4
  • Polynomial curve fit of degree 5.

In systems near densest packings, dx=1e-5 may be needed along with either a smaller xmax or a smaller region to fit. A good rule of thumb might be to fit a region where numpy.sum(s[0:n]*dx) ~ 0.5 - but this needs further testing to confirm.

sdf averages navg histograms together before writing them out to a text file in a plain format: “timestep bin_0 bin_1 bin_2 …. bin_n”.

sdf works well with restartable jobs. Ensure that navg*period is an integer fraction \(1/k\) of the restart period. Then sdf will have written the final output to its file just before the restart gets written. The new data needed for the next line of values is entirely collected after the restart.


sdf does not compute correct pressures for simulations with concave particles.

Numpy extrapolation code:

def extrapolate(s, dx, xmax, degree=5):
  # determine the number of values to fit
  n_fit = int(math.ceil(xmax/dx));
  s_fit = s[0:n_fit];
  # construct the x coordinates
  x_fit = numpy.arange(0,xmax,dx)
  x_fit += dx/2;
  # perform the fit and extrapolation
  p = numpy.polyfit(x_fit, s_fit, degree);
  return numpy.polyval(p, 0.0);


mc = hpmc.integrate.sphere(seed=415236)
analyze.sdf(mc=mc, filename='sdf.dat', xmax=0.02, dx=1e-4, navg=100, period=100)
analyze.sdf(mc=mc, filename='sdf.dat', xmax=0.002, dx=1e-5, navg=100, period=100)

Disable the analyzer.



Executing the disable command will remove the analyzer from the system. Any hoomd.run() command executed after disabling an analyzer will not use that analyzer during the simulation. A disabled analyzer can be re-enabled with enable().


Enables the analyzer



See disable().


Restore the state information from the file used to initialize the simulations


Changes the period between analyzer executions

Parameters:period (int) – New period to set (in time steps)



While the simulation is running (hoomd.run(), the action of each analyzer is executed every period time steps. Changing the period does not change the phase set when the analyzer was first created.