reporters¶
-
class
atomsmm.reporters.ExtendedStateDataReporter(file, reportInterval, **kwargs)[source]¶ An extension of OpenMM’s StateDataReporter class, which outputs information about a simulation, such as energy and temperature, to a file.
All original functionalities of StateDataReporter are preserved and the following ones are included:
Report the Coulomb contribution of the potential energy (keyword: coulombEnergy):
This contribution includes both real- and reciprocal-space terms.
Report the atomic virial of a fully-flexible system (keyword: atomicVirial):
Considering full scaling of atomic coordinates in a box volume change (i.e. without any distance constraints), the internal virial of the system is given by
\[W = -\sum_{i,j} r_{ij} E^\prime(r_{ij}),\]where \(E^\prime(r)\) is the derivative of the pairwise interaction potential as a function of the distance between to atoms. Such interaction includes van der Waals, Coulomb, and bond-stretching contributions. Bond-bending and dihedral angles are not considered because they are invariant to full volume-scaling of atomic coordinates.
Report the nonbonded contribution of the atomic virial (keyword: nonbondedVirial):
The nonbonded virial is given by
\[W_\mathrm{nb} = -\sum_{i,j} r_{ij} E_\mathrm{nb}^\prime(r_{ij}),\]where \(E_\mathrm{nb}^\prime(r)\) is the derivative of the nonbonded pairwise potential, which comprises van der Waals and Coulomb interactions only.
Report the atomic pressure of a fully-flexible system (keyword: atomicPressure):
\[P = \frac{2 K + W}{3 V},\]where \(K\) is the kinetic energy sum for all atoms in the system. If keyword bathTemperature is employed (see below), the instantaneous kinetic energy is substituted by its equipartition-theorem average \(\left\langle K \right\rangle = 3 N_\mathrm{atoms} k_B T/2\), where \(T\) is the heat-bath temperature.
Report the molecular virial of a system (keyword: molecularVirial):
To compute the molecular virial, only the center-of-mass coordinates of the molecules are considered to scale in a box volume change, while the internal molecular structure is kept unaltered. The molecular virial is computed from the nonbonded part of the atomic virial by using the formulation of Ref. [1]:
\[W_\mathrm{mol} = W - \sum_{i} (\mathbf{r}_i - \mathbf{r}_i^\mathrm{cm}) \cdot \mathbf{F}_i,\]where \(\mathbf{r}_i\) is the coordinate of atom i, \(\mathbf{F}_i\) is the resultant pairwise force acting on it (excluding bond-bending and dihedral angles), and \(\mathbf{r}_i^\mathrm{cm}\) is the center-of-mass coordinate of its containing molecule.
Report the molecular pressure of a system (keyword: molecularPressure):
\[P = \frac{2 K_\mathrm{mol} + W_\mathrm{mol}}{3 V},\]where \(K_\mathrm{mol}\) is the center-of-mass kinetic energy summed for all molecules in the system. If keyword bathTemperature is employed (see below), the instantaneous kinetic energy is substituted by its equipartition-theorem average \(\left\langle K_\mathrm{mol} \right\rangle = 3 N_\mathrm{mols} k_B T/2\), where \(T\) is the heat-bath temperature.
Report the center-of-mass kinetic energy (keyword: molecularKineticEnergy):
\[K_\mathrm{mol} = \frac{1}{2} \sum_{i=1}^{N_\mathrm{mol}} M_i v_{\mathrm{cm}, i}^2,\]where \(N_\mathrm{mol}\) is the number of molecules in the system, \(M_i\) is the total mass of molecule i, and \(v_{\mathrm{cm}, i}\) is the center-of-mass velocity of molecule i.
Report potential energies at multiple global parameter states (keyword: globalParameterStates):
Computes and reports the potential energy of the system at a number of provided global parameter states.
Report global parameter values (keyword: globalParameters):
Reports the values of specified global parameters.
Report derivatives of energy with respect to global parameters (keyword: energyDerivatives):
Computes and reports derivatives of the potential energy of the system at the current state with respect to specified global parameters.
Report values of collective variables (keyword: collectiveVariables)
Report the values of a set of collective variables.
Allow specification of an extra file for reporting (keyword: extraFile).
This can be used for replicating a report simultaneously to sys.stdout and to a file using a unique reporter.
- Keyword Arguments
coulombEnergy (bool, optional, default=False) – Whether to write the Coulomb contribution of the potential energy to the file.
atomicVirial (bool, optional, default=False) – Whether to write the total atomic virial to the file.
nonbondedVirial (bool, optional, default=False) – Whether to write the nonbonded contribution to the atomic virial to the file.
atomicPressure (bool, optional, default=False) – Whether to write the internal atomic pressure to the file.
molecularVirial (bool, optional, default=False) – Whether to write the molecular virial to the file.
molecularPressure (bool, optional, default=False) – Whether to write the internal molecular pressure to the file.
molecularKineticEnergy (bool, optional, default=False) – Whether to write the molecular center-of-mass kinetic energy to the file.
globalParameterStates (pandas.DataFrame, optional, default=None) – A DataFrame containing context global parameters (column names) and sets of values thereof. If it is provided, then the potential energy will be reported for every state these parameters define.
globalParameters (list(str), optional, default=None) – A list of global parameter names. If it is provided, then the values of these parameters will be reported.
energyDerivatives (list(str), optional, default=None) – A list of global parameter names. If it is provided, then the derivatives of the total potential energy with respect to these parameters will be reported. It is necessary that the calculation of these derivatives has been activated beforehand (see, for instance, CustomIntegrator).
collectiveVariables (list(openmm.CustomCVForce), optional, default=None) – A list of CustomCVForce objects. If it is provided, then the values of all collective variables associated with these objects will be reported.
pressureComputer (
PressureComputer, optional, default=None) – A computer designed to determine pressures and virials. This is mandatory if any keyword related to virial or pressure is set as True.extraFile (str or file, optional, default=None) – Extra file to write to, specified as a file name or a file object.
-
class
atomsmm.reporters.XYZReporter(file, reportInterval, **kwargs)[source]¶ Outputs to an XYZ-format file a series of frames containing the coordinates, velocities, momenta, or forces on all atoms in a Simulation.
Note
Coordinates are expressed in nanometers, velocities in nanometer/picosecond, momenta in dalton*nanometer/picosecond, and forces in dalton*nanometer/picosecond^2.
To use this reporter, create an XYZReporter object and append it to the Simulation’s list of reporters.
- Keyword Arguments
output (str, default='positions') – Which kind of info to report. Valid options are ‘positions’, ‘velocities’, ‘momenta’ and ‘forces’.
groups (set(int), default=None) – Which force groups to consider in the force calculations. If this is None, then all force groups will be evaluated.
-
class
atomsmm.reporters.CenterOfMassReporter(file, reportInterval, **kwargs)[source]¶ Outputs to an XYZ-format file a series of frames containing the center-of-mass coordinates, center-of-mass velocities, total momenta, or resultant forces on all molecules in a Simulation.
Note
Coordinates are expressed in nanometers, velocities in nanometer/picosecond, momenta in dalton*nanometer/picosecond, and forces in dalton*nanometer/picosecond^2.
To use this reporter, create an CenterOfMassReporter object and append it to the Simulation’s list of reporters.
- Keyword Arguments
output (str, default='positions') – Which kind of info to report. Valid options are ‘positions’, ‘velocities’, ‘momenta’ and ‘forces’.
groups (set(int), default=None) – Which force groups to consider in the force calculations. If this is None, then all force groups will be evaluated.
-
class
atomsmm.reporters.CustomIntegratorReporter(file, reportInterval, **kwargs)[source]¶ Outputs global and per-DoF variables of a CustomIntegrator instance.
- Keyword Arguments
describeOnly (bool, optional, default=True) – Whether to output only descriptive statistics that summarize the activated per-Dof variables.
-
class
atomsmm.reporters.ExpandedEnsembleReporter(file, reportInterval, states, temperature, **kwargs)[source]¶ Performs an Expanded Ensemble simulation and reports the energies of multiple states.
- Parameters
states (pandas.DataFrame_) – A DataFrame containing context global parameters (column names) and sets of values thereof. The potential energy will be reported for every state these parameters define. If one of the variables is named as weight, then its set of values will be assigned to every state as an importance sampling weight. Otherwise, all states will have identical weights. States which are supposed to only have their energies reported, with no actual visits, can have their weights set up to -inf.
temperature (unit.Quantity) – The system temperature.
- Keyword Arguments
reportsPerExchange (int, optional, default=1) – The number of reports between attempts to exchange the global parameter state, that is, the exchange interval measured in units of report intervals.