Model Syntax¶
This page provides a reference for the syntax used to write a set of equations.
Model Symbols¶
We use the term model symbol to describe all the identifiers that a user can define in the equations. They consist of the dependent variables, the model parameters, the macros and the covariates. You can think of them as variables in a programming language. They all follow the same naming convention:
- All of the following characters are allowed: numbers (0-9), letters (a-zA-Z), and the underscore symbol (_)
- The first character can not be a number, and a symbol can not start with 3 consecutive underscores. So __Alpha is valid, but not ___Alpha. XX1 is valid, but not 1XX.
- Symbols are case-sensitive. So Alpha and alpha are different symbols.
- A symbol can have only one use. The same name can not be used for both a model parameter and a macro.
- There is no maximum length to the symbol names, although no one has bothered testing what would happen with symbol names that are 3000 characters long.
- A symbol name can not be any of the reserved words or function names listed below.
Equation types¶
DEDiscover operates on a line by line basis with each line being one of the following types of statement. Not that the order in which the statements appear in not important.
Differential Equations¶
Differential equations have the form
dx/dt = 3x + alpha
where we call x a dependent variable. A valid model must contain at least one such equation.
Macros¶
The following expressions create macros X and Y:
X = 3*x _1
Y=3
Note that macros can not create cycles. For instance the following would raise an error:
X = alpha + Y
Y = 2*X
because X depend on Y and Y depends on X.
History Statements¶
History statements have the form:
y[t] = alpha / t, -5 < t \< 0
x[t] = -1, -INF < t <= -3
x[t] = log(alpha), -3 < t <= 0
History functions are used to evaluate delay variables at the time points before the start of the simulation. In the
example above x and y must be dependent variables. The [t] is part of the syntax and represents the current timestep.
The section after the comma represents the time interval where the function
is applied. The function for a dependent variable will default to 0 when it is not defined for an interval. Overlapping
intervals will result in undefined behavior.
Each statement must contain an upper and lower bound, and only the < and <= symbols are allowed.
Only numbers are allowed for the bounds on the right-hand side.
Covariates¶
Covariates have the form:
Covariate{COV_1, t}
Covariate{COV_2, t-1}
Covariate{COV_3, t-alpha}
Covariates are a late addition to DEDiscover, hence the unusually awkward syntax. They contain a model symbol followed by a time expression. The model symbol can by used in other expression. A covariate will use data mapped from the datatable created by a user. Until a mapping has been defined with a covariate the return value for this covariate will be 0.
The time expression can be any valid expression which does not generate a cycle, although it will typically be t or t minus
some constant.
Mathematical operations, notation and expressions¶
The table below lists all the binary operators that are available in DEDiscover. We follow the syntax used by muparser, as this package is used to perform the computation.
| Operator | Meaning | Priority |
|---|---|---|
| = | assignment | -1 |
| && | logical and | 1 |
| || | logical or | 4 |
| <= | less or equal | 4 |
| >= | greater or equal | 4 |
| != | not equal | 4 |
| == | equal | 4 |
| > | greater than | 4 |
| < | less than | 4 |
| + | addition | 5 |
| - | subtraction | 5 |
| * | multiplication | 6 |
| / | division | 6 |
| ^ | raise x to the power of y | 7 |
Predefined functions¶
DEDiscover defines a set of general purpose functions which are listed in the table below. Most of them are implemented by muparser, and we have added a few extra ones.
| Name | Number of Arguments | Explanation | Example |
|---|---|---|---|
| sin | 1 | sine function (degrees) | sin(aplha) |
| cos | 1 | cosine function | |
| tan | 1 | tangent function | |
| asin | 1 | arc-sine function | |
| acos | 1 | arc-cosine function | |
| atan | 1 | arc-tangent function | |
| sinh | 1 | hyperbolic sine function | |
| cosh | 1 | hyperbolic cosine | |
| tanh | 1 | hyperbolic tangent function | |
| asinh | 1 | hyperbolic arc-sine function | |
| acosh | 1 | hyperbolic arc-tangent function | |
| atanh | 1 | hyperbolic arc-tangent function | |
| log2 | 1 | logarithm to the base 2 | |
| log10 | 1 | logarithm to the base 10 | |
| log | 1 | logarithm to the base 10 | |
| ln | 1 | logarithm to base e (2.71828…) | |
| exp | 1 | e (2.71828…) raised to the power of x | |
| sqrt | 1 | square root function | |
| sign | 1 | sign function: -1 if x<0; 1 if x>=0 | |
| rint | 1 | Round a rational number to nearest integer. It is rounded down if the fractional part is less than 0.5, and rounded up otherwise. | |
| abs | 1 | absolute value | |
| if | 3 | if … then … else … if (a<5, 12+3, 2*X) will return 15 when a<5, twice the current value of X otherwise. | |
| min | var | min of all arguments | |
| max | var | max of all arguments | |
| sum | var | sum of all arguments | |
| avg | var | Mean value of all arguments | avg(T1,T2,T3) |
| ind | 1 | Indicator function, 1 if the argument is true, 0 otherwise. | ind( 0<= T1 <= 10 ) |
| gamma_p | 2 | Computes the normalised lower incomplete gamma function of the first and second argument. | gamma_p(a, z) |
| piecewise | var | Piecewise function. Returns the first value for which a boolean expresses to true. If none is true, returns the last argument if there is an odd number of argument, returns 0 otherwise. | piecewise (v1, a==0, v2, b > 5, v3, b3, 6) If a is 0 then returns v1, if b>5 then returns v2, if b3 is true returns v3, returns 6 otherwise. |
Time-Varying functions¶
DEDiscover defines 2 time varying function. (More may be coming.) These functions are evaluated during the simulation. The first argument will typically be the time variable t but could also be a dependent variable or an expression. The next 2 parameters are vectors. The elements in the vectors can either be fixed numbers or model parameters. They can not be dependent variables, macros or covariates. These functions are initialized at the beginning of the simulation, then at each iteration it is evaluated at the value defined by the first argument based on the values of the other arguments. Notice that the value of the first argument is the only one allowed to change during the simulation, since all the others are fixed numbers or model parameters.
All the functions accept an optional last parameter that contains the default value to be used when the value of the first parameter falls outside the range for which the function is defined. If not indicated it defaults to NaN (Not a Number). This parameter can be either a fixed number or a model parameter.
| Function name | Description | Use | Constraints | Example |
|---|---|---|---|---|
| locf | Last Observation Carried Forward. Given t, returns the value of b(k) such that a(k) <= t < b(k+1). Returns b(n) if t > a(n), 0 if t < a(1) | locf(t, [a(1), a(2),…a(n)], [(b(1), b(2), …b(n)],[def]) | All the a(1), a(2), … must be different. | locf(t, [alpha, 3, 4],[2,3,beta]) |
| boost_spline | Creates a cubic b-spline interpolation for points that are equally spaced. | boost_spline(t, [a(1), a(2), …a(n)], [b(1), b(2), …b(n)], [def]) |
|
boost_spline(t, [1, 3, 5, 7, 9]. [2,3,beta, 11, -4.5]) |
Reserved words¶
Some words are reserved, meaning that although they are correctly formed, then can not be used as dependent variable names, macros, or model parameters. All the predefined functions and binary operators described above are reserved symbols. In addition the symbols in the following table are reserved.
| Symbol | Use |
|---|---|
| t |
|
| t0 | Initial value of the independent variable (time) |
| INF | Infinity. Can be preceeded by +/- |
| NaN | Not a number |
| pi |
|
| and, or, xor | Boolean operators described above |