hoomd_script Namespace Reference

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

Packages
namespace	analyze
	Commands that analyze the system and provide some output.
namespace	angle
	Commands that specify angle forces.
namespace	benchmark
	Commands for benchmarking the performance of HOOMD.
namespace	bond
	Commands that specify bond forces.
namespace	charge
	Commands that create forces between pairs of particles.
namespace	compute
	Commands that compute properties of the system.
namespace	constrain
	Commands that create constraint forces on particles.
namespace	data
	Access particles, bonds, and other state information inside scripts.
namespace	dihedral
	Commands that specify dihedral forces.
namespace	dump
	Commands that dump particles to files.
namespace	external
	Commands that create external forces on particles.
namespace	force
	Other types of forces.
namespace	globals
	Global variables.
namespace	group
	Commands for grouping particles.
namespace	improper
	Commands that specify improper forces.
namespace	init
	Data initialization commands.
namespace	integrate
	Commands that integrate the equations of motion.
namespace	option
	Commands set global options.
namespace	pair
	Commands that create forces between pairs of particles.
namespace	tune
	Commands for tuning the performance of HOOMD.
namespace	update
	Commands that modify the system state in some way.
namespace	variant
	Commands for specifying values that vary over time.
namespace	wall
	Commands that specify wall forces.
Functions
def	get_hoomd_script_version
	Get the version information of hoomd_script.
def	run
	Runs the simulation for a given number of time steps.
def	run_upto
	Runs the simulation up to a given time step number.

---

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.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.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:

tsteps	Number of time steps to advance the simulation by
profile	Set to True to enable detailed profiling
limit_hours	(if set) Limit the run to a given number of hours.
limit_multiple	Only allow the limit_hours setting to stop the simulation 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_period	Sets the period, in time steps, between calls made to callback
quiet	Set to True to eliminate the status information printed to the screen by the run

Examples:

 run(1000)
 run(10e6)
 run(10000, profile=True)
 run(1e9, limit_hours=11)

 def py_cb(cur_tstep):
     print "callback called at step: ", str(cur_tstep)

 run(10000, callback_period=100, callback=py_cb)

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 (i.e. temperature) 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, it also doesn't make sense to execute run() until after pair forces, bond forces, and an integrator have been created.

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 on the GPU significantly; so only enable profiling for testing and troubleshooting purposes.

If limit_hours is changed from the default of None, the run will continue until either the specified number of time steps has been reached, or the given number of hours has elapsed. This option can be useful in shared machines where the queuing system limits job run times. A fractional value can be given to limit a run to only a few minutes, if needed.

When running restartable jobs, it may be advantageous to enforce that run() ends on a time step that is a multiple of some value. For example, when dumping dcd trajectories with a period of 200,000 you may want to ensure that a job always ends on a multiple of 200,000 so that when the next run begins, dump.dcd can continue writing right where it left off instead of at some random time (e.g. 234,187) that just happened to be when the time limit was reached in the previous run. Set this multiple with the limit_multiple argument. Keep in mind that a large multiple may require a long buffer time between limit_hours and the job wall clock limit as submitted to the queue.

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 is the current time step number, and if the callback function returns a negative number then the run is immediately aborted. All other return values are currently ignored.

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:

step	Final 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 warning is printed and no simulation steps are run.

It accepts all keyword options that run() does.

Examples:

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