calculate marked particles command

Purpose

This command calculates the number and mass of marked particles that are in a specified region (examples).

Syntax

calculate marked_particles region region-ID marker_id marker-ID keyword value

Keywords	Description
region	mandatory keyword, ID of counting region
marker_id	mandatory keyword, ID of a mark_particles or mark_inserted_particles command
particle_group	only the particles belonging to this group and to the marker-ID group are counted default: `all`
id	user-assigned name for the command call default: `marked_particles_[index of calculate]`
particle_group	particle group which is considered default: `all`
reset_marker	Resets the marker after counting the particle available options: `yes` or `no` default: `no`
count_through_periodic_boundary	defines whether particles are counted once / always when passing through a periodic boundary available options: `once` or `always` default: `once`
dimension	only required if more than one periodic boundary available, required for specifying the one to be used for `count_through_periodic_boundary always` available options: `x`, `y` or `z`
final_update	Recomputes at the last step of a simulate command. available options: `yes` or `no` default: `yes`

Examples

calculate marked_particles region reg1 marker_id mp1
calculate marked_particles region reg1 marker_id mp1 particle_group myParts id myMarkedParts
calculate marked_particles region reg1 marker_id mp1 reset_marker yes
calculate marked_particles region reg1 marker_id mp1 count_through_periodic_boundary always dimension z

Description

This command calculates the number and mass of marked and un-marked particles that are in the region specified via the region keyword. By default, all marked particles are counted and the optional particle_group keyword allows to consider only marked particles that are in special groups. Note that only particles marked by a mark_particles or mark_inserted_particles command are counted; therefore, a valid ID of such a command has to be provided via the marker_id keyword.

The reset_marker keyword controls if particles are un-marked after they have been counted once by this command. The default is that particles will remain marked.

The count_through_periodic_boundary keyword controls the way particle are counted when they cross a periodic boundary condition. If once is selected, particles are un-marked as soon as the cross the periodic boundary; hence, they are counted only once. The opposite occurs if always is selected. If the domain has more than one periodic boundary, the user must specify one of them via the dimension keyword. By default, count_through_periodic_boundary is set to once for all the possible periodic boundary conditions.

Warning

If multiple calculate marked_particles commands are operating on the same mark_particles or mark_inserted_particles command, the first calculate command will reset the marker value if reset_marker yes is used. If this is the case, the second calculate marked_particles command will not count them again. Note that the default setting reset_marker no will allow to reuse an existing marker.

The final_update keyword can be used to force a recomputation of the value at the last integration step of a simulate command. This is useful if the value is required in the input script between two simulate commands, e.g. for setting a variable.

Output information

The calculate marked_particles command calculates a global vector containing the following information:

Position	Property	Description
1	particles_total	total number of (marked + un-marked) particles in region
2	particles_marked	number of marked particles in region
3	mass_total	total mass of (marked + un-marked) particles in region
4	mass_marked	mass of marked particles in region

To access these values one could use dot-access (command-ID.Property) or the position (access via command-ID[Position]), where Property and Position are given in the table above.

When using the output_settings command the four components of the command are automatically written to the simulation_data.csv / result_monitor.csv file.

Alternatively, also the write_to_file command can be used to output the data to a specified file.

calculate marked_particles region reg1 marker_id mp1 id marker
write_to_file file marked_particles.txt string "id_time id_marker.particles_marked" &
    title "# time number_of_marked_particles"