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: 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 withenable()
.
-
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 withenable()
.
-
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:
- Pair potentials
- pair_dpd_energy (
hoomd.md.pair.dpd
) - Total DPD conservative potential energy (in energy units) - pair_dpdlj_energy (
hoomd.md.pair.dpdlj
) - Total DPDLJ conservative potential energy (in energy units) - pair_eam_energy (
hoomd.metal.pair.eam
) - Total EAM potential energy (in energy units) - pair_ewald_energy (
hoomd.md.pair.ewald
) - Short ranged part of the electrostatic energy (in energy units) - pair_gauss_energy (
hoomd.md.pair.gauss
) - Total Gaussian potential energy (in energy units) - pair_lj_energy (
hoomd.md.pair.lj
) - Total Lennard-Jones potential energy (in energy units) - pair_morse_energy (
hoomd.md.pair.yukawa
) - Total Morse potential energy (in energy units) - pair_table_energy (
hoomd.md.pair.table
) - Total potential energy from Tabulated potentials (in energy units) - pair_slj_energy (
hoomd.md.pair.slj
) - Total Shifted Lennard-Jones potential energy (in energy units) - pair_yukawa_energy (
hoomd.md.pair.yukawa
) - Total Yukawa potential energy (in energy units) - pair_force_shifted_lj_energy (
hoomd.md.pair.force_shifted_lj
) - Total Force-shifted Lennard-Jones potential energy (in energy units) - pppm_energy (
hoomd.md.charge.pppm
) - Long ranged part of the electrostatic energy (in energy units)
- pair_dpd_energy (
- Bond potentials
- bond_fene_energy (
hoomd.md.bond.fene
) - Total fene bond potential energy (in energy units) - bond_harmonic_energy (
hoomd.md.bond.harmonic
) - Total harmonic bond potential energy (in energy units) - bond_table_energy (
hoomd.md.bond.table
) - Total table bond potential energy (in energy units)
- bond_fene_energy (
- Angle potentials
- angle_harmonic_energy (
hoomd.md.angle.harmonic
) - Total harmonic angle potential energy (in energy units)
- angle_harmonic_energy (
- Dihedral potentials
- dihedral_harmonic_energy (
hoomd.md.dihedral.harmonic
) - Total harmonic dihedral potential energy (in energy units)
- dihedral_harmonic_energy (
- Special pair interactions
- special_pair_lj_energy (
hoomd.md.special_pair.lj
) - Total energy of special pair interactions (in energy units) - External potentials
- external_periodic_energy (
hoomd.md.external.periodic
) - Total periodic potential energy (in energy units) - external_e_field_energy (
hoomd.md.external.e_field
) - Total e_field potential energy (in energy units)
- external_periodic_energy (
- Wall potentials
- external_wall_lj_energy (
hoomd.md.wall.lj
) - Total Lennard-Jones wall energy (in energy units) - external_wall_gauss_energy (
hoomd.md.wall.gauss
) - Total Gauss wall energy (in energy units) - external_wall_slj_energy (
hoomd.md.wall.slj
) - Total Shifted Lennard-Jones wall energy (in energy units) - external_wall_yukawa_energy (
hoomd.md.wall.yukawa
) - Total Yukawa wall energy (in energy units) - external_wall_mie_energy (
hoomd.md.wall.mie
) - Total Mie wall energy (in energy units)
- external_wall_lj_energy (
- Integrators
- langevin_reservoir_energy_groupname (
hoomd.md.integrate.langevin
) - Energy reservoir for the Langevin integrator (in energy units) - nvt_reservoir_energy_groupname (
hoomd.md.integrate.nvt
) - Energy reservoir for the NVT thermostat (in energy units) - nvt_mtk_reservoir_energy_groupname (
hoomd.md.integrate.nvt
) - Energy reservoir for the NVT MTK thermostat (in energy units) - npt_thermostat_energy (
hoomd.md.integrate.npt
) - Energy of the NPT thermostat - npt_barostat_energy (
hoomd.md.integrate.npt
&hoomd.md.integrate.nph
) - Energy of the NPT (or NPH) barostat
- langevin_reservoir_energy_groupname (
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 withenable()
.
-
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, thenquery()
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: 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.