| Cube' Derived Metrics (CubeLib 4.8.2, revision f48dbd0f) Introduction in CubePL and Performance Analysis using Cube's Derived Metrics

- Contents

Syntax of CubePL

# Syntax step by step

This chapter introduced the CubePL syntax of the most common programming structures.

## Expressions

### Constants

Any constant expression is an `expression`. eg. 123.0, "someString"

### Arithmetical Expressions

Common mathematical notation of an arithmetical expression is valid in CubePL. Any arithmetical expression is an `expression`. eg. 123.0 + 23.6, sin(23)

### Boolean Expressions

Common literal notation of a boolean expression is valid in CubePL. Any boolean expression is an `expression`.

[expression] or|and|xor [expression]

or

not [expression]

Any `expression` can be a term of a boolean expression. Non zero value is observed as `TRUE`, zero value is `FALSE`.

### Function call expressions

Function calls have the following syntax:

name ( [expression ] )

## Lambda function (In-place function definition)

To define a function in-place, one uses the following syntax:

{
[statement];
[statement];
...
return [expression];
}

In-place definition of a function is an `expression`. It means, it can appear everywhere, where one can use an `expression`.

## Control structures

Control structures like if-else or while are `statements`.

### Condition IF-ELSE

One can execute series of statements under a condition using the short form of the `if` statement:

if ( condition )
{
[statement];
[statement];
...
}

or full form with `else` :

if ( condition )
{
[statement];
[statement];
...
}
else
{
[statement];
[statement];
...
}

`condition` is a boolean `expression`

### Loop WHILE

One can execute a series of statements as long as a condition is true using the `while` statement:

while ( condition )
{
[statement];
[statement];
...
}

Sequence of statements will be executed till condition is not fulfilled, max 1000000000 times.

## Variables

CubePL allows to work with memory, by using variables. All variables are multi-typed:

- In string context value of a numeric variable is presented in string format.
- In numerical context a string variable is converted to its numerical representation, if possible. Otherwise it is 0.

All variables are arrays. Indexless access to the variable assummes mutually index value 0.

### User defined Variables

The user can define a variable using the syntax:

${ name } = [expression];

or

${ name }[index] = [expression];

Currently its name is a fixed string of characters. In later versions of CubePL it will allow any `expression`.

Example of a string context :

${name} seq "STRING"

Example of a numeric context :

${name} >= 0.34

Example of an array access to the variable :

${name}[ ${i} ] >= 0.34

Access to the variable is an `expression`.

Index for the access to the value is also an `expression`.

### Predefined Variables

Cube provides a set of predefined variables for every calculation, which values are independend. Following predefined variables do contain the general information about the cube:

Predefined variable | Explanation
cube::#mirrors | Number of mirrors in cube file
cube::#metrics | Number of metrics in cube file
cube::#root::metrics | Number of root metrics in cube file
cube::#regions | Number of regions in cube file
cube::#callpaths | Number of call paths in cube file
cube::#root::callpaths | Number of root call paths
cube::#locations | Number of locations in cube file
cube::#locations::void | Number of void locations in cube file
cube::#locations::nonvoid | Number of nonvoid locations in cube file
cube::#locationgroups | Number of location groups in cube file
cube::#locationgroups::void | Number of void location groups in cube file
cube::#locationgroups::nonvoid | Number of nonvoid location groups in cube file
cube::#stns | Number of system tree nodes in cube file
cube::#rootstns | Number of root system tree nodes in cube file
cube::filename | Name of the cube file

CubePL engine defines a set of variables, which do depend on an index, their "id". Using call `sizeof(...)` one can run over them and inspect within CubePL expression.

cube::metric::unit::name | Unique name of the metric
cube::metric::disp::name | Display name of the metric
cube::metric::url | URL of the documentation of the metric
cube::metric::description | Description of the metric
cube::metric::dtype | Data type of the metric
cube::metric::uom | Unit of measurement of the metric
cube::metric::expression | CubePL expression of the metric
cube::metric::initexpression | CubePL initialisation expression of the metric
cube::metric::parentd::id | ID of the parent of the metric
cube::metric::#children | Number of children in the metric

