hoomd.update

Overview

hoomd.update.balance Adjusts the boundaries of a domain decomposition on a regular 3D grid.
hoomd.update.box_resize Rescale the system box size.
hoomd.update.sort Sorts particles in memory to improve cache coherency.

Details

Modify the system state periodically.

When an updater is specified, it acts on the particle system every period steps to change it in some way. See the documentation of specific updaters to find out what they do.

class hoomd.update.balance(x=True, y=True, z=True, tolerance=1.02, maxiter=1, period=1000, phase=0)

Adjusts the boundaries of a domain decomposition on a regular 3D grid.

Parameters:
  • x (bool) – If True, balance in x dimension.
  • y (bool) – If True, balance in y dimension.
  • z (bool) – If True, balance in z dimension.
  • tolerance (float) – Load imbalance tolerance (if <= 1.0, balance every step).
  • maxiter (int) – Maximum number of iterations to attempt in a single step.
  • period (int) – Balancing will be attempted every a period time steps
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.

Every period steps, the boundaries of the processor domains are adjusted to distribute the particle load close to evenly between them. The load imbalance is defined as the number of particles owned by a rank divided by the average number of particles per rank if the particles had a uniform distribution:

\[I = \frac{N(i)}{N / P}\]

where :math:` N(i) ` is the number of particles on processor \(i\), \(N\) is the total number of particles, and \(P\) is the number of ranks.

In order to adjust the load imbalance, the sizes are rescaled by the inverse of the imbalance factor. To reduce oscillations and communication overhead, a domain cannot move more than 5% of its current size in a single rebalancing step, and the edge of a domain cannot move more than half the distance to its neighbors.

Simulations with interfaces (so that there is a particle density gradient) or clustering should benefit from load balancing. The potential speedup is roughly \(I-1.0\), so that if the largest imbalance is 1.4, then the user can expect a roughly 40% speedup in the simulation. This is of course an estimate that assumes that all algorithms are roughly linear in \(N\), all GPUs are fully occupied, and the simulation is limited by the speed of the slowest processor. It also assumes that all particles roughly equal. If you have a simulation where, for example, some particles have significantly more pair force neighbors than others, this estimate of the load imbalance may not produce the optimal results.

A load balancing adjustment is only performed when the maximum load imbalance exceeds a tolerance. The ideal load balance is 1.0, so setting tolerance less than 1.0 will force an adjustment every period. The load balancer can attempt multiple iterations of balancing every period, and up to maxiter attempts can be made. The optimal values of period and maxiter will depend on your simulation.

Load balancing can be performed independently and sequentially for each dimension of the simulation box. A small performance increase may be obtained by disabling load balancing along dimensions that are known to be homogeneous. For example, if there is a planar vapor-liquid interface normal to the \(z\) axis, then it may be advantageous to disable balancing along \(x\) and \(y\).

In systems that are well-behaved, there is minimal overhead of balancing with a small period. However, if the system is not capable of being balanced (for example, due to the density distribution or minimum domain size), having a small period and high maxiter may lead to a large performance loss. In such systems, it is currently best to either balance infrequently or to balance once in a short test run and then set the decomposition statically in a separate initialization.

Balancing is ignored if there is no domain decomposition available (MPI is not built or is running on a single rank).

disable()

Disables the updater.

Examples:

updater.disable()

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

enable()

Enables the updater.

Examples:

updater.enable()

See also

disable()

restore_state()

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

set_params(x=None, y=None, z=None, tolerance=None, maxiter=None)

Change load balancing parameters.

Parameters:
  • x (bool) – If True, balance in x dimension.
  • y (bool) – If True, balance in y dimension.
  • z (bool) – If True, balance in z dimension.
  • tolerance (float) – Load imbalance tolerance (if <= 1.0, balance every step).
  • maxiter (int) – Maximum number of iterations to attempt in a single step.

Examples:

balance.set_params(x=True, y=False)
balance.set_params(tolerance=0.02, maxiter=5)
set_period(period)

Changes the updater period.

Parameters:period (int) – New period to set.

Examples:

updater.set_period(100);
updater.set_period(1);

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

class hoomd.update.box_resize(Lx=None, Ly=None, Lz=None, xy=None, xz=None, yz=None, period=1, L=None, phase=0, scale_particles=True)

Rescale the system box size.

