Modelling format

The model should be written in a plain text file, and should include all of the headings in the block below. Note that all # are required, but it is not necessary that there exists text in each heading only that the heading is present.

    ########## NAME
    ########## METADATA
    ########## MACROS
    ########## STATES
    ########## PARAMETERS 
    ########## VARIABLES
    ########## FUNCTIONS
    ########## EVENTS
    ########## OUTPUTS
    ########## INPUTS
    ########## FEATURES

Under the Name heading, the model name should be defined. Under the METADATA heading, timeunit should be defined (such as timeunit = 's' for seconds). STATES, PARAMETERS, VARIABLES, FUNCTIONS correspond to the "standard" format of an ODE model. Events correspond to similar events as in the SB toolbox. INPUTS and OUTPUTS correspond to the variables that should either be included och shared with other models or activities.

Below shows the two example models in this repository. Note that they share some variables via INPUT/OUTPUT.

An ODE example

########## NAME
Glucose
########## METADATA
Timeunit = s
Img = glucose.png
Docstr = A test model
Modeltype = ODE
########## MACROS
HEJ = 44
########## STATES
d/dt(GLUC) = UPTAKE - CLEARANCE
d/dt(TEST) = 0
TEST(0) = 0
GLUC(0) = 10
########## PARAMETERS 
k1 = 1
k2 = 1
k3 = 1
########## VARIABLES
UPTAKE = k1*INS
tmp = k3*UPTAKE
CLEARANCE = k2*GLUC
########## FUNCTIONS
########## EVENTS
E1 = GLUC < 3,k1,1,TEST,10
E2 = GLUC < 1.5,TEST,-10
########## OUTPUTS
INS_UPTAKE = tmp
########## INPUTS
INS = 1*INSULIN
########## FEATURES
GLUCOSE = GLUC # g/ml
TEST = TEST

A DAE example.

The DAE model is similar to an ODE model, except for that the expression should be written to only include a right-hand-side (rhs). If we have e.q. an algebraic equation ALG like: ALG = k1 - 5, it should be rewritten as 0 = k1 - 5 - ALG. Optionally, it could also likely be rewritten as 0 = ALG - k1 + 5.

Due to the way the compilation to C-code is implemented, algebraic states will end up after the ODE-states. Thus, it is advised to put the algebraic states and initial conditions at the end of STATES heading.

Also note that it is typically necessary to pass along an extra option to the Simulation function, with the calcic flag set to True:

options = {'calcic': True}

An example of a DAE model is given below.

########## NAME
Insulin
########## METADATA
Timeunit = s
Img = insulin.png
Docstr = En test model
########## MACROS
HEJ = 44
########## STATES
d/dt(INS) = PRODUCTION - UPTAKE - CLEARANCE
0 = INS - ALGSTATE
INS(0) = 5
ALGSTATE(0) = 5
########## PARAMETERS 
k1 = 1
k2 = 1
########## VARIABLES
CLEARANCE = k2*INS
########## FUNCTIONS
########## EVENTS
//eventtest = INS < 1, INS, 5
########## OUTPUTS
INSULIN = INS
########## INPUTS
UPTAKE = INS_UPTAKE
PRODUCTION = ACTIVITY_IN @ 0
########## FEATURES
INS = INS # Mol
ALGSTATE = ALGSTATE

Mathematical functions

Defined functions

Several mathematical functions are defined and can be used as right hand side values in assignments. All arguments are interpreted as floating point numbers.

Function	Description
all({a, b, ... , n})	Returns 1 if no arguments are 0. Otherwise returns 0. Arguments must be passed in braces.
any({a, b, ... , n})	Returns 1 if any arguments is not 0. Otherwise returns 0. Arguments must be passed in braces.
eq(a, b)	Returns 1 if a is equal to b. Otherwise returns 0.
ge(a, b)	Returns 1 if a is greater than or equal to b. Otherwise returns 0.
gt(a, b)	Returns 1 if a is greater than b. Otherwise returns 0.
indexMax({a, b, ... , n})	Returns the index of the greatest of the given arguments. Arguments must be passed in braces.
indexMin({a, b, ... , n})	Returns the index of the smallest of the given arguments. Arguments must be passed in braces.
le(a, b)	Returns 1 if a is less than or equal to b. Otherwise returns 0.
lt(a, b)	Returns 1 if a is less than b. Otherwise returns 0.
max(a, b)	Returns the greatest of a and b.
max({a, b, ... , n})	Returns the greatest of given arguments. Arguments must be passed in braces.
min(a, b)	Returns the smallest of a and b.
min({a, b, ... , n})	Returns the smallest of given arguments. Arguments must be passed in braces.
root(a, n)	Returns the nth root of a.
sign(a)	Returns 1 if a is positive, -1 if a is negative and 0 if a is 0.

Constants

The following constants are defined.

Constant	Description
CONSTANT_E	Euler's number, \(e\)
CONSTANT_LOG2_E	$ \log_2 e $
CONSTANT_LOG10_E	$ \log_{10} e $
CONSTANT_PI	Pi, \(\pi\)
CONSTANT_INV_PI	$ 1 \over \pi $
CONSTANT_INV_SQRT_PI	$ 1 \over \sqrt\pi $
CONSTANT_LN_2	$ \ln 2 $
CONSTANT_LN_10	$ \ln 10 $
CONSTANT_SQRT_2	$ \sqrt 2 $
CONSTANT_SQRT_3	$ \sqrt 3 $
CONSTANT_INV_SQRT_3	$ 1 \over \sqrt 3 $
CONSTANT_GAMMA	Euler's constant, \(\gamma\)
CONSTANT_PHI	The golden ratio, \(\varphi\)

Additional functions

All functions from the <cmath> header of the C++ standard library can also be used. The functions are called without providing the std:: namespace. For instance the following line will call the c++ function std::sin with the argument \(\pi \over 2\):

var = sin(CONSTANT_PI/2)

Examples of cmath functions

function	description
std::abs	Absolute value
std::fmod	Modulo operation
std::pow	Raise to exponent
std::sqrt	Square root
std::exp	Eulers number raised to exponent
std::log	Natural logarithm
std::log10	Common logarithm
std::cos	Cosine
std::sin	Sine
std::tan	Tangent
std::round	Round to closest integer
std::floor	Round down to closest integer
std::ceil	Round up to closest integer