hoomd.hpmc.tune¶
Overview
Tunes |
|
Tunes HPMCIntegrator move sizes to targeted acceptance rate. |
Details
Tuners for HPMC.
- class hoomd.hpmc.tune.BoxMCMoveSize(trigger, *args, **kwargs)¶
Tunes
BoxMC
move sizes to targeted acceptance rate.Tip
For most common creation of a
BoxMCMoveSize
tuner seeBoxMCMoveSize.secant_solver
andBoxMCMoveSize.scale_solver
respectively.The tuner will continue tuning despite being
tuned
. Thus, if simulation conditions change the move sizes will continue to change and the tuner will no longer betuned
. The changes to the move size are completely controlled by the givenhoomd.tune.RootSolver
instance. See the doumentation athoomd.tune
for more information.Warning
The tuner should be removed from the simulation once tuned to prevent invalid results due to the breaking of balance.
- Parameters:
trigger (hoomd.trigger.trigger_like) –
Trigger
to determine when to run the tuner.boxmc (hoomd.hpmc.update.BoxMC) – The
hoomd.hpmc.update.BoxMC
object to tune.moves (list[str]) – A list of types of moves to tune. Available options are ‘volume’, ‘aspect’, ‘shear_{x,y,z}’, and ‘length_{x,y,z}’ where brackets denote multiple options. For shear and length moves each dimension is tuned independently.
target (float) – The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
solver (
hoomd.tune.RootSolver
) – A solver that tunes move sizes to reach the specified target.max_move_size (
dict
[str
,float
], optional) – The maximum volume move size to attempt for each move time. See the available moves in themoves
attribute documentation. Defaults to no maximumNone
for each move type.
- trigger¶
Trigger
to determine when to run the tuner.- Type:
- boxmc¶
The
hoomd.hpmc.update.BoxMC
object to tune.- Type:
- moves¶
A list of types of moves to tune. Available options are ‘volume’, ‘aspect’, ‘shear_{x,y,z}’, and ‘length_{x,y,z}’ where brackets denote multiple options. For shear and length moves each dimension is tuned independently.
- target¶
The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
- Type:
- solver¶
A solver that tunes move sizes to reach the specified target.
- Type:
- max_move_size¶
The maximum volume move size to attempt for each move time. See the available moves in the
moves
attribute documentation.- Type:
Warning
Over-limiting the maximum move sizes can lead to the inability to converge to the desired acceptance rate.
Warning
Since each dimension of length and shear moves are tuned independently but the acceptance statistics are collected collectively, the reachable target acceptance rates is limited by the other dimensions.
- classmethod scale_solver(trigger, boxmc, moves, target, max_move_size=None, max_scale=2.0, gamma=1.0, tol=0.01)¶
Create a
BoxMCMoveSize
tuner with ahoomd.tune.ScaleSolver
.- Parameters:
trigger (hoomd.trigger.trigger_like) –
Trigger
to determine when to run the tuner.boxmc (hoomd.hpmc.update.BoxMC) – The
hoomd.hpmc.update.BoxMC
object to tune.moves (list[str]) – A list of types of moves to tune. Available options are ‘volume’, ‘aspect’, ‘shear_{x,y,z}’, and ‘length_{x,y,z}’ where brackets denote multiple options. For shear and length moves each dimension is tuned independently.
target (float) – The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
max_move_size (float) – The maximum value of a volume move size to attempt.
max_scale (float) – Maximum scale factor.
gamma (float) – The value of gamma to pass through to
hoomd.tune.ScaleSolver
. Controls the size of corrections to the move size (larger values increase stability while increasing convergence time).tol (float) – The absolute tolerance to allow between the current acceptance rate and the target before the move sizes are considered tuned. The tolerance should not be too much lower than the default of 0.01 as acceptance rates can vary significantly at typical tuning rates.
- classmethod secant_solver(trigger, boxmc, moves, target, max_move_size=None, gamma=0.8, tol=0.01)¶
Create a
BoxMCMoveSize
tuner with ahoomd.tune.SecantSolver
.This solver can be faster than
hoomd.tune.ScaleSolver
, but depending on the system slightly less stable. In general, with the default value of gamma this should not be a problem.- Parameters:
trigger (hoomd.trigger.trigger_like) –
Trigger
to determine when to run the tuner.boxmc (hoomd.hpmc.update.BoxMC) – The
hoomd.hpmc.update.BoxMC
object to tune.moves (list[str]) – A list of types of moves to tune. Available options are ‘volume’, ‘aspect’, ‘shear_{x,y,z}’, and ‘length_{x,y,z}’ where brackets denote multiple options. For shear and length moves each dimension is tuned independently.
target (float) – The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
max_move_size (float) – The maximum value of a volume move size to attempt, defaults to
None
which represents no maximum move size.gamma (float) – The value of gamma to pass through to
hoomd.tune.SecantSolver
. Controls the size of corrections to the move size (smaller values increase stability). Should be between 0 and 1, defaults to 0.8.tol (float) – The absolute tolerance to allow between the current acceptance rate and the target before the move sizes are considered tuned. The tolerance should not be too much lower than the default of 0.01 as acceptance rates can vary significantly at typical tuning rates.
Note
Increasing
gamma
towards 1 does not necessarily speed up convergence and can slow it down. In addition, large values ofgamma
can make the solver unstable, especially when tuning frequently.
- class hoomd.hpmc.tune.MoveSize(trigger, *args, **kwargs)¶
Tunes HPMCIntegrator move sizes to targeted acceptance rate.
Tip
Direct instantiation of this class requires a
hoomd.tune.RootSolver
that determines how move sizes are updated. This class also provides class methods to create aMoveSize
tuner with built-in solvers; seeMoveSize.secant_solver
andMoveSize.scale_solver
.- Parameters:
trigger (hoomd.trigger.trigger_like) –
Trigger
to determine when to run the tuner.moves (list[str]) – A list of types of moves to tune. Available options are
'a'
and'd'
.target (float) – The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
solver (
hoomd.tune.RootSolver
) – A solver that tunes move sizes to reach the specified target.types (list[str]) – A list of string particle types to tune the move size for, defaults to None which upon attaching will tune all types in the system currently.
max_translation_move (float) – The maximum value of a translational move size to attempt \([\mathrm{length}]\).
max_rotation_move (float) – The maximum value of a rotational move size to attempt.
- trigger¶
Trigger
to determine when to run the tuner.- Type:
- target¶
The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
- Type:
- solver¶
A solver that tunes move sizes to reach the specified target.
- Type:
- types¶
A list of string particle types to tune the move size for, defaults to None which upon attaching will tune all types in the system currently.
- max_translation_move¶
The maximum value of a translational move size to attempt \([\mathrm{length}]\).
- Type:
Note
Limiting the maximum move sizes can lead to the inability to converge to the desired acceptance rate. Also, not limiting the move size can lead to move sizes that require the use of multiple periodic images to check for overlaps, especially in low density systems since the acceptance rate tends towards 1. Therefore, it is recommended to pick a moderate maximum move size for at least the translational moves to prevent requiring checking periodic images.
Note
In systems containing disparate particle shapes and/or sizes, move sizes for the different types should be tuned independently so that the acceptances rates for the different particles are each near the target acceptance ratio. Otherwise, the global acceptance ratio, a weighted average of the acceptance ratios for each individual particle type, will approach the target value, while the per-type acceptance ratios may not be close to the target value. This requires setting the
types
attribute to be one type at a time while setting theignore_statistics
flag of the shape property of the HPMC integrator for all other types toTrue
.- classmethod scale_solver(trigger, moves, target, types=None, max_translation_move=None, max_rotation_move=None, max_scale=2.0, gamma=1.0, tol=0.01)¶
Create a
MoveSize
tuner with ahoomd.tune.ScaleSolver
.- Parameters:
trigger (hoomd.trigger.trigger_like) –
Trigger
to determine when to run the tuner.moves (list[str]) – A list of types of moves to tune. Available options are
'a'
and'd'
.target (float) – The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
types (list[str]) – A list of string particle types to tune the move size for, defaults to None which upon attaching will tune all types in the system currently.
max_translation_move (float) – The maximum value of a translational move size to attempt \([\mathrm{length}]\).
max_rotation_move (float) – The maximum value of a rotational move size to attempt.
max_scale (float) – Maximum scale factor.
gamma (float) – The value of gamma to pass through to
hoomd.tune.ScaleSolver
. Controls the size of corrections to the move size (larger values increase stability while increasing convergence time).tol (float) – The absolute tolerance to allow between the current acceptance rate and the target before the move sizes are considered tuned. The tolerance should not be too much lower than the default of 0.01 as acceptance rates can vary significantly at typical tuning rates.
- classmethod secant_solver(trigger, moves, target, types=None, max_translation_move=None, max_rotation_move=None, gamma=0.8, tol=0.01)¶
Create a
MoveSize
tuner with ahoomd.tune.SecantSolver
.This solver can be faster than
hoomd.tune.ScaleSolver
, but depending on the system slightly less stable. In general, with the default value of gamma this should not be a problem.- Parameters:
trigger (hoomd.trigger.trigger_like) –
Trigger
to determine when to run the tuner.moves (list[str]) – A list of types of moves to tune. Available options are
'a'
and'd'
.target (float) – The acceptance rate for trial moves that is desired. The value should be between 0 and 1.
types (list[str]) – A list of string particle types to tune the move size for, defaults to None which upon attaching will tune all types in the system currently.
max_translation_move (float) – The maximum value of a translational move size to attempt, defaults to
None
which represents no maximum move size \([\mathrm{length}]\).max_rotation_move (float) – The maximum value of a rotational move size to attempt, defaults to
None
which represents no maximum move size.gamma (float) – The value of gamma to pass through to
hoomd.tune.SecantSolver
. Controls the size of corrections to the move size (smaller values increase stability). Should be between 0 and 1, defaults to 0.8.tol (float) – The absolute tolerance to allow between the current acceptance rate and the target before the move sizes are considered tuned. The tolerance should not be too much lower than the default of 0.01 as acceptance rates can vary significantly at typical tuning rates.
Note
Increasing
gamma
towards 1 does not necessarily speed up convergence and can slow it down. In addition, large values ofgamma
can make the solver unstable, especially when tuning frequently.