Expressions

Almost every field in GibbsStudio that takes a number will also take an expression. A table column, a plot axis, a parameter’s value, a fitting residual, a plot title, a filter – all of them are evaluated rather than read, and all of them use the same small language.

This chapter is the reference for it. Parameters covers where parameters come from; this covers what you can write with them.

Three ways to name a value

Which form you use depends on what the value is and where you are writing it.

A parameter, in a GibbsStudio field – by its bare name:

porosity * 2
log10(k_calcite)

A results field, in anything that reads results – between hashes:

#Ca# * 1000
#si_Calcite# - #si_Dolomite#

The hashes exist because result fields are named by the chemistry and not by you: si_Calcite, Fe(3), C(4), Hfo_wOH. Names like those contain brackets, signs and dots that the parser would otherwise read as arithmetic, so they are delimited instead of escaped.

A parameter, inside a PHREEQC input – in the substitution marker, since the surrounding text is PHREEQC’s syntax and not GibbsStudio’s:

@{my_param}@        the parameter's value
@{$10^C_param$}@    an expression, evaluated first

Parameters has the detail on that last form.

Where expressions are evaluated

Worth knowing, because it decides what is in scope:

  • Parameter values see other parameters.

  • Table columns, plot axes and traces, plot titles see the fields of the view they read, plus the project’s parameters.

  • Filter views see the fields of the view they filter.

  • Fitting residuals see both the results and the fitting parameters.

  • PHREEQC input substitutions see parameters only, and are evaluated before the run. Results do not exist yet.

A field that evaluates to something that is not a number – because a name is misspelled, or a division produced an infinity – is reported rather than silently dropped.

Operators and functions

Arithmetic & Assignment Operators

OPERATOR

DEFINITION

“+”

Addition between x and y. (eg: x + y)

“-”

Subtraction between x and y. (eg: x - y)

“*”

Multiplication between x and y. (eg: x * y)

“/”

Division between x and y. (eg: x / y)

“%”

Modulus of x with respect to y. (eg: x % y)

“^”

x to the power of y. (eg: x ^ y)

Equalities & Inequalities

OPERATOR

DEFINITION

== or =

True only if x is strictly equal to y. (eg: x == y)

<> or !=

True only if x does not equal y. (eg: x <> y or x != y)

<

True only if x is less than y. (eg: x < y)

<=

True only if x is less than or equal to y. (eg: x <= y)

>

True only if x is greater than y. (eg: x > y)

>=

True only if x greater than or equal to y. (eg: x >= y)

Boolean Operations

OPERATOR

DEFINITION

true

True state or any value other than zero (typically 1).

false

False state, value of exactly zero.

and

Logical AND, True only if x and y are both true. (eg: x and y)

mand

Multi-input logical AND, True only if all inputs are true. Left to right short-circuiting of expressions. (eg: mand(x > y, z < w, u or v, w and x))

mor

Multi-input logical OR, True if at least one of the inputs are true. Left to right short-circuiting of expressions. (eg: mor(x > y, z < w, u or v, w and x))

nand

Logical NAND, True only if either x or y is false. (eg: x nand y)

nor

Logical NOR, True only if the result of x or y is false (eg: x nor y)

not

Logical NOT, Negate the logical sense of the input. (eg: not(x and y) == x nand y)

or

Logical OR, True if either x or y is true. (eg: x or y)

xor

Logical XOR, True only if the logical states of x and y differ. (eg: x xor y)

xnor

Logical XNOR, True iff the biconditional of x and y is satisfied. (eg: x xnor y)

&

Similar to AND but with left to right expression short circuiting optimisation. (eg: (x & y) == (y and x))

Similar to OR but with left to right expression short circuiting optimisation. (eg: (x | y) == (y or x))

General Purpose Functions

FUNCTION

DEFINITION

abs

Absolute value of x. (eg: abs(x))

avg

Average of all the inputs. (eg: avg(x,y,z,w,u,v) == (x + y + z + w + u + v) / 6)

ceil

Smallest integer that is greater than or equal to x.

clamp

Clamp x in range between r0 and r1, where r0 < r1. (eg: clamp(r0,x,r1))

equal

Equality test between x and y using normalised epsilon

erf

Error function of x. (eg: erf(x))

erfc

Complimentary error function of x. (eg: erfc(x))

exp

e to the power of x. (eg: exp(x))

expm1

e to the power of x minus 1, where x is very small. (eg: expm1(x))

floor

Largest integer that is less than or equal to x. (eg: floor(x))

frac

Fractional portion of x. (eg: frac(x))

hypot

Hypotenuse of x and y (eg: hypot(x,y)=sqrt(x*x + y*y))

