Simulation¶

class hoomd.Simulation(device, seed=None)¶

Define a simulation.

Parameters:

device (hoomd.device.Device) – Device to execute the simulation.
seed (int) – Random number seed.

Simulation is the central class that defines a simulation, including the state of the system, the operations that apply to the state during a simulation run, and the device to use when executing the simulation.

seed sets the seed for the random number generator used by all operations added to this Simulation.

Newly initialized Simulation objects have no state. Call create_state_from_gsd or create_state_from_snapshot to initialize the simulation’s state.

Example:

simulation = hoomd.Simulation(device=hoomd.device.CPU(), seed=1)

__del__()¶: Clean up dangling references to simulation.

property always_compute_pressure¶

Always compute the virial and pressure (defaults to False).

By default, HOOMD only computes the virial and pressure on timesteps where it is needed (when hoomd.write.GSD writes log data to a file or when using an NPT integrator). Set always_compute_pressure to True to make the per particle virial, net virial, and system pressure available to query any time by property or through the hoomd.logging.Logger interface.

Note

Enabling this flag will result in a moderate performance penalty when using MD pair potentials.

Example:

simulation.always_compute_pressure = True

Type:: bool

create_state_from_gsd(filename, frame=-1, domain_decomposition=(None, None, None))¶

Create the simulation state from a GSD file.

Parameters:

filename (str) – GSD file to read
frame (int) – Index of the frame to read from the file. Negative values index back from the last frame in the file.
domain_decomposition (tuple) – Choose how to distribute the state across MPI ranks with domain decomposition. Provide a tuple of 3 integers indicating the number of evenly spaced domains in the x, y, and z directions (e.g. (8,4,2)). Provide a tuple of 3 lists of floats to set the fraction of the simulation box to include in each domain. The sum of each list of floats must be 1.0 (e.g. ([0.25, 0.75], [0.2, 0.8], [1.0])).

When timestep is None before calling, create_state_from_gsd sets timestep to the value in the selected GSD frame in the file.

Note

Set any or all of the domain_decomposition tuple elements to None and create_state_from_gsd will select a value that minimizes the surface area between the domains (e.g. (2,None,None)). The domains are spaced evenly along each automatically selected direction. The default value of (None, None, None) will automatically select the number of domains in all directions.

Example:

simulation.create_state_from_gsd(filename=gsd_filename)

create_state_from_snapshot(snapshot, domain_decomposition=(None, None, None))¶

Create the simulation state from a Snapshot.

Parameters:

snapshot (Snapshot or gsd.hoomd.Frame) – Snapshot to initialize the state from. A gsd.hoomd.Frame will first be converted to a hoomd.Snapshot.
domain_decomposition (tuple) – Choose how to distribute the state across MPI ranks with domain decomposition. Provide a tuple of 3 integers indicating the number of evenly spaced domains in the x, y, and z directions (e.g. (8,4,2)). Provide a tuple of 3 lists of floats to set the fraction of the simulation box to include in each domain. The sum of each list of floats must be 1.0 (e.g. ([0.25, 0.75], [0.2, 0.8], [1.0])).

When timestep is None before calling, create_state_from_snapshot sets timestep to 0.

Note

Set any or all of the domain_decomposition tuple elements to None and create_state_from_snapshot will select a value that minimizes the surface area between the domains (e.g. (2,None,None)). The domains are spaced evenly along each automatically selected direction. The default value of (None, None, None) will automatically select the number of domains in all directions.

See also

run

Type:: hoomd.Operations

run(steps, write_at_start=False)¶

Advance the simulation a number of steps.

Parameters:

steps (int) – Number of steps to advance the simulation.
write_at_start (bool) – When True, writers with triggers that evaluate True for the initial step will be executed before the time step loop.

Note

Initialize the simulation’s state before calling run.

Simulation applies its operations to the state during each time step in the order: tuners, updaters, integrator, then writers following the logic in this pseudocode:

if write_at_start:
    for writer in operations.writers:
        if writer.trigger(timestep):
            writer.write(timestep)

end_step = timestep + steps
while timestep < end_step:
    for tuner in operations.tuners:
        if tuner.trigger(timestep):
            tuner.tune(timestep)

    for updater in operations.updaters:
        if updater.trigger(timestep):
            updater.update(timestep)

    if operations.integrator is not None:
        operations.integrator(timestep)

    timestep += 1

    for writer in operations.writers:
        if writer.trigger(timestep):
            writer.write(timestep)

This order of operations ensures that writers (such as hoomd.write.GSD) capture the final output of the last step of the run loop. For example, a writer with a trigger hoomd.trigger.Periodic(period=100, phase=0) active during a run(500) would write on steps 100, 200, 300, 400, and 500. Set write_at_start=True on the first call to run to also obtain output at step 0.

Warning

Using write_at_start=True in subsequent calls to run will result in duplicate output frames.

Example:

simulation.run(1_000)

property seed¶

Random number seed.

Seeds are in the range [0, 65535]. When set, seed will take only the lowest 16 bits of the given value.

HOOMD-blue uses a deterministic counter based pseudorandom number generator. Any time a random value is needed, HOOMD-blue computes it as a function of the user provided seed seed (16 bits), the current timestep (lower 40 bits), particle identifiers, MPI ranks, and other unique identifying values as needed to sample uncorrelated values: random_value = f(seed, timestep, ...)

Example:

simulation.seed = 2

(Loggable: category=”scalar”)

Type:: int

property state¶

The current simulation state.

Type:: hoomd.State

property timestep¶

The current simulation time step.

timestep is read only after creating the simulation state.

Note

Methods like create_state_from_gsd will set the initial timestep from the input. Set timestep before creating the simulation state to override values from create_ methods:

sim.timestep = 5000
sim.create_state_from_gsd("gsd_at_step_10000000.gsd")
assert sim.timestep == 5000

(Loggable: category=”scalar”)

Type:: int

property tps¶

The average number of time steps per second.

tps is the number of steps executed divided by the elapsed walltime in seconds. It is updated during the run loop and remains fixed after run completes.

Warning

The elapsed walltime and timestep are reset at the beginning of each call to run. Thus, tps will provide noisy estimates of performance at the start and stable long term averages after many timesteps.

Tip

Use the total elapsed wall time and timestep to average the timesteps executed per second at desired intervals.

Example:

logger.add(obj=simulation, quantities=["tps"])

(Loggable: category=”scalar”)

Type:: float

property walltime¶

The walltime spent during the last call to run.

walltime is the number seconds that the last call to run took to complete. It is updated during the run loop and remains fixed after run completes.

Note

walltime resets to 0 at the beginning of each call to run.