Tools

Introduction

Since version 2.0, AQUAgpusph is designed like a sandbox, such that the tools that will be used to perform the simulation can be selected "on the fly". 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.

Defining new tools

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

<Tools>
    <!-- ... -->
</Tools>

The new tools will be defined between the new "Tools" opened section. Each tool is defined as follows:

<Tool name="NAME" action="ACTION" type="TYPE">

Where ACTION, NAME and TYPE should be conveniently set. Depending on the selected "action" and "type" some other specific attributes will be required.

Name

The name of the variable can be arbitrary selected. If the XML file was included providing a prefix, the final name of the tool will be the concatenation of the prefix and the provided name.

Actions

Actions can be used to specify the position of the kernel we are defining. The possibilities are described in the following subsections:

add

The new tool will be appended at the end of the list of tools. No additional attributes are required.

insert

The new tool will be inserted in a specific position. One of the following attributes should be provided:

• at="ID" : The tool will be placed in the position ID.
• before="REF" : The tool will be placed before the already existing tool REF.
• after="REF" : The tool will be placed after the already existing tool REF.
• before_prefix="REF" : The tool will be placed before the already existing tool PREFIXREF, with PREFIXREF is the resulting text of joining the Prefix passed when the XML file was included, and REF.
• after_prefix="REF" : The tool will be placed after the already existing tool PREFIXREF, with PREFIXREF is the resulting text of joining the Prefix passed when the XML file was included, and REF.

remove

Then the tool with the provided name will be removed. No additional attributes are required.

replace

Then the tool with the provided name will be replaced with the new one.

Type

Several types of tools can be used:

kernel

An OpenCL kernel will be executed in the position specified. The attribute path="OpenCLSourceCodePath" should be provided, replacing OpenCLSourceCodePath by the OpenCL source code location.

The OpenCL code must have a valid __kernel void main() method (entry point name setting is not supported). AQUAgpusph is detecting automatically the input variables of the kernel by its name, which should match with the defined ones

copy

Copy one Array variable into another one (both should have the same type and length). The attributes in="OrigVar" and out="DestVar" must be provided, where OrigVar and DestVar are the names of the origin and source Array variables respectively.

This tool is designed to work with Array variables, in order to copy Scalar variables use set_scalar tool.

set

Set a Scalar variable to each component of an Array variable (of the same type). The attributes in="Array" and value="Scalar" must be provided, where Array is the Array to be filled and Scalar is the value to set.

This tool is designed to work with Array variables, in order to set Scalar variables use set_scalar tool.

set_scalar

Set a Scalar variable value. The attributes in="Scalar" and value="Value" must be provided, where Scalar is the Scalar to be changed, and Value is the expression to be evaluated and set. The value is evaluated using libmatheval, such that you can use other Scalar variables, referring to their name (followed by an underscore "_" and the component "x, y, z, w" if it is a vectorial scalar).

reduction

Reduces an Array to one single Scalar variable using the specified expression (prefix sum is a particular case of reduction). The attributes in="Array", out="Scalar" and null="Null" must be provided, where Array is the Array to be reduced, Scalar is the result, and Null is the value considered as null, i.e. A value reduced with that will result in the same value.

python

Imports a Python script, calling its main() method each time step. The attribute path="PythonSourceCodePath" should be provided, replacing PythonSourceCodePath by the Python script source code location.

You can read and write all the Variables defined for the simulation, for instance:

import aquagpusph as aqua
var = aqua.get("var")
aqua.set("var", var)

All the variables are 32 bits NumPy types:

• int, ivec, ivec2, ivec3, ivec4: numpy.int32
• unsigned int, uivec, uivec2, uivec3, uivec4 : numpy.int32
• float, vec, vec2, vec3, vec4: numpy.float32

Regarding the size, the Scalar variables have a size equal to the number of components (for instance float has size 1, while vec4 has size 4). On the other hand the Array variables are 2 dimensional NumPy arrays with the same length of the variable, and the same number of components of the type (for instance a vec4 array, with a length N, has a size (N, 4))

link-list

It is a little bit special method which is computing the minimum and maximum positions r_min, r_max, the cell of each particle icell, the permutation arrays (which allows to sort/unsort the particles data by its cell) id_sorted, id_unsorted, and the first particle found in each cell ihoc.

• The cells and head of chains (icell, ihoc) are already sorted by cells.
• id_unsorted cannot be used to get the original index of the sorted particles, but the index in the previous time step. To get original index see the id_inverse.xml preset.