IBMPopSim C++ essentials

C++ syntax

• Each statement must be ended by a semicolon.
• Single-line comments start with two forward slashes //.
• To create a variable, you must specify the type and assign it a value (type variable = value;). Here some examples:

int myNum = 5;               // Integer (whole number without decimals)
double myFloatNum = 5.99;    // Floating point number (with decimals)
char myLetter = 'D';         // Character
bool myBoolean = true;       // Boolean (true or false)

• bool data type can take the values true (1) or false (0).
• C++ supports the usual logical conditions from mathematics:
  • Less than: a < b
  • Less than or equal to: a <= b
  • Greater than: a > b
  • Greater than or equal to: a >= b
  • Equal to a == b
  • Not Equal to: a != b
• The logical operators are: !, &&, ||
• The arithmetic operators are: +, -, *, /, %
• Compound assignment: +=, -=, *=, /=, %=
• Increment and decrement: ++, --
• Conditional ternary operator: ? : The conditional operator evaluates an expression, returning one value if that expression evaluates to true, and a different one if the expression evaluates as false. Its syntax is:

condition ? result1; : result2;

• Use the if, else if, else statements to specify a block of C++ code to be executed if one or more conditions are or not true.

if (condition1) {
  // block of code to be executed if condition1 is true
} else if (condition2) {
  // block of code to be executed if the condition1 is false and condition2 is true
} else {
  // block of code to be executed if the condition1 is false and condition2 is false
}

• The syntax of the switch statement is a bit peculiar. Its purpose is to check for a value among a number of possible constant expressions. It is something similar to concatenating if-else statements, but limited to constant expressions. Its most typical syntax is:

switch (expression)
{
  case constant1:
     group-of-statements-1;
     break;
  case constant2:
     group-of-statements-2;
     break;
  .
  .
  .
  default:
     default-group-of-statements
}

It works in the following way: switch evaluates expression and checks if it is equivalent to constant1; if it is, it executes group-of-statements-1 until it finds the break statement. When it finds this break statement, the program jumps to the end of the entire switch statement (the closing brace).

• When you know exactly how many times you want to loop through a block of code, use the for loop.

for (statement 1; statement 2; statement 3) {
  // code block to be executed
}

• The while loop loops through a block of code as long as a specified condition is true.

while (condition) {
  // code block to be executed
}

For more details we recommend a few pages of www.cplusplus.com about:

• Variables
• Operators
• Statements

Usual numeric functions

The most popular functions of the cmath library, which is included in the package, are the following:

• Exponential and logarithm functions: exp(x), log(x) (natural logarithm)
• Trigonometric functions: cos(x), sin(x), tan(x)
• Power functions: pow(x, a) meaning x^a and sqrt(x) meaning $\sqrt{x}$
• Absolute value: abs(x)
• Truncation functions: ceil(x) meaning ⌈x⌉ and floor(x) meaning ⌊x⌋
• Bivariate functions: max(x, y) and min(x,y)

Note that these functions are not vectorial, the arguments x and y must be scalar. If the user wants to call some other functions of cmath not listed in the table, this is possible by adding the prefix std:: to the name of the function (scope resolution operator :: to access to functions declared in namespace standard std).

Individuals characteristics and model parameters: link between R and C++

To facilitate the model creation, the individuals’ characteristics and a list model parameters can be declared in the R environment and used in the C++ code.

The data shared between the R environment and the C++ code are:

• The characteristics of the individuals which must be atomic (Boolean, scalar or character).
• The model parameters: a list of variables of type:
  • Atomic, vector or matrix.
  • Predefined real functions of one variable, or list of such functions.
  • Piecewise real function of two variables, of list of such.

library(IBMPopSim)
pop <- population(IBMPopSim::EW_popIMD_14$sample)
get_characteristics(pop)
##   male    IMD 
## "bool"  "int"

params <- list("lambda" = 0.02, "alpha" = 0.4, "mu" = as.integer(2))
code <- "result = lambda + alpha * (age(I, t) + mu);"
event_birth <- mk_event_individual("birth", intensity_code = code)
mod <- mk_model(get_characteristics(pop), events = list("birth" = event_birth), 
                parameters = params, with_compilation = FALSE)
summary(mod)
## Events description:
## [[1]]    
## Event class : individual 
## Event type : birth 
## Event name : birth
## Intensity code : 'result = lambda + alpha * (age(I, t) + mu);' 
## Kernel code : '' 
## 
## --------------------------------------- 
## Individual description:
## names:  birth death male IMD 
## R types:  double double logical integer 
## C types:  double double bool int 
## --------------------------------------- 
## R parameters available in C++ code:
## names:  lambda alpha mu 
## R types:  double double integer 
## C types:  double double int

library(ggfortify)
dr <- with(EW_pop_14$rates,
           stepfun(x = death_male[,"age"], y = c(0, death_male[,"value"])))
autoplot(dr, xlab="age", ylab="dr", shape=NULL,main="Example of step function")

f <- piecewise_x(80, list(dr, gompertz(0.00006, 0.085)))
x <- seq(40, 110)
ggplot(data.frame(x=x, y=sapply(x, f)), aes(x=x, y=y))+ geom_step() + xlab("Age") +ylab("f") + ggtitle("Example of piecewise function")

params <- list("rate" = dr)
event <- mk_event_individual("death", intensity_code = "result = rate(age(I, t));")
mod <- mk_model(get_characteristics(pop), events = list("death" = event), 
                parameters = params, with_compilation = FALSE)
summary(mod)
## Events description:
## [[1]]    
## Event class : individual 
## Event type : death 
## Event name : death
## Intensity code : 'result = rate(age(I, t));' 
## Kernel code : '' 
## 
## --------------------------------------- 
## Individual description:
## names:  birth death male IMD 
## R types:  double double logical integer 
## C types:  double double bool int 
## --------------------------------------- 
## R parameters available in C++ code:
## names:  rate 
## R types:  closure 
## C types:  function_x

popsim(mod, pop, params = list("rate" = dr), age_max = 120, 
       events_bounds = c("death" = dr(age_max)), time = 10)

popsim(mod, pop, params = list("rate" = f), age_max = 120, 
       events_bounds = c("death" = f(age_max)), time = 10)

Random variables

We use the following notations to describe the available C++ random distributions, which can be used in the C++ intensity and kernel codes.

• 𝒰(a, b) : Uniform distribution on [a, b] with a < b

• ℰ(λ) : Exponential distribution, λ > 0

• 𝒩(μ, σ) : Gaussian distribution, μ, σ ∈ R

• Pois(λ): Poisson distribution, λ > 0

• Γ(α, β): Gamma distribution, α > 0, β > 0

• Weib(a, b): Weibull distribution, a > 0, b > 0

• 𝒰{a, b}: Discrete uniform distribution on {a, a + 1, …, b} with a < b

• ℬ(p): Bernoulli distribution, the probability of success is p ∈ (0, 1)

• ℬ(n, p): Binomial distribution n ≥ 1, p ∈ (0, 1)

• 𝒟_n : Discrete distribution with values in {0, …, n − 1} and with probabilities {p₀, …, p_n − 1}.

In the table below we show how to call them, which means how to make independent realizations of these random variables, and we give the reference to the C++ corresponding function of the random library hidden in this call.

In the discrete distribution call CDiscrete(p_begin, p_end), the arguments p_begin and p_end represent the iterators to the begin and to the end of an array which contains {p₀, …, p_n − 1}. Note that the use of iterators is a convenient and fast way to access a column or row of a matrix arma::mat.