calculate spatial_average command

Purpose

This command calculates cell-based average of velocity, radius, volume-fraction and pressure of the particles (examples).

Syntax

calculate spatial_average keywords values

Keywords	Description
id	name for the command
particle_group	particle group this command acts on default: `all`
region	id of region in which the averaging takes place default: `simulation_domain_region_`
write_every_time	time interval in which the averaging is performed default: equal to write_output_timestep; units: [time]
cell_size_relative *	size of cells relative to largest particle diameter default: 3; range: [0,∞); units: [length]
cell_size_absolute *	size of cells in lenth units range: [0,∞); units: [length]
file	a filename pattern for the output files default: `post/id_*.vts`
properties	list of properties to compute default: `{vf,vel,stress_tensor,pressure}`
variables	list of atom-style variables to compute default: empty
variable_weights	obligatory if `variables` is set, list of weights of the variables default: empty
correct_cell_volumes	available options: `off` and `by_region`; in the latter case the cell volumes are corrected if they are intersected by the region boundary default: `off`
add_external_heatflux	adds an extra field `heatFluxExternal` to impose an additional heat flux on particles default: `no`
`interpolate`	interpolate / smooth particle contriibution across neighboring cells default: `no`

* Keywords cell_size_relative and cell_size_absolute are mutually exclusive.

Examples

calculate spatial_average
calculate spatial_average id myAvg properties {vf,vel,stress_tensor} variables {v_myVariable} variable_weights {mass}

Description

This command computes the spatial average of certain quantities on a regular grid. If issued without any other keywords, the command will compute spatial averages of the volume fraction, particle velocity, stress tensor and granular pressure over all particles. Details on the values to be computed are found below. It is recommended to use the output_settings command (and not specify write_every_time and file), as this will add the Euler Fields automatically to the aspherix_simulation.pvd file. Otherwise, the data is written to files with names post/spatial_average_*.vts. In the file names, * is replaced with the time step at which the data is written. The data can also be written using dump field/vtk/cell. Refer to this article for a brief on how to post-process this output in an automated manner.

The behavior of the calculate spatial_average command can be modified using several keywords:

The id keyword can be used to set an id for the command. The particle_group keyword sets the group the command will consider during averaging. Particles not in that group will be ignored. Using the region keyword, averaging can be restricted to a region. In that case, the region’s bounding box will be subdivided into cells.

Note

The id keyword is not mandatory, but only one spatial_average command without id can be used in a simulation to avoid collision of names.

write_every_time can be used to set the interval. If not set, the value defined by the write_output_timestep command is used.

cell_size_relative and cell_size_absolute control the size of the averaging cells. The former sets the cell size to a multiple of the maximum particle diameter in the simulation, while the latter allows to set a specific value. With either option, the cell size cannot be smaller than the largest diameter in the simulation (eg. using cell_size_relative 1). It is recommended to use a larger value, since averages with too few particles are prone to high fluctuations.

file allows to set a filename pattern for the output files. The pattern passed to calculate spatial_average must end with .vts and contain exactly one asterisk (*), which will be replaced by the time step number at which the file was written. If it is not set the default will be post/id_*.vts where id is the id of this command. correct_cell_volumes triggers whether the cell volumes are corrected if they are intersected by the region boundary.

properties, variables and variable_weights control which averages are computed by calculate spatial_average and will be explained below.

In the following table, the allowed values for properties are shown together with their way of averaging and prerequisites. The column Weight contains the way the single particle contributions are weighted.

Property name in script	Particle property	Weight	Prerequisite
`pos`	position	volume	none
`vel`	velocity	mass	none
`omega`	angular velocity	mass	none
`force`	total force	mass	none
`torque`	total torque	mass	none
`radius`	particle radius	mass	none
`vf`	volume fraction	none	none
`bulk_density`	bulk density	none	none
`temp`	temperature	mass	enable_heat_transfer or related
`n_contacts_conduction`	number of contacts	mass	enable_heat_transfer with `store_contact_data yes`
`contact_area_conduction`	contact area	mass	enable_heat_transfer with `store_contact_data yes`
`wall_heattransfer_coeff`	wall heat transfer coefficient	mass	enable_heat_transfer with `store_contact_data yes`
`stress_tensor`	stress tensor	cell volume	requires calculation of `vel`
`pressure`	pressure	cell volume	requires calculation of `stress_tensor` and `vel`

In addition to the predefined properties listed above, calculate spatial_average can compute averages of atom-style variables via the variables and variable_weights keywords. The user is required to pass a list of variables in the form of {v_myVar1,v_myVar2,....} via variable and a list of respective weighing types to variable_weights. For the latter, allowed types are none, radius, rsq, volume, mass and cell_volume, which stand for no weighing (simple arithmetic average), weighing by radius, squared radius, particle volume and particle mass, respectively.

Note

correct_cell_volumes does not affect variables scaled by none, radius or rsq

Note that the velocity is Favre (i.e., mass) averaged, whereas the radius is arithmetically averaged. To calculate the stress, this command internally uses a compute stress/atom. It includes the convective term correctly for granular particles with non-zero average velocity (which is not included in compute stress/atom) The stress tensor contribution from the generic particle $k$ reads

$S_{ij}^k =- \left[m_k \left(v_{k,i}-\bar{v}_{k,i} \right)\left(v_{k,j}-\bar{v}_{k,j} \right) + \sum_{n=1}^{N_p} \frac{r_{k,i} F_{k,i} + r_{n,j} F_{n,j}}{2} \right] \delta_{i,j}$

where $i$ and $j$ indicate the tensor components, $\bar{v}_i$ is the (cell-based) average velocity and $m_k$ is the mass of particle $k$ . The first term is the kinetic energy contribution from particle $k$ , while the second term is a pairwise energy contribution where $n$ loops over the $N_p$ neighbors of particle $k$ , $r_{k,i}$ and $r_{n,j}$ are the positions of the two particles in the pairwise interaction, and $F_{k,i}$ and $F_{n,j}$ are the forces on the two particles resulting from the pairwise interaction.

Note

Forces originating from a cohesion model bond are fully taken into account when computing the stress tensor.

Volume fractions and stresses are calculated based on the assumption of a structured (equidistant regular) grid, so volume fractions and stresses near walls that are not aligned with the grid will be incorrect if the cell volume is not corrected. If values near a wall are important, you can use a region mesh/vtk that aligns with the wall and set correct_cell_volumes to region.

If the add_external_heatflux keyword is set to yes then an additional field is added to the output which is called heatFluxExternal_avg which can be used in combination with the enable heat_transfer command to add an external heat flux that is distributed to particles.

Output information

This command calculates a defined set of Eulerian fields.

When using the output_settings command and if write_every_time` and file are not specified, the information is automatically added to the aspherix_simulation.pvd file (recommended). If any of the keywords are defined, seperate vts files will be written.

Alternatively, the dump euler/vtk/custom command can be used to write the data to files, using the command id. Note that the values can only be accessed on time levels that are multiples of write_every_time since that is when calculations are performed.

calculate spatial_average command

Syntax

Examples

Description

Output information

Related commands