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 anhpmc.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 oftune_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 toupdate()
rescales the current value of the tunable(s) by the ratio of the observed acceptance rate to the target value. Forgamma > 0
, the scale factor is the reciprocal of a weighted mean of the above ratio with 1, according toscale = (1.0 + gamma) / (target/acceptance + gamma)The names in
tunables
must match one of the keys intunable_map
, which in turn correspond to the keyword parameters of the MC object being updated.tunable_map
is adict
ofdict
. The keys of the outerdict
are strings that can be specified in thetunables
parameter. The value of this outerdict
is anotherdict
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 thecallable
for ‘set’ to callhoomd.hpmc.integrate.mode_hpmc.set_params()
withtunable={type: newval}
instead oftunable=newval
if thetype
argument is given when creating thetune
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
usingtune
.This is a thin wrapper to
tune
that simply defines an alternativetunable_map
dictionary. In this case, theobj
argument must be an instance ofhoomd.hpmc.update.boxmc
. Several tunables are defined.‘dLx’, ‘dLy’, and ‘dLz’ use the acceptance rate of volume moves to set
delta[0]
,delta[1]
, anddelta[2]
, respectively in a call tohoomd.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]
, anddelta[2]
, respectively in a call tohoomd.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 ofboxmc
.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.
-