hoomd.tune¶
Overview
Tuner wrapper for 

Adjusts the boundaries of the domain decomposition. 

Class for defining y = f(x) relationships for tuning x for a set y target. 

Order particles in memory to improve performance. 

Solves equations of f(x) = y using a ratio of the current y with the target. 

Solves equations of f(x) = y using the secant method. 

Abstract base class for “solving” stepwise equations of f(x) = y. 
Details

class
hoomd.tune.
ManualTuneDefinition
(get_y, target, get_x, set_x, domain=None)¶ Class for defining y = f(x) relationships for tuning x for a set y target.
This class is made to be used with
SolverStep
subclasses. Here y represents a dependent variable of x. In general, x and y should be of typefloat
, but specificSolverStep
subclasses may accept other types.A special case for the return type of y is
None
. If the value is currently inaccessible or would be invalid, aManualTuneDefinition
object can return a y ofNone
to indicate this.SolverStep
objects will handle this automatically. Since we check forNone
internally inSolverStep
objects, aManualTuneDefinition
object’sy
property should be consistant when called multiple times within a timestep. Parameters
get_y (
callable
) – A callable that gets the current value for y.target (
any
) – The target y value to approach.get_x (
callable
) – A callable that gets the current value for x.set_x (
callable
) – A callable that sets the current value for x.domain (
tuple
[any
,any
], optional) – A tuple pair of the minimum and maximum accepted values of x, defaults toNone
. When, the domain isNone
then any value of x is accepted. Either the minimum or maximum can be set toNone
as well which means there is no maximum or minimum. The domain is used to wrap values within the specified domain when setting x.
Note
Placing domain restrictions on x can lead to the target y value being impossible to converge to. This will lead to the
SolverStep
object passed this tunable to never finish solving regardless if all otherManualTuneDefinition
objects are converged.
clamp_into_domain
(value)¶ Return the closest value within the domain.
 Parameters
value (
any
) – A value of the same type as x. Returns
The value clamps within the domains of x. Clamping here refers to returning the value or minimum or maximum of the domain if value is outside the domain.

property
domain
¶ A tuple pair of the minimum and maximum accepted values of x.
When, the domain is
None
then any value of x is accepted. Either the minimum or maximum can be set toNone
as well which means there is no maximum or minimum. The domain is used to wrap values within the specified domain when setting x. Type
tuple[
any
,any
]

in_domain
(value)¶ Check whether a value is in the domain.
 Parameters
value (
any
) – A value that can be compared to the minimum and maximum of the domain. Returns
Whether the value is in the domain of x.
 Return type

property
max_x
¶ Maximum allowed x value.

property
min_x
¶ Minimum allowed y value.

property
target
¶ The targetted y value, can be set.

property
x
¶ The dependent variable.
Can be set. When set the setting value is clamped within the provided domain. See
clamp_into_domain
for further explanation.

property
y
¶ The independent variable, and is unsettable.

class
hoomd.tune.
CustomTuner
(action, trigger=1)¶ Tuner wrapper for
hoomd.custom.Action
objects.For usage see
hoomd.custom.CustomOperation
.

class
hoomd.tune.
LoadBalancer
(trigger, x=True, y=True, z=True, tolerance=1.02, max_iterations=1)¶ Adjusts the boundaries of the domain decomposition.
 Parameters
trigger (hoomd.trigger.Trigger) – Select the timesteps on which to perform load balancing.
tolerance (
float
) – Load imbalance tolerance.max_iterations (
int
) – Maximum number of iterations to attempt in a single step.
LoadBalancer
adjusts the boundaries of the MPI domains 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 \(N_i\) is the number of particles on rank \(i\), \(N\) is the total number of particles, and \(P\) is the number of ranks.
In order to adjust the load imbalance,
LoadBalancer
scales by the inverse of the imbalance factor. To reduce oscillations and communication overhead, it does not move a domain more than 5% of its current size in a single rebalancing step, and not 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 \(I1.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 update. The load balancer can attempt multiple iterations of balancing on each update, and up to maxiter attempts can be made. The optimal values of update 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 vaporliquid interface normal to the \(z\) axis, then it may be advantageous to disable balancing along \(x\) and \(y\).
In systems that are wellbehaved, there is minimal overhead of balancing with a small update. However, if the system is not capable of being balanced (for example, due to the density distribution or minimum domain size), having a small update 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).

