calculate average command

Purpose

This command calculates the average of either particle or mesh properties. It can be used for the entire domain, defined regions or particle groups, or for multiple meshes (examples).

Warning

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

Syntax

calculate average keyword/value pairs

The calculate average command can either be applied for averaging 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 average is evaluated
particle_group	particle group for which the average 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 average command
final_update	Recomputes at the last step of a simulate command. available options: `yes` or `no` default: `yes`

Examples

calculate average id avgfx quantity fx
calculate average id avgmyVar quantity v_myVar
calculate average id avgfx quantity fx particle_group g1 region r1
calculate average id avg_tags quantities {id_tag1, id_tag2}
calculate average id mesh_avg meshes {plate,cad} mesh_properties {Temp,liquidContent} property_weights {area,volume}

Access the calculated values above via:

id_avgfx
id_avgmyVar
id_avg_tags[1]
id_avg_tags[2]
id_mesh_avg[1] or id_mesh_avg.Temp
id_mesh_avg[2] or id_mesh_avg.liquidContent

Description

This command calculates the average 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 do particle averaging or mesh averaging.

Particle averaging

For particle variables/data, averaging can be done 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 averaging of a single per-particle variable or command. The name of the variable/command must come after the keyword.

If you want to average 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 average id avgZvel quantity vz

variable myVar atom (x-0.1)*(x-0.1)
calculate average id avg2 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 averaging

Averaging 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 average. 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. This sum is then divided by a mesh characteristic value. These values are:

none: mesh element property is multiplied by 1, and the sum is divided by the number of mesh elements
area: the mesh element property multiplied by the area of the element, and the sum is divided by the total area of the mesh
volume: the mesh element property multiplied by the volume of the element, and the sum is divided by the total volume of the mesh

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 average 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 averaged 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.Temp, 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 average id avg1 quantity x
calculate average id avg2 quantities {y,z}
calculate average id avg3 meshes {mes1} mesh_properties {Temp,wear}
write_to_file file calculate_average_output.txt string "id_avg1 id_avg2[1] id_avg2[2] id_avg3[1] id_avg3[2]"