XML.Variables

Variables

AQUAgpusph can be pictured as a sandbox where the user can define a set of variables and a set of tools to process them. That is indeed the way AQUAgpusph achieves its high level of modularity.

The user can define the variables to be operated by the the tools adding <Variables> sections on the XML input files, and <Variable> elements within such sections.

Following an example of an XML file defining 2 variables:

<?xml version="1.0" ?>
<sphInput>
    <Variables>
        <Variable name="s" type="vec" value="0.0, 0.0, 0.0, 0.0" />
        <Variable name="a" type="float*" length="N" />
    </Variables>
</sphInput>

The variables are featured by their name and type.

Name

It is the unique identifier of the variable, setted by the name attribute. The naming convention shall follow the C99 rules, as well as some other rules:

• Names can contain letters, digits and underscores
• Names must begin with a letter or an underscore
• Names are case-sensitive
• Names cannot contain whitespaces or special characters
• Reserved words --such as int-- cannot be used as names
• Names cannot start with the __ prefix
• Names cannot end with the _x, _y, _z, _w, _yx, _yy, _yz, _yw, _zx, _zy, _zz, _zw, _wx, _wy, _wz and _ww suffixes.

Since the name is a unique identifier, <Variable> elements with already taken variable names will replace those already defined variables. Along this line, no check on types compatibility will be done.

Type

The variable type is set by the mandatory type attribute. The following basic types can be considered:

• int: 32 bits signed integer
• long: 64 bits signed integer
• unsigned int: 32 bits unsigned integer
• unsigned long: 64 bits unsigned integer
• float: 32 bits floating point number
• double: 64 bits floating point number
• ivec2, ivec3, ivec4, ivec8: Union of 2, 3, 4 and 8 int respectively
• lvec2, lvec3, lvec4, lvec8: Union of 2, 3, 4 and 8 long respectively
• uivec2, uivec3, uivec4, uivec8: Union of 2, 3, 4 and 8 unsigned int respectively
• ulvec2, ulvec3, ulvec4, ulvec8: Union of 2, 3, 4 and 8 unsigned long respectively
• vec2, vec3, vec4, vec8: Union of 2, 3, 4 and 8 float respectively
• dvec2, dvec3, dvec4, dvec8: Union of 2, 3, 4 and 8 double respectively
• ivec: ivec2 in 2D, ivec4 in 3D
• lvec: lvec2 in 2D, lvec4 in 3D
• uivec: uivec2 in 2D, uivec4 in 3D
• ulvec: ulvec2 in 2D, ulvec4 in 3D
• vec: vec2 in 2D, vec4 in 3D
• dvec: dvec2 in 2D, dvec4 in 3D
• matrix: 2x2 (2D) or 4x4 (3D) matrix of float. This type cannot only be defined as an array (see below).

In AQUAgpusph scalar and array variables can be defined.

Scalars

Scalar variables are defined setting the type as it is described above, in contrast to arrays which use the * prefix. The main feature of the scalar variables is that they are allocated and handled on the host. Typically these variables represent auxiliar numbers --like iterators--, constants --like the gravity--, or integral values --like the total energy--.

When a scalar is declared, the value attribute shall be provided with the initial value of the variable. In case of variable types with more than one component, comma separated values have to be provided. See the following example where the gravity acceleration is defined for a 3D simulation:

<?xml version="1.0" ?>
<sphInput>
    <Variables>
        <Variable name="g" type="vec" value="0.0, 0.0, 9.81, 0.0" />
    </Variables>
</sphInput>

Math expressions are allowed to compute the value. For instance the following XML input defines the variables dr and hfac, and from them the h variable is computed:

<?xml version="1.0" ?>
<sphInput>
    <Variables>
        <Variable name="dr" type="float" value="0.1" />
        <Variable name="hfac" type="float" value="2.0" />
        <Variable name="h" type="float" value="hfac * dr" />
    </Variables>
</sphInput>

Arrays

Arrays are declared adding the * prefix to the variable type. In contrast to scalars, array variables are allocated and handled by the computational device, which has a theoretical larger computational capability. In general these variables represent properties of the particles --like the density or the velocity--.

The array variables require the attribute length, which determines the number of components of the array. Some scalar varaibles can be considered to set the length of the array. The most important ones are N --so a component per particle is added-- and n_sets --so a component per particles set is added--.

On the following example the velocity field of the particles is defined:

<?xml version="1.0" ?>
<sphInput>
    <Variables>
        <Variable name="u" type="vec*" length="N" />
    </Variables>
</sphInput>

The length of the array is in general constant, although it is possible to create installable C++ tools which might modify the length of a variable. ihoc is the very only example of a variable changing its length on AQUAgpusph.

To maximize the performance on AQUAgpusph, the computational doamin is divided on cells of $2 h$ length. The particles are then sorted according to the index of the cell where they are located (this is actually a common practice on the vast majority of the SPH codes optimized for GPUs). It is hereby quite normal to see, all along the AQUAgpusph presets, that the array variables are declared twice, adding a _in suffix the second time. Those copies are used to backup and sort the variables.