hpmc.compute

Overview

FreeVolume

Compute the free volume available to a test particle.

SDF

Compute the scale distribution function.

Details

Compute properties of hard particle configurations.

class hoomd.hpmc.compute.FreeVolume(test_particle_type, num_samples)

Compute the free volume available to a test particle.

Parameters
  • test_particle_type (str) – Test particle type.

  • num_samples (int) – Number of samples to evaluate.

FreeVolume computes the free volume in the simulation state available to a given test particle using Monte Carlo integration. It must be used in combination with an HPMC integrator, which defines the particle shape parameters.

FreeVolume generates num_samples uniform random test particle placements (position and orientation) inside the box and counts the number of times these test placements overlap with the particles in the simulation state. It then computes the free volume with:

\[V_\mathrm{free} = \left( \frac{n_\mathrm{samples} - n_\mathrm{overlaps}} {n_\mathrm{samples}} \right) V_\mathrm{box}\]

where \(V_\mathrm{free}\) is the estimated free volume free_volume, \(n_\mathrm{samples}\) is the number of samples num_samples, \(n_\mathrm{overlaps}\) is the number of overlapping test placements, and \(V_\mathrm{box}\) is the volume of the simulation box.

Note

The test particle type must exist in the simulation state and its shape parameters must be set in the simulation’s HPMC integrator. Particles with this type may or may not be present in the simulation state.

Note

FreeVolume respects the interaction_matrix set in the HPMC integrator.

Examples:

fv = hoomd.hpmc.compute.FreeVolume(test_particle_type='B',
                                   num_samples=1000)
test_particle_type

Test particle type.

Type

str

num_samples

Number of samples to evaluate.

Type

int

property free_volume

Free volume available to the test particle \([\mathrm{length}^{2}]\) in 2D and \([\mathrm{length}^{3}]\) in 3D.

(Loggable: category=”scalar”)

class hoomd.hpmc.compute.SDF(xmax, dx)

Compute the scale distribution function.

Parameters
  • xmax (float) – Maximum x value at the right hand side of the rightmost bin \([\mathrm{length}]\).

  • dx (float) – Bin width \([\mathrm{length}]\).

SDF computes a distribution function of parameter \(x\). For each pair of particles, it scales the particle separation vector by \(1+x\) and records the smallest \(x\) that would cause the particles to touch in the histogram \(s(x)\). The histogram is discrete and \(s(x_i) = s[i]\) where \(x_i = i \cdot dx + dx/2\).

The extrapolation of \(s(x)\) to \(x = 0\), \(s(0+)\) is related to the pressure

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

where \(d\) is the dimensionality of the system, \(\rho\) is the number density, and \(\beta = \frac{1}{kT}\). This measurement of the pressure is inherently noisy due to the nature of the sampling. Average betaP over many timesteps to obtain accurate results.

Assuming particle diameters are ~1, these paramater values typically achieve good results:

  • xmax = 0.02

  • dx = 1e-4

In systems near densest packings, dx=1e-5 may be needed along with smaller xmax. Check that \(\sum_i s(x_i) \cdot dx \approx 0.5\).

Warning

SDF does not compute correct pressures for simulations with concave particles or enthalpic interactions.

Note

SDF runs on the CPU even in GPU simulations.

xmax

Maximum x value at the right hand side of the rightmost bin \([\mathrm{length}]\).

Type

float

dx

Bin width \([\mathrm{length}]\).

Type

float

property betaP

Beta times pressure in NVT simulations \(\left[ \mathrm{length}^{-d} \right]\).

Use a polynomial curve fit of degree 5 to estimate \(s(0+)\) and compute the pressure via:

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

where \(d\) is the dimensionality of the system, \(\rho\) is the number density, and \(\beta = \frac{1}{kT}\).

Attention

In MPI parallel execution, betaP is available on rank 0 only. betaP is None on ranks >= 1.

(Loggable: category=”scalar”)

Type

float

property sdf

\(s[i]\) - The scale distribution function \([\mathrm{probability\ density}]\).

Attention

In MPI parallel execution, the array is available on rank 0 only. sdf is None on ranks >= 1.

(Loggable: category=”sequence”)

Type

(N_bins,) numpy.ndarray of float)