hoomd.analyze

Overview

hoomd.analyze.callback Callback analyzer.
hoomd.analyze.imd Send simulation snapshots to VMD in real-time.
hoomd.analyze.log Log a number of calculated quantities to a file.

Details

Commands that analyze the system and provide some output.

An analyzer examines the system state in some way every period time steps and generates some form of output based on the analysis. Check the documentation for individual analyzers to see what they do.

class hoomd.analyze.callback(callback, period, phase=0)

Callback analyzer.

Parameters:
  • callback (callable) – The python callback object
  • period (int) – The callback is called every a period time steps
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.

Create an analyzer that runs a given python callback method at a defined period.

Examples:

def my_callback(timestep):
  print(timestep)

analyze.callback(callback = my_callback, period = 100)
disable()

Disable the analyzer.

Examples:

my_analyzer.disable()

Executing the disable command will remove the analyzer from the system. Any hoomd.run() command executed after disabling an analyzer will not use that analyzer during the simulation. A disabled analyzer can be re-enabled with enable().

enable()

Enables the analyzer

Examples:

my_analyzer.enable()

See disable().

restore_state()

Restore the state information from the file used to initialize the simulations

set_period(period)

Changes the period between analyzer executions

Parameters:period (int) – New period to set (in time steps)

Examples:

analyzer.set_period(100)
analyzer.set_period(1)

