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 and Tools 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.

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).