cube::callpath::mod | Module of the call path
cube::callpath::line | File line of the call path
cube::calleeid | ID of the callee region
cube::callpath::#children | Number of children in the call path
cube::callpath::parent::id | ID of the parent callpath

cube::region::name | Name of the region
cube::region::mangled::name | Mangled name of the region
cube::region::paradigm | Name of the paradigm of the region
cube::region::role | Name of the role the region is playing within the paradigm
cube::region::url | URL with the description of the region of the call path
cube::region::description | Description of the region of the call path
cube::region::mod | Module of the region of the call path
cube::region::begin::line | Begin line of the region of the call path
cube::region::end::line | End line of the region of the call path

cube::stn::name | Name of the system tree node
cube::stn::class | Class of the system tree node
cube::stn::description | Description of the system tree node
cube::stn::#children | Number of children (other system tree nodes) of the system tree node
cube::stn::#locationgroups | Number of location groups of the system tree node
cube::stn::parent::id | ID (among all system tree nodes) of the parent of the system tree node
cube::stn::parent::sysid | ID (global) of the parent of the system tree node

cube::locationgroup::name | Name of the location group
cube::locationgroup::rank | Rank of the location group
cube::locationgroup::type | Type of the location group
cube::locationgroup::void | Is the this location group void?
cube::locationgroup::#locations | Number of locations of the location group
cube::locationgroup::parent::id | ID (amoung all system tree nodes) of the parent system tree node
cube::locationgroup::parent::sysid | ID (global) of the parent system tree node

cube::location::name | Name of the location
cube::location::rank | Rank of the location
cube::location::type | Type of the location
cube::location::void | Is the this location void?
cube::location::parent::id | ID (among all location groups) of the parent location group
cube::location::parent::sysid | ID (global) of the parent location group

CubePL engine sets a series of context sensetive variables, which value depends on the paramaters, for which the derived metric is being calculated. Their value can be used to refer to the values of context insensitive variables described above:

calculation::metric::id | ID of the metric, being calculated
calculation::callpath::id | ID of the callpath, for what is the metric being calculated
calculation::callpath::state | State of the callpath (inclusive=0, exclusive=1, same=2), for what is the metric being calculated
calculation::callpath::#elements | Number of selected callpath, for which is metric being calculated. Usually bigger than 1 only for postderived metrics
calculation::region::id | ID of the region, for what is the metric being calculated
calculation::region::#elements | Number of selected regions, for which is metric being calculated. Usually bigger than 1 only for postderived metrics
calculation::sysres::id | ID (local within system resource type) if the sysem resource, for what is the metric being calculated
calculation::sysres::sysid | ID (global) if the sysem resource, for what is the metric being calculated
calculation::sysres::kind | Type of the system element: `0 = unknown` `5 = system tree node` `6 = location group` `7 = location`
calculation::sysres::#elements | Number of selected system tree elements, for which is metric being calculated. Usually bigger than 1 only for postderived metrics

## Different ways to refer an another metric

### Context sensitive reference to another metric

To use values of another metric in the same calculation context, one uses syntax:

metric::[uniq_name]( modificator, modificator )

or

metric::[uniq_name]( modificator)

or

metric::[uniq_name]()

There are three version of this call:

1. with two arguments (call path and system);
2. with one argument (call path);
3. with no argument(an arguments takes as '*').

`modificator` specifies flavor of the calculation: `i` - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an `expression`.

### Context insensitive reference to another metric

To use values of another metric in the some fixed calculation context (e.g. aggregated over threads), one uses syntax:

metric::fixed::[uniq_name]( modificator, modificator )

or

metric::fixed::[uniq_name]( modificator)

or

metric::fixed::[uniq_name]()

