calculate massflow command

Purpose

This command tracks how many particles pass through a surface (examples).

Syntax

calculate massflow keyword/value pairs

Every calculate massflow command requires information about a shape that is used for the measurement and a measurement direction.

Keywords	Description
mesh ¹	Mesh id for the mesh to be used as surface for the calculation
outlet_shape ¹	Creates a surface of the given shape for the massflow calculation available options: `circle`, `ellipse`, `square` or `rectangle` (keywords see here)

¹ The keywords mesh and outlet_shape are mutually exclusive.

Keywords	Description
outward_vector ²	Vector pointing towards the “outside” of the surface used for the calculation.
count_particles_once ³	Sets whether particles are computed only the first time they go through the surface. available options: `yes` or `no` default: `yes`
point_at_outlet ²	Coordinate of the point on the outlet side of the surface.
inside_out	Inverts the direction for `point_at_outlet`. available options: `yes` or `no` default: `no`
point_inside_mesh ²	Coordinate of the center of a spherical / cylindrical mesh, which defines both `point_at_outlet` and `inside_out` at once.

² The keywords outward_vector, point_at_outlet and point_inside_mesh are mutually exclusive.

³ The keyword count_particles_once is automatically set to yes if point_at_outlet is used.

Keywords	Description
id	user-assigned name for the calculate massflow command
particle_group	Particle group for which the calculation will be performed default: `all`
delete_atoms	Deletes particles after they pass through the surface. available options: `yes` or `no` default: `no`
sum_additional_properties	Brace-enclosed list of additional particle variables or commands to be summed.
sum_additional_properties_mode	Mode with which additional properties are summed. available options: `out` or `net` default: `out`
file	name of the file where results will be saved.
mode *	Mode with which file is written. available options: `write` or `append` default: `write`
file_properties *	Brace-enclosed list of particle properties to be output to file
write_to_terminal	Prints per-particle information to screen when particle passes mesh / face available options: `yes` or `no` default: `no`

This keyword only works if file is defined.

Examples

mesh id inface material material1 solid no file meshes/mf_measurement_face.stl
calculate massflow mesh inface outward_vector (0, 0, -1)

calculate massflow outlet_shape circle center (0.05,0.05,0) radius 0.05 outward_vector (0, 0, -1)

calculate massflow id mf mesh measure_face point_at_outlet (1e-2, 1e-2, 0) &
   sum_additional_properties {v_volume, id_dSauter} file post/mf_particle_information.txt &
   file_properties {id_psd[1], id_psd[2], id_psd[3]} mode write delete_atoms yes

calculate massflow outlet_shape circle center (0.05,0.05,0) radius 0.05 outward_vector (0, 0, -1) &
   count_particles_once yes write_to_terminal yes

calculate massflow outlet_shape ellipse center (0.05,0.05,0) x_axis (1,0,0) x_radius 0.05 y_radius 0.1 &
   outward_vector (0, 0, -1)

calculate massflow outlet_shape square center (0.05,0.05,0) x_axis (1,0,0) length 0.05 outward_vector (0, 0, -1)

calculate massflow outlet_shape rectangle center (0.05,0.05,0) x_axis (1,0,0) x_length 0.05 y_length 0.1 &
   outward_vector (0, 0, -1) particle_group blueParticles

Description

The calculate massflow command tracks the mass / particles that pass a surface in a given direction.

The surface can be defined either as a mesh, or as an outlet_shape.

The mesh keyword requires non-solid mesh defined by a mesh command. The outlet_shape is a generic shape that is defined within the frame of this command (keywords and more information can be found here).

Particles are counted if they cross from the inner side to the outer side of the surface (default output), specific variables also contain information about particles crossing in the reverse direction (see Section Output Information for more details).

The outer side can be defined either by using the keyword outward_vector or by specifying a point at the outlet side of the surface (keyword point_at_outlet or point_inside_mesh). The keywords outward_vector, point_at_outlet and point_inside_mesh are mutually exclusive and one of them must be always selected.

Warning

The following restrictions apply in case outward_vector is specified:

the surface must be planar,
the vector defined by outward_vector must not lie on the surface plane.

Note that the vector defined by outward_vector does not necessarily have to be perpendicular to the mesh.

The keyword point_at_outlet is especially useful in case a cylindrically-shaped surface is used. The point_at_outlet value should be on the cylinder axis in this case. If you like to track particles moving away from the cylinder axis, specify the point_at_outlet on the axis, and use the keyword inside_out to flip the direction. If a mesh is used a point_inside_mesh can be defined, which will essentially set the point_at_outlet and flip the direction both at once (outwards is then defined as the direction from the point_inside_mesh towards the wall).

The count_particles_once command sets whether particles are computed only the first time they go through the surface. By default it is set to yes. If set to no, a particle contributes to number and mass count every time it crosses the surface. This is useful in the case of periodic boundary conditions or in re-circulating flow conditions, otherwise backflowing particles will not be counted anymore. If the point_at_outlet keyword is set, then count_particles_once is automatically set to yes and cannot be changed.

This command tracks how many particles pass through a surface. By default this command computes the mass and particle flow rates for all particles passing through, but can be set to compute only particles in a specific particle_group.

If the delete_atoms keyword is set to yes, the particles passing through the surface are deleted at the next re-neighboring step. The mass and number of deleted particles can be accessed as shown here.

Additional properties can be computed with the sum_additional_properties command. It takes a brace-enclosed list of particle properties, which can be taken from other commands. You can change the behaviour of the command with sum_additional_properties_mode. By default it is set to out, which computes particles moving in the direction of the outward_vector. It can also be set to net, which will calculate the net flow of particles, i.e. particles going in subtracted from particles moving out.