trigger
¶ Select the timesteps on which to perform load balancing.

class
hoomd.tune.
ParticleSorter
(trigger=200, grid=None)¶ Order particles in memory to improve performance.
 Parameters
trigger (hoomd.trigger.Trigger) – Select the timesteps on which to sort. Defaults to a
hoomd.trigger.Periodic(200)
trigger.grid (int) – Resolution of the grid to use when sorting. The default value of
None
setsgrid=4096
in 2D simulations andgrid=256
in 3D simulations.
ParticleSorter
improves simulation performance by sorting the particles in memory along a spacefilling curve. This takes particles that are close in space and places them close in memory, leading to a higher rate of cache hits when computing pair potentials.Note
New
Operations
instances include aParticleSorter
constructed with default parameters.
trigger
¶ Select the timesteps on which to sort.

class
hoomd.tune.
ScaleSolver
(max_scale=2.0, gamma=2.0, correlation='positive', tol=1e05)¶ Solves equations of f(x) = y using a ratio of the current y with the target.
 Parameters
max_scale (
float
, optional) – The maximum amount to scale the current x value with, defaults to 2.0.gamma (
float
, optional) – nonnegative real number used to dampen or increase the rate of change in x.gamma
is added to the numerator and denominator of they / target
ratio. Larger values ofgamma
lead to smaller changes while agamma
of 0 leads to scaling x by exactly they / target
ratio.correlation (
str
, optional) – Defines whether the relationship between x and y is of a positive or negative correlation, defaults to ‘positive’. This determines which direction to scale x in for a given y.tol (
float
, optional) – The absolute tolerance for convergence of y, defaults to 1e5.
Note
This solver is only usable when quantities are strictly positive.

solve_one
(tunable)¶ Takes in a tunable object and attempts to solve x for a specified y.
 Parameters
tunable (
hoomd.tune.ManualTuneDefinition
) – A tunable object that represents a relationship of f(x) = y. Returns
Whether or not the tunable converged to the target.
 Return type

class
hoomd.tune.
SecantSolver
(gamma=0.9, tol=1e05)¶ Solves equations of f(x) = y using the secant method.
 Parameters
gamma (
float
, optional) – real number between 0 and 1 used to dampen the rate of change in x.gamma
scales the corrections to x each iteration. Larger values ofgamma
lead to larger changes while agamma
of 0 leads to no change in x at all.tol (
float
, optional) – The absolute tolerance for convergence of y, defaults to 1e5.
Note
Tempering the solver with a smaller than 1
gamma
value is crucial for numeric stability. If instability is found, then loweringgamma
accordingly should help.
solve_one
(tunable)¶ Takes in a tunable object and attempts to solve x for a specified y.
 Parameters
tunable (
hoomd.tune.ManualTuneDefinition
) – A tunable object that represents a relationship of f(x) = y. Returns
Whether or not the tunable converged to the target.
 Return type

class
hoomd.tune.
SolverStep
¶ Abstract base class for “solving” stepwise equations of f(x) = y.
Requires a single method
SolverStep.solve_one
that steps forward one iteration in solving the given variable relationship. Users can use subclasses of this withhoomd.tune.ManualTuneDefinition
to tune attributes with a functional relation.Note
A
SolverStep
object requires manual iteration to converge. This is to support the use case of measuring quantities that require running the simulation for some amount of time after one iteration before remeasuring the dependent variable (i.e. the y).SolverStep
object can be used inhoomd.custom.Action
subclasses for user defined tuners and updaters.
solve
(tunables)¶ Iterates towards a solution for a list of tunables.
If a y for one of the
tunables
isNone
then we skip thattunable
. Skipping implies that the quantity is not tuned andsolve
will returnFalse
. Parameters
tunables (list[
hoomd.tune.ManualTuneDefinition
]) – A list of tunable objects that represent a relationship f(x) = y. Returns
Returns whether or not all tunables were considered tuned by the object.
 Return type

abstract
solve_one
(tunable)¶ Takes in a tunable object and attempts to solve x for a specified y.
 Parameters
tunable (
hoomd.tune.ManualTuneDefinition
) – A tunable object that represents a relationship of f(x) = y. Returns
Whether or not the tunable converged to the target.
 Return type
