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:

1. All of the following characters are allowed: numbers (0-9), letters (a-zA-Z), and the underscore symbol (_)
2. 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.
3. Symbols are case-sensitive. So Alpha and alpha are different symbols.
4. A symbol can have only one use. The same name can not be used for both a model parameter and a macro.
5. 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.
6. 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.

Binary operators (adapted from muparser: https://beltoforion.de/en/muparser/)
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
- 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.

Predefined function (adapted and augmented from muparser homepage https://beltoforion.de/en/muparser/)
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.

Time-Varying functions
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])
1. All the a(1), a(2), … must be equally spaces.
2. n >= 4
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.

Reserved words
Symbol Use
t
Independent variable
(time)
t0 Initial value of the independent variable (time)
INF Infinity. Can be preceeded by +/-
NaN Not a number
pi
The mathematical constant:
3.141592…
and, or, xor Boolean operators described above