Guidelines for Writing RTMB-Compatible Code

Models defined in rtmb_code rely on Automatic Differentiation (AD) via the RTMB package. To ensure the model is differentiable and numerically stable, specific coding practices must be followed.

Details

1. Automatic Differentiation and advector: Parameters and intermediate calculations involving them are treated as advector objects. RTMB "records" all mathematical operations to compute derivatives automatically. If a function strips these attributes or is not differentiable, the gradient calculation will fail.

2. Avoid Discrete Branching: Standard R conditional statements like if (x > 0) or ifelse() based on parameter values do not provide derivatives.

Problem: They create "jumps" in the likelihood surface.
Solution: Use smooth approximations. For example, use fabs instead of abs, or log_mix for mixture logic.

3. Numerical Stability: Computations in log-space are preferred to prevent overflow or underflow. Use the following stable utilities instead of raw algebraic expressions:

log_sum_exp: For summing probabilities in log-space.
log1p_exp: For log(1 + exp(x)).
inv_logit: For mapping real numbers to probabilities.

4. Vectorization vs. Loops:

Vectorization: Highly recommended for performance. Standard R vectorized arithmetic (+, -, *, /, log, exp) works seamlessly with AD.
Loops: Standard for loops are safe as long as the operations inside are differentiable.
Avoid apply: Functions like apply, sapply, or lapply may sometimes strip AD attributes and should be replaced with vectorized operations or explicit loops.

5. Matrix Operations: Use specialized functions for matrix algebra to maintain efficiency:

quad_form_chol: For efficient quadratic forms.
log_det_chol: For log-determinants via Cholesky factors.

Details

See also