University of Michigan Logo
hoomd_script Namespace Reference

Base module for the user-level scripting API. More...

Namespaces

 analyze
 Commands that analyze the system and provide some output.
 
 angle
 Commands that specify angle forces.
 
 benchmark
 Commands for benchmarking the performance of HOOMD.
 
 bond
 Commands that specify bond forces.
 
 charge
 Commands that create forces between pairs of particles.
 
 cite
 Commands to support automatic citation generation.
 
 comm
 Commands to support MPI communication.
 
 compute
 Commands that compute properties of the system.
 
 constrain
 Commands that create constraint forces on particles.
 
 context
 Gather information about the execution context.
 
 data
 Access particles, bonds, and other state information inside scripts.
 
 dihedral
 Commands that specify dihedral forces.
 
 dump
 Commands that dump particles to files.
 
 external
 Commands that create external forces on particles.
 
 force
 Other types of forces.
 
 globals
 Global variables.
 
 group
 Commands for grouping particles.
 
 improper
 Commands that specify improper forces.
 
 init
 Data initialization commands.
 
 integrate
 Commands that integrate the equations of motion.
 
 meta
 Write out simulation and environment context metadata.
 
 nlist
 Wrapper for "global" nlist commands.
 
 option
 Commands set global options.
 
 pair
 Commands that create forces between pairs of particles.
 
 sorter
 Wrapper for "global" sorter commands.
 
 tune
 Commands for tuning the performance of HOOMD.
 
 update
 Commands that modify the system state in some way.
 
 variant
 Commands for specifying values that vary over time.
 
 wall
 Commands that specify wall forces.
 

Functions

def get_hoomd_script_version
 Get the version information of hoomd_script. More...
 
def run
 Runs the simulation for a given number of time steps. More...
 
def run_upto
 Runs the simulation up to a given time step number. More...
 
def get_step
 Get the current simulation time step. More...
 
def cuda_profile_start
 Start CUDA profiling. More...
 
def cuda_profile_stop
 Stop CUDA profiling. More...
 

Detailed Description

Base module for the user-level scripting API.

hoomd_script provides a very high level user interface for executing simulations using HOOMD. This python module is designed to be imported into python with "from hoomd_script import *"

Function Documentation

def hoomd_script.cuda_profile_start ( )

Start CUDA profiling.

When using nvvp to profile CUDA kernels in hoomd jobs, you usually don't care about all the initialization and startup. cuda_profile_start() allows you to not even record that. To use, uncheck the box "start profiling on application start" in your nvvp session configuration. Then, call cuda_profile_start() in your hoomd script when you want nvvp to start collecting information.

Example:

1 from hoomd_script import *
2 init.read_xml("init.xml");
3 # setup....
4 run(30000); # warm up and auto-tune kernel block sizes
5 option.set_autotuner_params(enable=False); # prevent block sizes from further autotuning
6 cuda_profile_start();
7 run(100);
def hoomd_script.cuda_profile_stop ( )

Stop CUDA profiling.

See also
cuda_profile_start();
def hoomd_script.get_hoomd_script_version ( )

Get the version information of hoomd_script.

Returns
a tuple (major, minor)

This version is the version number of hoomd_script , not HOOMD as a whole. It is intended for use by third party API plugins that interface with hoomd_script. When new features are added (i.e. a new command or a new option to an existing command), the minor version will be incremented. When major changes are implemented or changes that break backwards compatibility are made, then the major version is incremented and the minor reset to 0. Only one such increment of either type will occur per each tagged release of HOOMD.

def hoomd_script.get_step ( )

Get the current simulation time step.

Returns
current simulation time step
def hoomd_script.run (   tsteps,
  profile = False,
  limit_hours = None,
  limit_multiple = 1,
  callback_period = 0,
  callback = None,
  quiet = False 
)

Runs the simulation for a given number of time steps.

Parameters
tstepsNumber of time steps to advance the simulation
profileSet to True to enable detailed profiling
limit_hours(if set) Limit the run to a given number of hours.
limit_multipleWhen stopping the run() due to walltime limits, only stop when the time step is a multiple of limit_multiple .
callback(if set) Sets a Python function to be called regularly during a run.
callback_periodSets the period, in time steps, between calls made to callback
quietSet to True to eliminate the status information printed to the screen by the run

Examples:

1 run(1000)
2 run(10e6, limit_multiple=100000)
3 run(10000, profile=True)
4 run(1e9, limit_hours=11)
5 
6 def py_cb(cur_tstep):
7  print "callback called at step: ", str(cur_tstep)
8 
9 run(10000, callback_period=100, callback=py_cb)

Overview

Execute the run() command to advance the simulation forward in time. During the run, all previously specified analyzers, dumps, updaters and the integrators are executed at the specified regular periods.

After run() completes, you may change parameters of the simulation and continue the simulation by executing run() again. Time steps are added cumulatively, so calling run(1000) and then run(2000) would run the simulation up to time step 3000.

run() cannot be executed before the system is initialized. In most cases, run() should only be called after after pair forces, bond forces, and an integrator are specified.

When profile is True, a detailed breakdown of how much time was spent in each portion of the calculation is printed at the end of the run. Collecting this timing information can slow the simulation significantly.

Wallclock limited runs

There are a number of mechanisms to limit the time of a running hoomd script. Use these in a job queuing environment to allow your script to cleanly exit before reaching the system enforced walltime limit.

Force run() to end only on time steps that are a multiple of limit_mulitple. Set this to the period at which you dump restart files so that you always end a run() cleanly at a point where you can restart from. Use phase=0 on logs, file dumps, and other periodic tasks. With phase=0, these tasks will continue on the same sequence regardless of the restart period.

Set the environment variable HOOMD_WALLTIME_STOP prior to executing hoomd to stop the run() at a given wall clock time. run() monitors performance and tries to ensure that it will end before HOOMD_WALLTIME_STOP. This environment variable works even with multiple stages of runs in a script (use run_upto()). Set the variable to a unix epoch time. For example in a job script that should run 12 hours, set HOOMD_WALLTIME_STOP to 12 hours from now, minus 10 minutes to allow for job cleanup.

1 export HOOMD_WALLTIME_STOP=$((`date +%s` + 12 * 3600 - 10 * 60))

When using HOOMD_WALLTIME_STOP, run() will throw the exception WalltimeLimitReached if it exits due to the walltime limit. For more information on using this exception, see (TODO: page to be written).#

limit_hours is another way to limit the length of a run(). Set it to a number of hours (use fractional values for minutes) to limit this particular run() to that length of time. This is less useful than HOOMD_WALLTIME_STOP in a job queuing environment.

Callbacks

If callback is set to a Python function then this function will be called regularly at callback_period intervals. The callback function must receive one integer as argument and can return an integer. The argument passed to the callback is the current time step number. If the callback function returns a negative number, the run is immediately aborted.

If callback_period is set to 0 (the default) then the callback is only called once at the end of the run. Otherwise the callback is executed whenever the current time step number is a multiple of callback_period.

def hoomd_script.run_upto (   step,
  keywords 
)

Runs the simulation up to a given time step number.

Parameters
stepFinal time step of the simulation which to run
keywords(see below) Catch for all keyword arguments to pass on to run()

run_upto() runs the simulation, but only until it reaches the given time step, step. If the simulation has already reached the specified step, a message is printed and no simulation steps are run.

It accepts all keyword options that run() does.

Examples:

1 run_upto(1000)
2 run_upto(10000, profile=True)
3 run_upto(1e9, limit_hours=11)