While the simulation is running (hoomd.run(), the action of each analyzer is executed every period time steps. Changing the period does not change the phase set when the analyzer was first created.

class hoomd.analyze.imd(port, period=1, rate=1, pause=False, force=None, force_scale=0.1, phase=0)

Send simulation snapshots to VMD in real-time.

Parameters:
  • port (int) – TCP/IP port to listen on.
  • period (int) – Number of time steps to run before checking for new IMD messages.
  • rate (int) – Number of periods between coordinate data transmissions.
  • pause (bool) – Set to True to pause the simulation at the first time step until an imd connection is made.
  • force (hoomd.md.force.constant) – A force that apply forces received from VMD.
  • force_scale (float) – Factor by which to scale all forces received from VMD.
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.

hoomd.analyze.imd listens on a specified TCP/IP port for connections from VMD. Once that connection is established, it begins transmitting simulation snapshots to VMD every rate time steps.

To connect to a simulation running on the local host, issue the command:

imd connect localhost 54321

in the VMD command window (where 54321 is replaced with the port number you specify for hoomd.analyze.imd.

Note

If a period larger than 1 is set, the actual rate at which time steps are transmitted is rate * period.

Examples:

analyze.imd(port=54321, rate=100)
analyze.imd(port=54321, rate=100, pause=True)
imd = analyze.imd(port=12345, rate=1000)
disable()

Disable the analyzer.

Examples:

my_analyzer.disable()

Executing the disable command will remove the analyzer from the system. Any hoomd.run() command executed after disabling an analyzer will not use that analyzer during the simulation. A disabled analyzer can be re-enabled with enable().

enable()

Enables the analyzer

Examples:

my_analyzer.enable()

See disable().

restore_state()

Restore the state information from the file used to initialize the simulations

set_period(period)

Changes the period between analyzer executions

Parameters:period (int) – New period to set (in time steps)

Examples:

analyzer.set_period(100)
analyzer.set_period(1)

While the simulation is running (hoomd.run(), the action of each analyzer is executed every period time steps. Changing the period does not change the phase set when the analyzer was first created.

class hoomd.analyze.log(filename, quantities, period, header_prefix='', overwrite=False, phase=0)

Log a number of calculated quantities to a file.

Parameters:
  • filename (str) – File to write the log to, or None for no file output.
  • quantities (list) – List of quantities to log.
  • period (int) – Quantities are logged every period time steps.
  • header_prefix (str) – Specify a string to print before the header.
  • overwrite (bool) – When False (the default) an existing log will be appended to. When True, an existing log file will be overwritten instead.
  • phase (int) – When -1, start on the current time step. When >= 0, execute on steps where (step + phase) % period == 0.

hoomd.analyze.log reads a variety of calculated values, like energy and temperature, from specified forces, integrators, and updaters. It writes a single line to the specified output file every period time steps. The resulting file is suitable for direct import into a spreadsheet, MATLAB, or other software that can handle simple delimited files. See Units for information on the units in hoomd.

Quantities that can be logged at any time:

  • volume - Volume of the simulation box (in volume units)
  • N - Particle number (dimensionless)
  • lx - Box length in x direction (in length units)
  • ly - Box length in y direction (in length units)
  • lz - Box length in z direction (in length units)
  • xy - Box tilt factor in xy plane (dimensionless)
  • xz - Box tilt factor in xz plane (dimensionless)
  • yz - Box tilt factor in yz plane (dimensionless)
  • momentum - Magnitude of the average momentum of all particles (in momentum units)
  • time - Wall-clock running time from the start of the log (in seconds)

Thermodynamic properties: - The following quantities are always available and computed over all particles in the system (see hoomd.compute.thermo for detailed definitions):

  • num_particles
  • ndof
  • translational_ndof
  • rotational_ndof
  • potential_energy (in energy units)
  • kinetic_energy (in energy units)
  • translational_kinetic_energy (in energy units)
  • rotational_kinetic_energy (in energy units)
  • temperature (in thermal energy units)
  • pressure (in pressure units)
  • pressure_xx, pressure_xy, pressure_xz, pressure_yy, pressure_yz, pressure_zz (in pressure units)
  • The above quantities, tagged with a _groupname suffix are automatically available for any group passed to an integrate command
  • Specify a compute.thermo directly to enable additional quantities for user-specified groups.

The following quantities are only available if the command is parentheses has been specified and is active for logging:

Additionally, all pair and bond potentials can be provided user-defined names that are appended as suffixes to the logged quantity (e.g. with pair.lj(r_cut=2.5, name="alpha"), the logged quantity would be pair_lj_energy_alpha):

By specifying a force, disabling it with the log=True option, and then logging it, different energy terms can be computed while only a subset of them actually drive the simulation. Common use-cases of this capability include separating out pair energy of given types (shown below) and free energy calculations. Be aware that the globally chosen r_cut value is the largest of all active pair potentials and those with log=True, so you will observe performance degradation if you disable(log=True) a potential with a large r_cut.

File output from analyze.log is optional. Specify None for the file name and no file will be output. Use this with the query() method to query the values of properties without the overhead of writing them to disk.

You can register custom python callback functions to provide logged quantities with register_callback().

Examples:

lj1 = pair.lj(r_cut=3.0, name="lj1")
lj1.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
lj1.pair_coeff.set('A', 'B', epsilon=1.0, sigma=1.0)
lj1.pair_coeff.set('B', 'B', epsilon=1.0, sigma=1.0)

lj2 = pair.lj(r_cut=3.0, name="lj2")
lj2.pair_coeff.set('A', 'A', epsilon=1.0, sigma=1.0)
lj2.pair_coeff.set('A', 'B', epsilon=0.0, sigma=1.0)
lj2.pair_coeff.set('B', 'B', epsilon=0.0, sigma=1.0)
lj2.disable(log=True)

analyze.log(filename='mylog.log', quantities=['pair_lj_energy_lj1', 'pair_lj_energy_lj2'],
            period=100, header_prefix='#')


logger = analyze.log(filename='mylog.log', period=100,
                     quantities=['pair_lj_energy'])

analyze.log(quantities=['pair_lj_energy', 'bond_harmonic_energy',
            'kinetic_energy'], period=1000, filename='full.log')

analyze.log(filename='mylog.log', quantities=['pair_lj_energy'],
            period=100, header_prefix='#')

analyze.log(filename='mylog.log', quantities=['bond_harmonic_energy'],
            period=10, header_prefix='Log of harmonic energy, run 5\\n')
logger = analyze.log(filename='mylog.log', period=100,
                     quantities=['pair_lj_energy'], overwrite=True)

log = analyze.log(filename=None, quantities=['potential_energy'], period=1)
U = log.query('potential_energy')

By default, columns in the log file are separated by tabs, suitable for importing as a tab-delimited spreadsheet. The delimiter can be changed to any string using set_params()

The header_prefix can be used in a number of ways. It specifies a simple string that will be printed before the header line of the output file. One handy way to use this is to specify header_prefix=’#’ so that gnuplot will ignore the header line automatically. Another use-case would be to specify a descriptive line containing details of the current run. Examples of each of these cases are given above.

Warning

When an existing log is appended to, the header is not printed. For the log to remain consistent with the header already in the file, you must specify the same quantities to log and in the same order for all runs of hoomd that append to the same log.

disable()

Disable the logger.

Examples:

logger.disable()

Executing the disable command will remove the logger from the system. Any hoomd.run() command executed after disabling the logger will not use that logger during the simulation. A disabled logger can be re-enabled with enable().

enable()

Enables the logger

Examples:

logger.enable()

See disable().

query(quantity)

Get the current value of a logged quantity.

Parameters:quantity (str) – Name of the quantity to return.

query() works in two different ways depending on how the logger is configured. If the logger is writing to a file, query() returns the last value written to the file. If filename is None, then query() returns the value of the quantity computed at the current timestep.

Examples:

logdata = logger.query('pair_lj_energy')
log = analyze.log(filename=None, quantities=['potential_energy'], period=1)
U = log.query('potential_energy')
register_callback(name, callback)

Register a callback to produce a logged quantity.

Parameters:
  • name (str) – Name of the quantity
  • callback (callable) – A python callable object (i.e. a lambda, function, or class that implements __call__)

The callback method must take a single argument, the current timestep, and return a single floating point value to be logged.

Note

One callback can query the value of another, but logged quantities are evaluated in order from left to right.

Examples:

logger = analyze.log(filename='log.dat', quantities=['my_quantity', 'cosm'], period=100)
logger.register_callback('my_quantity', lambda timestep: timestep**2)
logger.register_callback('cosm', lambda timestep: math.cos(logger.query('my_quantity')))
restore_state()

Restore the state information from the file used to initialize the simulations

set_params(quantities=None, delimiter=None)

Change the parameters of the log.

Parameters:
  • quantities (list) – New list of quantities to log (if specified)
  • delimiter (str) – New delimiter between columns in the output file (if specified)

Examples:

logger.set_params(quantities=['bond_harmonic_energy'])
logger.set_params(delimiter=',');
logger.set_params(quantities=['bond_harmonic_energy'], delimiter=',');
set_period(period)

Changes the period between analyzer executions

Parameters:period (int) – New period to set (in time steps)

Examples:

analyzer.set_period(100)
analyzer.set_period(1)

While the simulation is running (hoomd.run(), the action of each analyzer is executed every period time steps. Changing the period does not change the phase set when the analyzer was first created.