calculate residence time command

Purpose

This command computes the residence time of particles in the regions listed after a regions keyword (examples).

Syntax

calculate residence_time keyword/value pairs

Keywords

Description

id
user-assigned name for the command call
default: residence_time_[index of calculate]

particle_group
particle group for which the residence time is evaluated
default: all

regions
list of region-IDs where the residence time is evaluated

check_every_time
time step width for command execution
default: same value as write_to_terminal_timestep; range: (0,∞); units: [time]

Examples

calculate residence_time
calculate residence_time particle_group markerParticles regions {reactionZone}
calculate residence_time check_every_time 0.01 regions {r1,r2} id res

Description

This command computes the residence time of 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 time calculation is restricted to the specified group of particles.

Per default, time interval at which the residence time 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 residence time 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 residence time to a separate file

calculate residence_time regions {reg1,reg2} id res
write_to_file file residence_time.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_time commands also save the individual residence time 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 time 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 time

# calculate the residence time in simulation domain only
calculate residence_time id res
# extract the per-particle residence time in the simulation domain
variable globRes atom res

# calculate the residence time in the simulation domain + in region reg1
calculate residence_time regions {reg1} id res2
# extract the per-particle residence times in simulation domain and reg1
variable resSimDom atom id_res2[1]
variable resReg1 atom id_res2[2]

Example for the usage of per-particle residence times

# calculate the residence time
calculate residence_time id res
# define the evaluation region
region reg1 block low ( 0, 0, 0.0 ) high ( 0.1, 0.1, 0.01 )
# average the residence time in the evaluation region
calculate average quantity id_res region reg1 id avgRes
# write the result to a file
write_to_file file average_residence_time.txt string "id_time id_avgRes" &
    title "# time average_residence_time"
# standard output_settings command
output_settings
# add new global properties to terminal output & simulation_data_aspherix.csv /
# result_monitor.txt
status_style mode add all {id_avgRes}

Example for tracking the residence time of particles leaving the domain

# residence time in simulation_domain
calculate residence_time id restime
# calculate massflow and add residence time to log
calculate massflow mesh outlet outward_vector ( 1, 0, 0 ) id mf_outlet &
    count_particles_once yes file massflow_rt.txt delete_atoms yes &
    file_properties { id_restime }

Restrictions

  • The calculate residence_time command cannot be used for multisphere particles.

  • Resetting the timestep when restarting (i.e. read ... reset_timestep yes) will invalidate the stored residence time value. CFDEMcoupling will sync the DEM timestep to match that on the CFD side and produce the same error if the restart time on the DEM side is out of sync.