There are three version of this call:

1. with two arguments (call path and system);
2. with one argument (call path);
3. with no argument(an arguments takes as '*').

`modificator` specifies flavor of the calculation: `i` - inclusive, e - exclusive, * - same like in calculation context.

Metric reference is an `expression`.

### Direct reference to another metric

To use values of another metric with an specific call path id and system resource id (!), one uses syntax:

metric::call::[uniq_name]( callpath id, modificator, sysres id, modificator )

or

metric::call::[uniq_name]( callpath id, modificator )

There are two version of this call:

1. with four arguments (call path and system); - Only callculation of an inclusive or exclusive value is performed
2. with one argument (call path); - Aggragation over system tree is performed additionally to the calculation of the inclisive or exclusive value for the calltree id

`modificator` specifies flavor of the calculation: `i` - inclusive, e - exclusive.

Metric reference is an `expression`.

Note that "sysres id" is a global identificator and can be refered using ${calculation::sysres::id}.

### Definition of an encapsulated calculation within CubePL expression using metrics of Cube.

One special mechanis of CubePL processing engine allows some level of calculation separation. A derived metric can be created within another CubePL expression. Such "ghost" metric gets its name and properties and exists inside of the cube object as a casual metric. Only difference to the casual metric is in the fact that ghost metric is not visible in GUI and tools and is not stored inside of the metric tree of the cube file.

One can refer such metric as a casual metric using metric references (see 'Context sensitive reference to another metric' , 'Context insensitive reference to another metric' and 'Direct reference to another metric' ).

Example for definition of such metric :

cube::metric::nvisitors(e)
<<
{
${return}=0;
if ( ${cube::locationgroup::void}[${calculation::sysres::id}] != 1)
{
if (metric::visits()>0 )
{
${return} = 1;
};
};
return ${return};
}
>>;
${visitors} = metric::fixed::nvisitors(e);

where

cube::metric::prederived::nvisitors(e)

gives a type (prederives, exclusive) and unique name (nvisitors) of this metric. Unique name is used then later to refer to this metric via

${visitors} = metric::fixed::nvisitors(e);

There are kinds of metrics, which can be defined on such manner:

1. `cube::metric::prederived::name(e)` - An exclusive prederived metric with the name `name`;
2. `cube::metric::prederived::name(i)` - An inclusive prederived metric with the name `name`;
3. `cube::metric::postderived::name` - A postderived metric with the name `name`.

Notice that once the metric with some unique name created it exists whole lifetime of the cube object. Therefore one can refer to some somewhere previously defined ghost metric from any following it CubePL expressions.

Ghost Metric definition is a `statement`.

### Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an initialisation phase for previously created ghost metric. For that purpose one uses expression `cube::init::metric::[name]`. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::init::nvisitors
<<
{
global(nvisitors);
}
>>;

where

cube::init::metric::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a `statement`.

### Definition of an initialization expression for ghost metrics within CubePL expression.

One can specify within of a CubePL expression an aggregation operator "+" or "-" for previously created ghost metric. For that purpose one uses expression `cube::metric::plus::[name]` or `cube::metric::minus::[name]`. Notice that named metric should be know by the moment of compilation of the CubePL expression.

Example for definition of such metric :

cube::init::metric::plus::nvisitors
<<
max( arg1, arg2)
>>;

or

cube::init::metric::minus::nvisitors
<<
min( arg1, arg2)
>>;

where

cube::init::metric:plus::nvisitors

or

cube::init::metric:minus::nvisitors

uses an unique name (nvisitors) of the metric.

Definition of the initialisation phase of a metric is a `statement`.

# Grammar of CubePL

Here will be a full grammar of CubePL expressions (later).

|  | Copyright © 1998–2022 Forschungszentrum Jülich GmbH, Jülich Supercomputing Centre Copyright © 2009–2015 German Research School for Simulation Sciences GmbH, Laboratory for Parallel Programming