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. :doc:`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: .. code-block:: text porosity * 2 log10(k_calcite) **A results field, in anything that reads results** -- between hashes: .. code-block:: text #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: .. code-block:: text @{my_param}@ the parameter's value @{$10^C_param$}@ an expression, evaluated first :doc:`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; | | | } | +----------+---------------------------------------------------------+