calculate sum command

Purpose

This command calculates the sum of one or more per-particle style variables in the entire simulation domain / for a group of particles or the sum of one or more mesh properties for one or meshes (examples).

Warning

GPU support for this command has not been tested and may not work as expected.

Syntax

calculate sum keyword/value pairs

The calculate sum command can either be applied for summing particle or mesh properties.

Keywords	Description
quantity *	variable or command that computes a per-particle value
quantities *	brace-enclosed list of variables or commands that compute per-particle values
region	region in which the sum is evaluated
particle_group	particle group for which the sum is evaluated

* The keywords quantity and quantities are mutually exclusive.

Keywords	Description
meshes	brace-enclosed list of mesh ids or `all` for all meshes available options: `{mesh1,mesh2,etc}` or `all`
mesh_properties	brace-enclosed list of mesh properties
property_weights	brace-enclosed list of weights for each mesh property available options: `area` or `volume` default: `none`

Keywords	Description
id	user-assigned name for the calculate sum command
final_update	Recomputes at the last step of a simulate command. available options: `yes` or `no` default: `yes`

Examples

calculate sum id sumfx quantity fx
calculate sum id sumMyVar quantity v_myVar
calculate sum id sumfx quantity fx particle_group g1 region r1
calculate sum id sum_tags quantities {id_tag1, id_tag2}
calculate sum id mesh_sum meshes {plate,cad} mesh_properties {Temp,liquidContent} property_weights {area,volume}

Access the calculated values above via:

id_sumfx
id_sumMyVar
id_sum_tags[1]
id_sum_tags[2]
id_mesh_sum[1] or id_mesh_sum.Temp
id_mesh_sum[2] or id_mesh_sum.liquidContent

Description

This command calculates the sum of a per-particle style variable, a command that computes per-particle data, or a mesh property of a surface mesh.

Note that the command can sum particle or mesh properties exclusively.

Particle property summing

For particle variables/data, sums can be calculated for:

the entire simulation domain, or
in a region defined by the region keyword, or
in a group of particles defined by the particle_group keyword.

The quantity keyword allows the summing of a single per-particle variable or command. The name of the variable/command must come after the keyword.

If you want to sum more than one variable/command, the quantities keyword can be used. The variables/commands must come after the keyword within curly braces.

Global per-particle variables that are provided by Aspherix (e.g., positions x, y, z, forces fx, fy, fz, velocities vx, vy, vz, …) can be used directly, user-defined variables must be accessed with ‘v_VARNAME’, where VARNAME is the user-defined name of the variable.

calculate sum id sumZforce quantity fz

variable myVar atom fx*fx
calculate sum id sumSqXforce quantity v_myVar

Alternatively, if you have a command that computes a per-particle scalar or vector, you can also use this. To do so prepend the commands id with id_, e.g. id_myCommandId. If the command computes a per-particle vector, you must specify the component, e.g. id_myVectorCommandId[1].

Mesh property summing

Summing of mesh properties can be done for the meshes defined in the meshes keyword. The keyword accepts two formats for the value:

A list of mesh names enclosed in braces: {mesh1, mesh2}
The value all, which makes the command apply to all meshes in the domain.

The keyword mesh_properties defines the properties to be summed up. This applies to all meshes defined in the meshes keyword. The mesh_properties keyword takes a list of properties enclosed by braces.

The properties can be weighted by using the property_weights keyword. The weighting is done by multiplying the properties in each mesh element by an element characteristic value, and summing the product for all mesh elements. These values are:

none: no scaling factor is applied
area: the mesh element property is multiplied by the area of the element
volume: the mesh element property multiplied by the volume of the element

The mesh element volume is defined as the mesh element area times the mesh element thickness (wall thickness). The mesh thickness can be defined via the mesh_module heattransfer or mesh_module liquidtransfer commands. A thickness of 1 will be used if it was not set explicitly.

The final_update keyword will 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 sum command produces a global scalar (when using quantity) or vector (when using quantities or meshes). When using the output_settings command, the results are automatically written to the simulation_data_aspherix.csv / result_monitor.txt file (names same as in access information below).

The summed property for a command with id CMDID can be accessed by id_CMDID, the components of the vector for properties and meshes by id_CMDID[1], id_CMDID[2], etc. For meshes also dot-access via the property name is possible (e.g., id_CMDID.wear, id_CMDID.area, etc).

With the write_to_file command the information 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 sum id sum1 quantity fx
calculate sum id sum2 quantities {fy,fz}
calculate sum id sum3 meshes {mes1} mesh_properties {Temp,wear}
write_to_file file calculate_sum_output.txt string "id_sum1 id_sum2[1] id_sum2[2] id_sum3[1] id_sum3[2]"