When using the keyword file information about the particles that passed the surface is stored. By default the direction, id, time, diameter, position, velocity and orientation are written to the output file. The direction here is defined as 1 (in the direction of the outward vector) or -1 (opposite the vector). Please note that this keyword does not trigger the general output of this command (massflowrate, …) to said file (see output information for more information).

If you wish to alter the default output behaviour for file you may use the file_properties keyword to specify a list of per particle properties from a command or from atom style variables. If this keyword is used, id and time are always written, followed by the desired properties.

If you wish to append data to an existing file, mode must be set to append, otherwise data will be overwritten if the simulation is restarted.

If the write_to_terminal keyword is set to yes, the per particle information is written to the screen. Since a line per particle passing the surface is generated, this can lead to a lot of screen output!

Output information

This command generates both general global output (such as mass / particle flow rate or cumulated mass / particle flow, see table), detailed global output (information about each particle that passed the face / shape) and per particle output (marker).

General global output

When using the output_settings command, mass and particle flow rate as well as cumulated mass and number of particles are automatically written to the simulation_data_aspherix.csv file (ID.mass, ID.particles, ID.mass_flow_rate, ID.particle_flow_rate, where ID is the id of the current massflow command).

With the write_to_file command these and more quantities (see table) can be written to a separate file, with the status_style command additional quantities can be added to the standard output produced by the output_settings command.

calculate massflow id cal1 mesh inface outward_vector (0, 0, -1)
write_to_file file myMassflowOutput.txt &
   string "id_time id_cal1.mass_flow_rate_out id_cal1.mass_flow_rate_in id_cal1.mass_flow_rate_net" &
   title "# time mass_flow_rate_out mass_flow_rate_in mass_flow_rate_net"
write_to_file file myMassCumulatedOutput.txt &
   string "id_time id_cal1.mass_out id_cal1.mass_in id_cal1.mass_net" &
   title "# time mass_out mass_in mass_net"

calculate massflow id cal1 mesh inface outward_vector (0, 0, -1)
status_style mode add all {id_cal1.deleted_mass, id_cal1.deleted_particles}

Full list of general global output properties of the `calculate massflow` command.
PROPERTY	Value
mass, mass_out	total mass of all particles that penetrated the surface (outwards)
particles, particles_out	total number of particles (outwards)
mass_flow_rate, mass_flow_rate_out	mass of particles divided by time (outwards, since last output)
particle_flow_rate, particle_flow_rate_out	number of particles divided by time (outwards, since last output)
deleted_mass	mass of delete particles (if `delete_particles` is active)
deleted_particles	number of delete particles (if `delete_particles` is active)
mass_in	total mass of all particles that penetrated the surface (inwards)
particles_in	total number of particles (inwards)
mass_flow_rate_in	mass of particles divided by time (since last output)
particle_flow_rate_in	number of particles divided by time (inwards, since last output)
mass_net	total mass of all particles that penetrated the surface (out-in)
particles_net	total number of particles (out-in)
mass_flow_rate_net	mass of particles divided by time (out-in, since last output)
particle_flow_rate_net	number of particles divided by time (out-in, since last output)
sum_additional_properties_entry summed value of	an entry in the sum_additional_properties list

The endings _out, _in and _net have the following meaning:

_out: counted towards the outside (determined by outward_vector or point_at_outside),
_in: counted towards the inside (opposite out), considers backflow of particles,
and _net: particles out minus particles in.

The last entry in this list refers to the values specified to the sum_additional_properties keyword. The mode for summing additional properties can be set via the sum_additional_properties_mode keyword. For output commands the additional properties can be accessed by id_ID.id_propertyName (see example below). The output_settings command will print the results of sum_additional_properties automatically to the simulation_data_aspherix.csv file.

calculate massflow id cal1 mesh inface outward_vector (0, 0, -1) &
   sum_additional_properties {id_surfaceLiquidContent} sum_additional_properties_mode net
write_to_file file myMassflowOutput.txt &
   string "id_time id_cal1.mass_flow_rate id_cal1.id_surfaceLiquidContent" &
   title "# time mass_flow_rate_out surface_liquid_content"

Detailed global output

If the file keyword is used, each processor generates a separate file that contains information about every particle that went through the face or mesh. Per default, these properties are direction, id, time, diameter, position, velocity, orientation and color (if existent) at the time when the particle is counted by the calculate massflow command.

The keyword file_properties can be used to replace the default quantities by custom ones. The names of default per-particle variables such as radius, force or velocity can be found here.

calculate residence_time id rt regions {measurement_region}
calculate massflow id mf mesh measurement_plate outward_vector (1, 0, 0) count_particles_once yes &
   file post/residence_time_particles.txt file_properties {id_rt[1], id_rt[2]}

Per-particle output

calculate massflow commands also save a per-particle vector with a marker. The output_settings command automatically adds this property to the list of particle properties that can be visualized in Paraview, Ovito, etc (name: massflow_ID). The marker can have the following values:

-1: the particle has not been near the measurement mesh / face
0: the particle has been in the proximity (neighbor list) of the mesh / face
1: the particle has been counted by the command at least once and will be counted again if it passes again (count_particles_once no)
2: the particle case been counted and will not be counted again if it passes the mesh / face again (count_particles_once yes)

Further information

Information about this command is written to binary restart files so that the summed properties are restored.

When using massflow with multispherical particles, the evaluation of the mass passing the surface is done for each sphere within the multisphere particle. Each sphere counts as a fraction of a particle, i.e. floating point number might evolve for the number of particles passing the surface if not all spheres belonging to one multisphere particle pass the surface. The weight for each sphere is calculated taking into account the possible overlap between spheres in a multisphere particle.

The keyword sum_additional_property is deprecated, please use sum_additional_properties instead.