hpmc.util

Overview

hpmc.util.tune Tune mc parameters.
hpmc.util.tune_npt Tune the HPMC hoomd.hpmc.update.boxmc using tune.

Details

HPMC utilities

class hoomd.hpmc.util.tune(obj=None, tunables=[], max_val=[], target=0.2, max_scale=2.0, gamma=2.0, type=None, tunable_map=None, *args, **kwargs)

Tune mc parameters.

hoomd.hpmc.util.tune provides a general tool to observe Monte Carlo move acceptance rates and adjust the move sizes when called by a user script. By default, it understands how to read and adjust the trial move domain for translation moves and rotation moves for an hpmc.integrate instance. Other move types for integrators or updaters can be handled with a customized tunable map passed when creating the tuner or in a subclass definition. E.g. see use an implementation of tune_npt

Parameters:
  • obj – HPMC Integrator or Updater instance
  • tunables (list) – list of strings naming parameters to tune. By default, allowed element values are ‘d’ and ‘a’.
  • max_val (list) – maximum allowed values for corresponding tunables
  • target (float) – desired acceptance rate
  • max_scale (float) – maximum amount to scale a parameter in a single update
  • gamma (float) – damping factor (>= 0.0) to keep from scaling parameter values too fast
  • type (str) – Name of a single hoomd particle type for which to tune move sizes. If None (default), all types are tuned with the same statistics.
  • tunable_map (dict) – For each tunable, provide a dictionary of values and methods to be used by the tuner (see below)
  • args – Additional positional arguments
  • kwargs – Additional keyword arguments

Example:

mc = hpmc.integrate.convex_polyhedron()
mc.set_params(d=0.01, a=0.01, move_ratio=0.5)
tuner = hpmc.util.tune(mc, tunables=['d', 'a'], target=0.2, gamma=0.5)
for i in range(10):
    run(1e4)
    tuner.update()

Note

You should run enough steps to get good statistics for the acceptance ratios. 10,000 trial moves seems like a good number. E.g. for 10,000 or more particles, tuning after a single timestep should be fine. For npt moves made once per timestep, tuning as frequently as 1,000 timesteps could get a rough convergence of acceptance ratios, which is probably good enough since we don’t really know the optimal acceptance ratio, anyway.

Warning

There are some sanity checks that are not performed. For example, you shouldn’t try to scale ‘d’ in a single particle simulation.

Details:

If gamma == 0, each call to update() rescales the current value of the tunable(s) by the ratio of the observed acceptance rate to the target value. For gamma > 0, the scale factor is the reciprocal of a weighted mean of the above ratio with 1, according to

scale = (1.0 + gamma) / (target/acceptance + gamma)

The names in tunables must match one of the keys in tunable_map, which in turn correspond to the keyword parameters of the MC object being updated.

tunable_map is a dict of dict. The keys of the outer dict are strings that can be specified in the tunables parameter. The value of this outer dict is another dict with the following four keys: ‘get’, ‘acceptance’, ‘set’, and ‘maximum’.

A default tunable_map is provided but can be modified or extended by setting the following dictionary key/value pairs in the entry for tunable.

  • get (callable): function called by tuner (no arguments) to retrieve current tunable value
  • acceptance (callable): function called by tuner (no arguments) to get relevant acceptance rate
  • set (callable): function to call to set new value (optional). Must take one argument (the new value). If not provided, obj.set_params(tunable=x) will be called to set the new value.
  • maximum (float): maximum value the tuner may set for the tunable parameter

The default tunable_map defines the callable for ‘set’ to call hoomd.hpmc.integrate.mode_hpmc.set_params() with tunable={type: newval} instead of tunable=newval if the type argument is given when creating the tune object.

update()

Calculate and set tunable parameters using statistics from the run just completed.

class hoomd.hpmc.util.tune_npt(obj=None, tunables=[], max_val=[], target=0.2, max_scale=2.0, gamma=2.0, type=None, tunable_map=None, *args, **kwargs)

Tune the HPMC hoomd.hpmc.update.boxmc using tune.

This is a thin wrapper to tune that simply defines an alternative tunable_map dictionary. In this case, the obj argument must be an instance of hoomd.hpmc.update.boxmc. Several tunables are defined.

‘dLx’, ‘dLy’, and ‘dLz’ use the acceptance rate of volume moves to set delta[0], delta[1], and delta[2], respectively in a call to hoomd.hpmc.update.boxmc.length().

‘dV’ uses the volume acceptance to call hoomd.hpmc.update.boxmc.volume().

‘dlnV’ uses the ln_volume acceptance to call hoomd.hpmc.update.boxmc.ln_volume().

‘dxy’, ‘dxz’, and ‘dyz’ tunables use the shear acceptance to set delta[0], delta[1], and delta[2], respectively in a call to hoomd.hpmc.update.boxmc.shear().

Refer to the documentation for hoomd.hpmc.update.boxmc for information on how these parameters are used, since they are not all applicable for a given use of boxmc.

Note

A bigger damping factor gamma may be appropriate for tuning box volume changes because there may be multiple parameters affecting each acceptance rate.

Example:

mc = hpmc.integrate.convex_polyhedron()
mc.set_params(d=0.01, a=0.01, move_ratio=0.5)
updater = hpmc.update.boxmc(mc, betaP=10)
updater.length(0.1, weight=1)
tuner = hpmc.util.tune_npt(updater, tunables=['dLx', 'dLy', 'dLz'], target=0.3, gamma=1.0)
for i in range(10):
    run(1e4)
    tuner.update()
update()

Calculate and set tunable parameters using statistics from the run just completed.