Variables

Introduction

Since version 2.0, AQUAgpusph is designed like a sandbox, such that the variables that will be used by the code can be defined "on the fly" for each simulation. Anyway, in order to do more accessible the code, some Presets are provided "out of the box", which are defining Variables, Definitions, Tools and Reports to carry out specific actions.

To avoid errors the variables definition is done in the following order:

1. All the XML files are parsed, and the variables declared.
2. The scalar variables values are evaluated in the way they were declared.
3. The array variables lengths are evaluated in the way they were declared.

Therefore, the user must ensure that the dependencies of each variable are satisfied before evaluating its value/length. If a variable is set several times, just the last instance will be used.

Defining new variables

In order to define new variables an specific section should be opened in the simulation definition XML input files (take a look on the examples to learn more about this):

<Variables>
    <!-- ... -->
</Variables>

The new variables will be defined between the new "Variables" opened section. Each variable is defined as follows:

<Variable name="NAME" type="TYPE" length="LENGTH" value="VALUE">

Where NAME, TYPE, LENGTH and VALUE should be conveniently set as it is described in the following subsections.

Name

The name of the variable can be arbitrary selected, being mindful that the name should be ISO C compliance (otherwise it will not be usable in OpenCL codes).

Type

The valid types of the variables can be divided in 2 main classes:

Array

Array variables are lists of values with a predefined #Length. These variables are mainly oriented to be used in OpenCL, however they can be manipulated with Python (as NumPy arrays). For the array variables setting a #Value field, or setting it inside another variable #Value field either, will result in an undefined behavior.

The valid types for array variables are:

• int*: List of signed integers
• ivec2*: List of signed integer 2D vectors (xy components)
• ivec3*: List of signed integer 3D vectors (xyz components). In general using this type is not recommended.
• ivec4*: List of signed integer 4D vectors (xyzw components)
• ivec*: ivec2* in the 2D version, ivec4* in the 3D version
• unsigned int*: List of unsigned integers
• uivec2*: List of unsigned integer 2D vectors (xy components)
• uivec3*: List of unsigned integer 3D vectors (xyz components). In general using this type is not recommended.
• uivec4*: List of unsigned integer 4D vectors (xyzw components)
• uivec*: uivec2* in the 2D version, uivec4* in the 3D version
• float*: List of float numbers
• vec2*: List of float 2D vectors (xy components)
• vec3*: List of float 3D vectors (xyz components). In general using this type is not recommended.
• vec4*: List of float 4D vectors (xyzw components)
• vec*: vec2* in the 2D version, vec4* in the 3D version

Scalar

Scalar variables, in front of array variables, are consisting in just one element (and therefore #Length is ever equal to 1).

The valid types for scalar variables are:

• int*: signed integer
• ivec2*: signed integer 2D vector (xy components)
• ivec3*: signed integer 3D vector (xyz components). In general using this type is not recommended.
• ivec4*: signed integer 4D vector (xyzw components)
• ivec*: ivec2 in the 2D version, ivec4 in the 3D version
• unsigned int*: unsigned integer
• uivec2*: unsigned integer 2D vector (xy components)
• uivec3*: unsigned integer 3D vector (xyz components). In general using this type is not recommended.
• uivec4*: unsigned integer 4D vector (xyzw components)
• uivec*: uivec2 in the 2D version, uivec4 in the 3D version
• float*: float number
• vec2*: float 2D vector (xy components)
• vec3*: float 3D vector (xyz components). In general using this type is not recommended.
• vec4*: float 4D vector (xyzw components)
• vec*: vec2 in the 2D version, vec4 in the 3D version

Length

Just for array variables, it is used to define the number of elements of the array. If a float value is provided it will be converted to an integer one.

This field is evaluated using libmatheval, such that you can use scalar variables referring to their name (followed by an underscore "_" and the component "x, y, z, w" if it is a vectorial scalar).

Value

Just for scalar variables, it is used to define the number of elements of the array. The resulting value provided will be converted to the required type. In order to set vectorial variables values, each component should be separated by a comma ",".

This field is evaluated using libmatheval, such that you can use scalar variables referring to their name (followed by an underscore "_" and the component "x, y, z, w" if it is a vectorial scalar).

Default variables

Some variables are defined by default by AQUAgpusph (before any other definition is parsed from the XML files):

NAME	TYPE	LENGTH	DESCRIPTION
dims	unsigned int	1	Number of dimension, i.e. 2 for the 2D version, 3 for the 3D version
t	float	1	Simulation time $t$ . It is 0 by default, but can be modified to start the simulation from a different $t_{0}$
dt	float	1	Time step ${\displaystyle\Delta t}$ . It should be provided by the user in the XML definition files
iter	unsigned int	1	Index of the time step to being computed. It is intended that this value is not manually set
n_sets	unsigned int	1	number of particles sets, and therefore is automatically computed and should not be manually set
N	unsigned int	1	Number of particles (including boundaries). It is the sum of the number of particles in each particles set, and therefore is automatically computed and should not be manually set
n_radix	unsigned int	1	The first value, bigger or equal to N, which is power of 2
n_cells	uivec4	1	Number of cells in each direction. It is automatically computed and should not be manually set
support	unsigned int	1	Support of the selected kernel. It is usually 2, but some specific kernels may use 3
id	unsigned int*	N	Identifier of each particle (it can be used to identify the original index of each particle after sorting them)
r	vec*	N	Position of the particles ${\displaystyle{\mathbf{r}}}$
iset	unsigned int*	N	Index of the Particles set each particle belongs
id_sorted	unsigned int*	N	Permutations from unsorted space to sorted space
id_unsorted	unsigned int*	N	Permutations from sorted space to unsorted space
icell	unsigned int*	N	Cell where each particle is placed in
ihoc	unsigned int*	n_cells	First particle found in each cell.