calculate residence distance command
Purpose
This command computes the distance travelled by particles in specified regions (examples).
Syntax
calculate residence_distance keyword/value pairs
Keywords |
Description |
|---|---|
id |
user-assigned name for the command call
default:
residence_distance_[index of calculate] |
particle group for which the residence distance is evaluated
default:
all |
|
list of region-IDs where the residence distance is evaluated
|
|
time step width for command execution
default: same value as write_to_terminal_timestep; range: (0,∞); units: [time]
|
Examples
calculate residence_distance
calculate residence_distance particle_group markerParticles regions {reactionZone}
calculate residence_distance check_every_time 0.01 regions {r1,r2} id res
Description
This command computes the distance travelled by particles in the whole
simulation domain, and if applicable, also
in the regions specified by the optional regions keyword.
If the particle_group keyword is used, the residence distance calculation
is restricted to the specified group of particles.
Per default, time interval at which the residence distance is calculated is defined by the
write_to_terminal_timestep command. If a finer
resolution is desired, the check_every_time keyword can be used to decrease the
evaluation time interval. The check_every_time value must be a multiple of the
simulation timestep and the write_to_terminal_timestep must be a multiple of the
check_every_time value.
Output information
This command generates global and per-particle output.
Global output
The global output is a vector having n+1 components, where n is the number
of regions specified via the regions keyword. Each component stores the average
travelled distance of the particle group for the whole simulation domain (first component)
and for each region (following components). The order is following the one in which
the regions are listed after the regions keyword. The components of the generated
vector for a command with ID RESID can be accessed by id_RESID[1], etc.
When using the output_settings command, the results are automatically written to the simulation_data_aspherix.csv / result_monitor.txt file.
Alternatively, also the write_to_file command can be used to output the data to a specified file.
Example for saving the travelled distance to a separate file
calculate residence_distance regions {reg1,reg2} id res
write_to_file file residence_distance.txt string "id_time id_res[1] id_res[2] id_res[3]" &
title "# time simulation_domain region1 region2"
Information about this command is written to binary restart files.
Per particle output
calculate residence_distance commands also save the individual travelled distance of each
particle (for the entire simulation domain as well as potentially specified regions)
plus an additional marker quantity. The latter is used for internal purposes and
can be ignored by the user. The output_settings command automatically the result
to the particle properties that can be visualized in Paraview, Ovito, etc.
If the keyword regions is not used, the per-particle residence distance can be accessed by
id_RESID, otherwise the per-property values are accessed by id_RESID[1], id_RESID[2], etc.
In the latter case an additional vector component is saved (id: number of regions + 2) which
contains a marker which is only used for internal purposes and can be ignored.
Example for accessing per-particle residence distance
# calculate the residence distance in simulation domain only
calculate residence_distance id res
# extract the per-particle residence distance in the simulation domain
variable globRes atom res
# calculate the residence distance in the simulation domain + in region reg1
calculate residence_distance regions {reg1} id res2
# extract the per-particle residence distance in simulation domain and reg1
variable resSimDom atom res[1]
variable resReg1 atom res[2]
Restrictions
The calculate residence_distance command cannot be used for multisphere particles.