Formulas in moodss

Contents:

1. About this document

This document contains general and reference information to help the user create formulas from data cells coming from modules loaded in the moodss application. Once created, the formulas are displayed in formulas tables, described in the general moodss documentation.
This document particularly covers the mathematical expressions that can be used in formulas, including their syntax and the various available operators and functions.

2. Expressions

In moodss and moomps, a formula consists of a user defined name, comments and a mathematical expression made of data cells, mathematical operators and functions. The expression is the core of the formula.

An expression consists of a combination of operands (data cells, numbers, mathematical functions, ...), operators (+, -, ...), and parentheses. White space may be used between the operands and operators and parentheses; it is ignored when the result of the formula is internally calculated.

For example, the screen shot below shows the expression used to calculate the memory usage of a computer in percent, obtained by dividing the used memory by the available memory and multiplying the result by 100.

basic memory usage expression

You may notice that something is wrong with this expression, since its result seems to be 0, unexpected since there is some actual memory used. What is happening is that the internal calculation engine (called the calculator in this document), when possible, interprets the operands as integer values.
What we want in this case is to force floating-point numbers calculations, which can be achieved by using a math function to convert one of the memory operands to floating-point, as shown below.

floating-point memory usage expression

We will now cover in more details all the available features of expressions.

2.1. Operands

Where possible, operands are interpreted as integer values (such as 123), else treated as floating-point numbers (such as 12.345) if that is possible.
An operand may be directly input as a constant value by the user (such as the 100 multiplier in the screen shots above), or dropped from any source of data cells (such as used memory and available memory).

Conversion among internal representations for integer and floating-point operands is done automatically as needed. For arithmetic computations, integers are used until some floating-point number is introduced, after which floating-point is used. For example, the result of 5/4 is 1, while 5/4.0 gives 1.25.
Floating-point results are always displayed and used with a . (dot) or an e so that they will not look like integer values. For example, the result of 20.0/5.0 is 4.0, not 4.

An operand may also be a mathematical function whose arguments have any of the above forms for operands, such as double(127544) (see the functions section).

2.2. Operators

The valid operators are listed below, grouped in decreasing order of precedence:

2.3. Functions

The following specific functions take strictly one data cell (dragged and dropped in moodss formulas interface) as sole argument. They internally use the value of the data cell at the last update of the formula, which means that they return an undefined value the first time they are invoked, since, obviously, there was no previous value for the data cell.

Notes:

There is also a special specific function which returns the time difference between updates:

The following mathematical functions are also supported in expressions. They work solely with floating-point numbers unless otherwise noted:

2.4. Error handling

Error handling is handled by the internal calculator, and most messages are easy to understand, but careful reading and thorough thinking is always useful...
Note: for experts, it is actually the expr command in a safe Tcl interpreter that reports errors.

Some typical error messaged are explained here (please request new entries as you see fit):

3. Formatting

(to be implemented)

4. Advanced usage

Operands integer values may be specified in decimal (the normal case), in octal (if the first character of the operand is 0), or in hexadecimal (if the first two characters of the operand are 0x).

Floating-point numbers may be specified in any of the ways accepted by an ANSI-compliant C compiler (except that the f, F, l, and L suffixes are not permitted). For example, all of the following are valid floating-point numbers: 2.1, 3., 6e4, 7.91e+16. If no numeric interpretation is possible, then it is an error and the result of the expression is ?.

The following operator is also valid:

The following random functions are also supported in expressions:

Finally, for users fluent in the Tcl language, you may use all the features of the expr command, including strings as operands, as the formula text is directly passed to the expr command, after filling the values of the data cells of course.