NeighborListBuffer

class hoomd.md.tune.NeighborListBuffer(self, trigger: hoomd.trigger.Trigger, nlist: hoomd.md.nlist.NeighborList, solver: hoomd.tune.solve.Optimizer, maximum_buffer: float)

Optimize neighbor list buffer size for maximum TPS.

Tip

Direct instantiation of this class requires a hoomd.tune.Optimizer that determines how move sizes are updated. This class also provides class methods to create a NeighborListBuffer tuner with built-in solvers; see NeighborListBuffer.with_grid and NeighborListBuffer.with_gradient_descent.

Parameters:
trigger

Trigger to determine when to run the tuner.

Type:

hoomd.trigger.Trigger

solver

A solver that tunes the neighbor list buffer to maximize TPS.

Type:

hoomd.tune.solve.Optimizer

maximum_buffer

The largest buffer value to allow.

Type:

float

minimum_buffer

The smallest buffer value to allow.

Type:

float

Warning

When using with a hoomd.device.GPU device, kernel launch parameter autotuning can prevent convergence. Run the simulation for 25,000 steps before adding the tuner to allow the autotuning to converge first results in better TPS optimization.

Note

NeighborListBuffer.with_grid generally performs better than NeighborListBuffer.with_gradient_descent due to the stocastic nature of TPS.

property best_buffer_size

The buffer size corresponding to max_tps during tuning.

(Loggable: category=”scalar”)

Type:

float

property final_bin

Boundaries of grid search optimization.

Property is only available when a hoomd.tune.GridOptimizer is used, and tuning is finished. Otherwise, the property is None.

Type:

tuple[float, float]

property last_tps

The last TPS computed for the tuner.

(Loggable: category=”scalar”)

Type:

int

property max_tps

The maximum recorded TPS during tuning.

(Loggable: category=”scalar”)

Type:

int

property tuned

Whether the neighbor list buffer is considered tuned.

The tuner is considered tune when the specified solver returns True when solving twice consecutively. See hoomd.tune for more information on tuning criteria.

Type:

bool

classmethod with_gradient_descent(trigger: Trigger | int, nlist: NeighborList, maximum_buffer: float, minimum_buffer: float = 0.0, alpha: Variant | float = hoomd._hoomd.VariantRamp, kappa: ndarray | None = (0.33, 0.165), tol: float = 1e-05, max_delta: float | None = None)

Create a NeighborListBuffer with a gradient descent solver.

See hoomd.tune.solve.GradientDescent for more information on the solver.

Parameters:

  • trigger (hoomd.trigger.trigger_like) – Trigger to determine when to run the tuner.

  • nlist (hoomd.md.nlist.NeighborList) – Neighbor list buffer to maximize TPS.

  • maximum_buffer (float) – The largest buffer value to allow.

  • minimum_buffer (float, optional) – The smallest buffer value to allow (defaults to 0).

  • alpha (hoomd.variant.variant_like, optional) – Number between 0 and 1 or variant used to dampen the rate of change in x (defaults to hoomd.variant.Ramp(1e-5, 1e-6, 0, 30)). alpha scales the corrections to x each iteration. Larger values of alpha lead to larger changes while a alpha of 0 leads to no change in x at all.

  • kappa (numpy.ndarray of float, optional) – A NumPy array of floats which are weight applied to the last NN of the gradients to add to the current gradient as well, where NN is the size of the array (defaults to (0.33, 0.165)).

  • tol (float, optional) – The absolute tolerance for convergence of y (defaults to 1e-5).

  • max_delta (float, optional) – The maximum iteration step allowed (defaults to None which does not limit step size).

Note

Given the stocasticity of TPS, a non none kappa is recommended.

Tip

For better convergence choose an alpha in the range of 0.01 divided by the expected order of magnitude of the TPS. The default value assumes a TPS in the thousands.

Tip

When using the hoomd.tune.solve.GradientDescent, optimization is improved by starting at lower buffer values, as this has the steepest gradient.

classmethod with_grid(trigger: Trigger | int, nlist: NeighborList, maximum_buffer: float, minimum_buffer: float = 0.0, n_bins: int = 5, n_rounds: int = 1)

Create a NeighborListBuffer with a hoomd.tune.GridOptimizer.

Parameters:

  • trigger (hoomd.trigger.trigger_like) – Trigger to determine when to run the tuner.

  • nlist (hoomd.md.nlist.NeighborList) – Neighbor list buffer to maximize TPS.

  • maximum_buffer (float) – The largest buffer value to allow.

  • minimum_buffer (float, optional) – The smallest buffer value to allow (defaults to 0).

  • n_bins (int, optional) – The number of bins in the range to test (defaults to 5).

  • n_rounds (int, optional) – The number of rounds to perform the optimization over (defaults to 1).

Note

Using this method adds another attribue final_bin which gives the final bin boundaries after tuning for n_rounds.