calculate temporal_residual command

Purpose

This command calculates the absolute or relative temporal residuals of specified scalar quantities.

Syntax

calculate temporal_residual keyword/value pairs

Keywords

Keywords	Description
id	user-assigned name for the calculate temporal_residual command
quantity*	ID (without prefix) of the command/variable storing a scalar value
quantities*	brace-enclosed list of variables/commands storing the corresponding scalar values
mode	Specifies the expression used in the definition of the residual. available options: `relative` or `absolute` default: `relative`
update_every_time	time interval used in the definition of the residual units: seconds; default: write_every_time value

* The keywords quantity and quantities are mutually exclusive.

Examples

# instantaneous mass of the system
calculate sum id total_mass region filling_region particle_group all quantity mass
# absolute residual of the total mass
calculate temporal_residual id mass_absolute_residual quantity total_mass update_every_time 0.01 mode absolute

# instantaneous kinetic energy of the system
variable instantaneous_ke equal "ke(all,filling_region)"
# temporal-averaged kinetic energy of the system
calculate temporal_average id temporal_averaged_ke particle_group all update_every_time 0.01 object instantaneous_ke
# several residuals are calculated in a single command
calculate temporal_residual id relative_residuals quantities {total_mass, instantaneous_ke, temporal_averaged_ke} update_every_time 0.01 mode relative

Access the calculated values above via:

id_mass_absolute_residual
id_relative_residuals[1]
id_relative_residuals[2]
id_relative_residuals[3]

Description

This command calculates the temporal residuals of scalar quantities that are stored by other commands or variables. Only scalar quantities can be used with this command i.e. per-atom quantities, vectors and arrays are not allowed.

The quantities are specified by the quantity or quantities keywords. For mode relative the temporal residual $\delta f(t)$ of a certain scalar $f(t)$ , at time instant $t$ , is defined by

(1) $\delta f(t) = \begin{cases} \frac{f(t) - f(t - \Delta t)}{f(t - \Delta t)}, & \text{if } f(t - \Delta t) \ne 0 \\ 1, & \text{otherwise} \end{cases}$

whereas for mode absolute the residual is defined by

$\delta f(t) = f(t) - f(t - \Delta t).$

In both cases, the time interval $\Delta t$ [s] used for the residual calculation is set by the update_every_time keyword.

Temporal residuals can be useful to define conditions (using e.g. a variable boolean) that are the input of the simulate mode until_condition_reached command, triggering the termination of the simulation once the condition is reached.

The relative temporal residuals of quantities that approach zero can assume very high values, because the denominator in equation Eq.1 is very small. Thus, in those cases it is recommended to use the mode absolute.