iclamp

Inverse-clamp x outside of the range r0 and r1. Where r0 < r1. If x is within the range it will snap to the closest bound. (eg: iclamp(r0,x,r1)

inrange

In-range returns ‘true’ when x is within the range r0 and r1. Where r0 < r1. (eg: inrange(r0,x,r1)

log

Natural logarithm of x. (eg: log(x))

log10

Base 10 logarithm of x. (eg: log10(x))

log1p

Natural logarithm of 1 + x, where x is very small. (eg: log1p(x))

log2

Base 2 logarithm of x. (eg: log2(x))

logn

Base N logarithm of x. where n is a positive integer. (eg: logn(x,8))

max

Largest value of all the inputs. (eg: max(x,y,z,w,u,v))

min

Smallest value of all the inputs. (eg: min(x,y,z,w,u))

mul

Product of all the inputs. (eg: mul(x,y,z,w,u,v,t) == (x * y * z * w * u * v * t))

ncdf

Normal cumulative distribution function. (eg: ncdf(x))

nequal

Not-equal test between x and y using normalised epsilon

pow

x to the power of y. (eg: pow(x,y) == x ^ y)

root

Nth-Root of x. where n is a positive integer. (eg: root(x,3) == x^(1/3))

round

Round x to the nearest integer. (eg: round(x))

roundn

Round x to n decimal places (eg: roundn(x,3)) where n > 0 and is an integer. (eg: roundn(1.2345678,4) == 1.2346)

sgn

Sign of x, -1 where x < 0, +1 where x > 0, else zero. (eg: sgn(x))

sqrt

Square root of x, where x >= 0. (eg: sqrt(x))

sum

Sum of all the inputs. (eg: sum(x,y,z,w,u,v,t) == (x + y + z + w + u + v + t))

swap <=>

Swap the values of the variables x and y and return the current value of y. (eg: swap(x,y) or x <=> y)

trunc

Integer portion of x. (eg: trunc(x))

Trigonometry Functions

FUNCTION

DEFINITION

acos

Arc cosine of x expressed in radians. Interval [-1,+1] (eg: acos(x))

acosh

Inverse hyperbolic cosine of x expressed in radians. (eg: acosh(x))

asin

Arc sine of x expressed in radians. Interval [-1,+1] (eg: asin(x))

asinh

Inverse hyperbolic sine of x expressed in radians. (eg: asinh(x))

atan

Arc tangent of x expressed in radians. Interval [-1,+1] (eg: atan(x))

atan2

Arc tangent of (x / y) expressed in radians. [-pi,+pi] eg: atan2(x,y)

atanh

Inverse hyperbolic tangent of x expressed in radians. (eg: atanh(x))

cos

Cosine of x. (eg: cos(x))

cosh

Hyperbolic cosine of x. (eg: cosh(x))

cot

Cotangent of x. (eg: cot(x))

csc

Cosecant of x. (eg: csc(x))

sec

Secant of x. (eg: sec(x))

sin

Sine of x. (eg: sin(x))

sinc

Sine cardinal of x. (eg: sinc(x))

sinh

Hyperbolic sine of x. (eg: sinh(x))

tan

Tangent of x. (eg: tan(x))

tanh

Hyperbolic tangent of x. (eg: tanh(x))

deg2rad

Convert x from degrees to radians. (eg: deg2rad(x))

deg2grad

Convert x from degrees to gradians. (eg: deg2grad(x))

rad2deg

Convert x from radians to degrees. (eg: rad2deg(x))

grad2deg

Convert x from gradians to degrees. (eg: grad2deg(x))

Control Structures

STRUCTURE

DEFINITION

if

If x is true then return y else return z. eg:

1. if (x, y, z)
2. if ((x + 1) > 2y, z + 1, w / v)
3. if (x > y) z;
4. if (x <= 2*y) { z + w };

if-else

The if-else/else-if statement. Subject to the condition branch the statement will return either the value of the consequent or the alternative branch. eg:

1. if (x > y) z; else w;
2. if (x > y) z; else if (w != u) v;
3. if (x < y) { z; w + 1; } else u;
4. if ((x != y) and (z > w))
   {
     y := sin(x) / u;
     z := w + 1;
   }
   else if (x > (z + 1))
   {
     w := abs (x - y) + z;
     u := (x + 1) > 2y ? 2u : 3u;
   }

switch

The first true case condition that is encountered will determine the result of the switch. If none of the case conditions hold true, the default action is assumed as the final return value. This is sometimes also known as a multi-way branch mechanism. eg:

switch
{
  case x > (y + z) : 2 * x / abs(y - z);
  case x < 3       : sin(x + y);
  default          : 1 + x;
}