hoomd.tune
Overview
Userdefined tuner. 

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 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
Tuners.
Tuner
operations make changes to the parameters of other operations (or the
simulation state) that adjust the performance of the simulation without changing
the correctness of the outcome. Every new hoomd.Simulation
object includes a
ParticleSorter
in its operations by default. ParticleSorter
rearranges the
order of particles in memory to improve cachecoherency.
This package also defines the CustomTuner
class and a number of helper
classes. Use these to implement custom tuner operations in Python code.
 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.When setting
x
the value is clamped between the given domain via,\[\begin{split}x &= x_{max}, \text{ if } x_n > x_{max},\\ x &= x_{min}, \text{ if } x_n < x_{min},\\ x &= x_n, \text{ otherwise}\end{split}\] 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. __eq__(other)
Test for equality.
 __hash__()
Compute a hash of the tune definition.
 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, any value of x is accepted. Either the minimum or maximum can be set to
None
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(trigger, action)
Bases:
CustomOperation
,Tuner
Userdefined tuner.
 Parameters
action (hoomd.custom.Action) – The action to call.
trigger (hoomd.trigger.Trigger) – Select the timesteps to call the action.
CustomTuner
is ahoomd.operation.Tuner
that wraps a userdefinedhoomd.custom.Action
object so the action can be added to ahoomd.Operations
instance for use withhoomd.Simulation
objects.Tuners modify the parameters of other operations to improve performance. Tuners may read the system state, but not modify it.
See also
The base class
hoomd.custom.CustomOperation
.
 class hoomd.tune.LoadBalancer(trigger, x=True, y=True, z=True, tolerance=1.02, max_iterations=1)
Bases:
Tuner
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 \(I1.0\), so that if the largest imbalance is 1.4, then the user can expect a 40% speedup in the simulation. This is of course an estimate that assumes that all algorithms are linear in \(N\), all GPUs are fully occupied, and the simulation is limited by the speed of the slowest processor. 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)
Bases:
Tuner
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
hoomd.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)
Bases:
SolverStep
Solves equations of f(x) = y using a ratio of y with the target.
Each time this solver is called it takes updates according to the following equation if the correlation is positive:
\[x_n = \min{\left(\frac{\gamma + t}{y + \gamma}, s_{max}\right)} \cdot x\]and
\[x_n = \min{\left(\frac{y + \gamma}{\gamma + t}, s_{max}\right)} \cdot x\]if the correlation is negative, where \(t\) is the target and \(x_n\) is the new x.
The solver will stop updating when \(\lvert y  t \rvert \le tol\).
 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.
 __eq__(other)
Test for equality.
 solve_one(tunable)
Solve one step.
 class hoomd.tune.SecantSolver(gamma=0.9, tol=1e05)
Bases:
SolverStep
Solves equations of f(x) = y using the secant method.
The solver updates
x
each step via,\[x_n = x  \gamma \cdot (y  t) \cdot \frac{x  x_{o}}{y  y_{old}}\]where \(o\) represent the old values, \(n\) the new, and \(t\) the target. Due to the need for a previous value, then first time this is called it makes a slight jump higher or lower to start the method.
The solver will stop updating when \(\lvert y  t \rvert \le tol\).
 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. __eq__(other)
Test for equality.
 solve_one(tunable)
Solve one step.
 class hoomd.tune.SolverStep
Bases:
object
Abstract base class for “solving” stepwise equations of f(x) = y.
Requires a single method
solve_one
that steps forward one iteration in solving the given variable relationship. Users can use subclasses of this withManualTuneDefinition
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