Parameters:
  • L (hoomd.variant) – (if set) box length in the x,y, and z directions as a function of time (in distance units)
  • Lx (hoomd.variant) – (if set) box length in the x direction as a function of time (in distance units)
  • Ly (hoomd.variant) – (if set) box length in the y direction as a function of time (in distance units)
  • Lz (hoomd.variant) – (if set) box length in the z direction as a function of time (in distance units)
  • xy (hoomd.variant) – (if set) X-Y tilt factor as a function of time (dimensionless)
  • xz (hoomd.variant) – (if set) X-Z tilt factor as a function of time (dimensionless)
  • yz (hoomd.variant) – (if set) Y-Z tilt factor as a function of time (dimensionless)
  • period (int) – The box size will be updated every period time steps.
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.
  • scale_particles (bool) – When True (the default), scale particles into the new box. When False, do not change particle positions when changing the box.

Every period time steps, the system box dimensions is updated to values given by the user (in a variant). As an option, the particles can either be left in place as the box is changed or their positions can be scaled with the box.

Note

If period is set to None, then the given box lengths are applied immediately and periodic updates are not performed.

L, Lx, Ly, Lz, xy, xz, yz can either be set to a constant number or a hoomd.variant. if any of the box parameters are not specified, they are set to maintain the same value in the current box.

Use L as a shorthand to specify Lx, Ly, and Lz to the same value.

By default, particle positions are rescaled with the box. Set scale_particles=False to leave particles in place when changing the box.

If, under rescaling, tilt factors get too large, the simulation may slow down due to too many ghost atoms being communicated. hoomd.update.box_resize does NOT reset the box to orthorhombic shape if this occurs (and does not move the next periodic image into the primary cell).

Examples:

update.box_resize(L = hoomd.variant.linear_interp([(0, 20), (1e6, 50)]))
box_resize = update.box_resize(L = hoomd.variant.linear_interp([(0, 20), (1e6, 50)]), period = 10)
update.box_resize(Lx = hoomd.variant.linear_interp([(0, 20), (1e6, 50)]),
                  Ly = hoomd.variant.linear_interp([(0, 20), (1e6, 60)]),
                  Lz = hoomd.variant.linear_interp([(0, 10), (1e6, 80)]))
update.box_resize(Lx = hoomd.variant.linear_interp([(0, 20), (1e6, 50)]), Ly = 10, Lz = 10)

# Shear the box in the xy plane using Lees-Edwards boundary conditions
update.box_resize(xy = hoomd.variant.linear_interp([(0,0), (1e6, 1)]))
disable()

Disables the updater.

Examples:

updater.disable()

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

enable()

Enables the updater.

Examples:

updater.enable()

See also

disable()

restore_state()

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

set_period(period)

Changes the updater period.

Parameters:period (int) – New period to set.

Examples:

updater.set_period(100);
updater.set_period(1);

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

class hoomd.update.sort

Sorts particles in memory to improve cache coherency.

Warning

Do not specify hoomd.update.sort explicitly in your script. HOOMD creates a sorter by default.

Every period time steps, particles are reordered in memory based on a Hilbert curve. This operation is very efficient, and the reordered particles significantly improve performance of all other algorithmic steps in HOOMD.

The reordering is accomplished by placing particles in spatial bins. A Hilbert curve is generated that traverses these bins and particles are reordered in memory in the same order in which they fall on the curve. The grid dimension used over the course of the simulation is held constant, and the default is chosen to be as fine as possible without utilizing too much memory. The grid size can be changed with set_params().

Warning

Memory usage by the sorter grows quickly with the grid size:

  • grid=128 uses 8 MB
  • grid=256 uses 64 MB
  • grid=512 uses 512 MB
  • grid=1024 uses 4096 MB

Note

2D simulations do not use any additional memory and default to grid=4096.

A sorter is created by default. To disable it or modify parameters, save the context and access the sorter through it:

c = context.initialize();
hoomd.init.create_random(N=1000, phi_p=0.2)
# the sorter is only available after initialization
c.sorter.disable()
disable()

Disables the updater.

Examples:

updater.disable()

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

enable()

Enables the updater.

Examples:

updater.enable()

See also

disable()

restore_state()

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

set_params(grid=None)

Change sorter parameters.

Parameters:grid (int) – New grid dimension (if set)
Examples::
sorter.set_params(grid=128)
set_period(period)

Changes the updater period.

Parameters:period (int) – New period to set.

Examples:

updater.set_period(100);
updater.set_period(1);

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