Model file syntax¶
The model file is very flexible and allows you to create spatial models, generate custom propensity functions, and more. The model file uses EMODL (Epidemiological Model Language) syntax defined by IDM that is similar to LISP. Lines are enclosed in parentheses. Any text that follows a semi-colon (;) is treated as a comment until the beginning of the next line.
The basic format of the model file is as follows:
(import (rnrs) (emodl cmslib)) (start-model "modelname") ... (end-model)
Basic EMODL syntax¶
All EMODL arguments available to define the CMS model are listed below.
Defines a function that returns a boolean value, used with state-event.
(bool name expression)
(bool exitTimeEvent (== R 85))
Defines a numeric function that is evaluated each time it is needed.
(func name function)
func muA (/ 1 60))
Declares an external JSON-formatted file that can be referenced in species definitions, parameter definitions, and functions.
json name file
(json defaults "garkiparams.json")
Creates a new geographic locale.
Adds a variable or function to the list of observed items that are output from a simulation.
(observe label function)
(observe carrier C)
Defines a named, constant value.
(param name value)
(param reVal 0)
Defines a reaction or transition from one set of species to another.
(reaction name input-species output-species propensity-function)
(reaction recoveryIc (Ic) () (/ (* gamma Ic) 20))
Sets the current geographic local. New species will be associated with this locale. This is used with spatial solvers.
Defines a unique species or population of particles or agents.
(species name [initial population])
(species Sa 2500)
Defines an event to occur given a particular system state.
(state-event name predicate (variable-value pairs))
(state-event death-v (> I 25) ((Kv 0.02)))
Defines an event to occur at a particular time. You have the option to add recurrent events.
(time-event name time iterations (variable-value pairs))
(time-event sia 50.0 ((Kv 0.02)))
- variable-value pairs
This is not a named parameter, but rather a list of pairs of variables to set and the value to which to set them.
((var (val)))(var (val)))
((V (* S 0.5)) (S (* S 0.5)))sets V = S/2 and then sets S = S/2 (in other words, it transfers half the population of S to V).
Mathematical operators and functions¶
The arguments can be used with the following operators to define the mathematics of the CMS model.
(exp x)returns e^x
(floor x)returns the largest integer <= x.
(ceil x)returns the smallest integer >= x.
- square root
- Heaviside step
(step x)returns 1 if x >= 0 else returns 0.
(empirical "filename")reads an empirically defined cumulative distribution function from the file specified and returns a probability from the configuration file based on a random number draw.
(+ x y)
(- x y)
(* x y)
(/ x y)
(^ x y)or
(pow x y)
(min x y)
(max x y)
(uniform min max)returns a value uniformly distributed between min and max based on a random number draw.
(normal mean var)or
(gaussian mean var)returns a value from a normal distribution with the given mean and variance.
(+ x y z ...)or
(sum x y z ...)returns the sum of all the given arguments.
(* x y z ...)returns the product of all the given arguments.
The following example shows an simple SEIR model specification.
; simplemodel (import (rnrs) (emodl cmslib)) (start-model "seir.emodl") (species S 990) (species E) (species I 10) (species R) (observe susceptible S) (observe exposed E) (observe infectious I) (observe recovered R) (param Ki 0.0005) (param Kl 0.2) (param Kr (/ 1 7)) (param Kw (/ 1 135)) (reaction exposure (S I) (E I) (* Ki S I)) (reaction infection (E) (I) (* Kl E)) (reaction recovery (I) (R) (* Kr I)) (reaction waning (R) (S) (* Kw R)) (end-model)
Note that when a species is in both the input and the output, neither is technically necessary. In other words, the following reaction specifications are equivalent. You can think about this as catalysis: an S in the presence of I becomes an E with the I unaffected.
(reaction exposure (S I) (E I) (* Ki S I)) (reaction exposure (S) (E) (* Ki S I))