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.


The following expressions create macros X and Y:

X = 3*x _1

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 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:
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.

Predefined function (adapted and augmented from muparser homepage
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
Independent variable
t0 Initial value of the independent variable (time)
INF Infinity. Can be preceeded by +/-
NaN Not a number
The mathematical constant:
and, or, xor Boolean operators described above