SoftMatterDynamicsMeasurements¶

Included in QATK.Dynamics

class SoftMatterDynamicsMeasurements(kinetic_energy=None, potential_energy=None, volume=None, density=None, temperature=None, dipole=None, charge_current=None, charge_current_groups=None, pressure=None, stress=None, strain=None, call_interval=None)¶

Create a hook for measuring various properties during a soft matter dynamics calculation.

Parameters:

kinetic_energy (bool) – Whether to measure the kinetic energy.
potential_energy (bool) – Whether to measure the potential energy.
volume (bool) – Whether to measure the volume.
density (bool) – Whether to measure the density.
temperature (bool) – Whether to measure the temperature.
dipole (None | bool | All | str | list[str]) – Whether to measure the dipole moment. None or False does not measure the dipole. True or "vector" measures the full dipole vector and stores it as a vector. All measures all dipole components and stores them as separate scalar properties. Separate components can be calculated by specifying "x", "y", or "z" as either a single string or a list of strings. Components are stored as separate scalar properties.
charge_current (None | bool | All | str | list[str]) – Whether to measure the charge current. None or False does not measure the charge current. True or "vector" measures the full charge current vector and stores it as a vector. All measures all charge current components and stores them as separate scalar properties. Separate components can be calculated by specifying "x", "y", or "z" as either a single string or a list of strings. Components are stored as separate scalar properties.
charge_current_groups (None | str | list[str]) – Whether to calculate the charge current for selected groups of atoms. None does not measure the charge current. Groups can be specified with a string or list of strings of configuration tags that specify the charge groups.
pressure (None | bool | All | Isotropic | Anisotropic | DiagonalOnly | str | list[str]) – Whether to measure the pressure. None or False does not measure the pressure. True or Isotropic calculates the scalar pressure. Anisotropic or "tensor" measures the full pressure tensor and stores it as a tensor. DiagonalOnly stores the diagonal pressure elements as separate scalars. All measures all pressure components and stores them as separate scalar properties. Separate components can be calculated by specifying "xx", "yy", "zz" "xy", "xz" or "yz" as either a single string or a list of strings.
stress (None | bool | All | Isotropic | Anisotropic | DiagonalOnly | str | list[str]) – Whether to measure the stress. None or False does not measure the stress. True or Isotropic calculates the scalar stress. Anisotropic or "tensor" measures the full stress tensor and stores it as a tensor. DiagonalOnly stores the diagonal stress elements as separate scalars. All measures all stress components and stores them as separate scalar properties. Separate components can be calculated by specifying "xx", "yy", "zz" "xy", "xz" or "yz" as either a single string or a list of strings.
strain (None | bool | All | Isotropic | Anisotropic | DiagonalOnly | str | list[str]) – Whether to measure the strain. None or False does not measure the strain. True or Anisotopic calculates the scalar strain. Anisotropic or "tensor" measures the full strain tensor and stores it as a tensor. DiagonalOnly stores the diagonal strain elements as separate scalars. All measures all strain components and stores them as separate scalar properties. Separate components can be calculated by specifying "xx", "yy", "zz" "xy", "xz" or "yz" as either a single string or a list of strings.
call_interval (int) – The interval (in steps) at which to measure the given properties.

Note

Argument changes:

call_frequency: Replaced with call_interval since 2026.03

callInterval()¶

Returns:: The call interval of the hook.
Return type:: int

chargeCurrent()¶

Returns:: The charge current measurement option.
Return type:: None | Isotropic | Anisotropic | list[str]

chargeCurrentGroups()¶

Returns:: The charge current groups option.
Return type:: None | list[str]

density()¶

Returns:: Whether to measure the density.
Return type:: bool

dipole()¶

Returns:: The dipole measurement option.
Return type:: None | Isotropic | Anisotropic | list[str]

kineticEnergy()¶

Returns:: Whether to measure the kinetic energy.
Return type:: bool

potentialEnergy()¶

Returns:: Whether to measure the potential energy.
Return type:: bool

pressure()¶

Returns:: The pressure measurement option.
Return type:: None | Isotropic | DiagonalOnly | Anisotropic | list[str]

strain()¶

Returns:: The strain measurement option.
Return type:: None | Isotropic | DiagonalOnly | Anisotropic | list[str]

stress()¶

Returns:: The stress measurement option.
Return type:: None` | Isotropic | DiagonalOnly | Anisotropic | list[str]

temperature()¶

Returns:: Whether to measure the temperature.
Return type:: bool

uniqueString()¶: Return a unique string representing the state of the object.

volume()¶

Returns:: Whether to measure the volume.
Return type:: bool

Usage Examples¶

Perform an NVT simulation of acrylonitrile and measure the pressure, dipole moment and energy. All three components of the dipole moment are calculated using fluctuations from the charges assigned by the OPLS forcefield. Likewise the diagonal components of the pressure tensor are recorded and stored as individual measurements in the trajectory.

# Set the measurement hook
measurement = SoftMatterDynamicsMeasurements(
    kinetic_energy=True,
    potential_energy=True,
    dipole=All,
    pressure=DiagonalOnly,
    call_interval=100,
)

# Run the simulation
simulation.simulate(100000, hook_functions=[measurement])

equilibrated_acrylonitrile.hdf5 measurement_example.py

Notes¶

The SoftMatterDynamicsMeasurements class is used to measure quantities during a soft matter dynamics simulation where it operates as a hook function. The properties to be measured are specified as arguments when the class is instantiated. The hook function is then given to the simulate method in the SoftMatterDynamicsSimulation using the hook_functions argument. This includes the hook functions in the molecular dynamics simulation. Hook functions are only active for the simulate call they are given to. The selected properties are written to the MDTrajectory as measurements during the simulation.

By default all measurement properties are turned off, and thus all desired measurements must be selected. In this class three types of properties, scalar, vector and tensor can be measured. Scalar properties include thing like kinetic energy and density. Selecting these types of measurements is done with a simple True/False to their corresponding arguments.

Vector properties include things like the dipole moment and charge_current. Here in addition to True/False specific components of the vector can be measured separately. Giving True or the string "vector" to the argument causes the whole vector to be stored as a vector in the trajectory. While more compact, this means that individual vector components cannot be visualized in the Movie Tool. To store all vector components as separate measurements the flag All can be given. Separate components can also be selected by giving the strings "x", "y" and "z" to measure the corresponding vector component.

Tensor properties include the system pressure and strain. The tensor and its components can be selected in a number of ways. Giving True or the flag Isotropic calculates the tensor trace and stores it as a single value. The flag DiagonalOnly calculates the diagonal elements of the tensor and stores them as separate measurements. Likewise the flag All stores all 6 unique values and stores them as separate measurements. The full tensor can be stored as a tensor using either the flag Anisotropic or the string "tensor". Lastly individual components of the tensor can be selected with the string "xx", "yy", "zz", "xy", "xz" and "yz".

In addition to the desired measurements number of steps between when measurements are calculated and stored can also be given. This is specified in the argument call_interval argument. In general this should not be set too low, as frequent property calculation can degrade the performance of the overall molecular dynamics. The amount of storage required for each property should also be considered. This is especially true when measuring pressure and stress, as these are calculated numerically. In addition it should be noted that the calculation of these properties does not take into account bond constraints. If accurate measurements of pressure or stress are required for your simulation then bond constraints should be not used.