3.7 Step-like Functions

Warning: These functions can seriously hinder sampling and optimization efficiency for gradient-based methods (e.g., NUTS, HMC, BFGS) if applied to parameters (including transformed parameters and local variables in the transformed parameters or model block). The problem is that they break gradients due to discontinuities coupled with zero gradients elsewhere. They do not hinder sampling when used in the data, transformed data, or generated quantities blocks.

3.7.1 Absolute Value Functions

R fabs(T x)
absolute value of x

real fdim(real x, real y)
Return the positive difference between x and y, which is x - y if x is greater than y and 0 otherwise; see warning above. \[ \text{fdim}(x,y) = \begin{cases} x-y & \text{if } x \geq y \\ 0 & \text{otherwise} \end{cases} \]

3.7.2 Bounds Functions

real fmin(real x, real y)
Return the minimum of x and y; see warning above. \[ \text{fmin}(x,y) = \begin{cases} x & \text{if } x \leq y \\ y & \text{otherwise} \end{cases} \]

real fmax(real x, real y)
Return the maximum of x and y; see warning above. \[ \text{fmax}(x,y) = \begin{cases} x & \text{if } x \geq y \\ y & \text{otherwise} \end{cases} \]

3.7.3 Arithmetic Functions

real fmod(real x, real y)
Return the real value remainder after dividing x by y; see warning above. \[ \text{fmod}(x,y) = x - \left\lfloor \frac{x}{y} \right\rfloor \, y \] The operator \(\lfloor u \rfloor\) is the floor operation; see below.

3.7.4 Rounding Functions

Warning: Rounding functions convert real values to integers. Because the output is an integer, any gradient information resulting from functions applied to the integer is not passed to the real value it was derived from. With MCMC sampling using HMC or NUTS, the MCMC acceptance procedure will correct for any error due to poor gradient calculations, but the result is likely to be reduced acceptance probabilities and less efficient sampling.

The rounding functions cannot be used as indices to arrays because they return real values. Stan may introduce integer-valued versions of these in the future, but as of now, there is no good workaround.

R floor(T x)
floor of x, which is the largest integer less than or equal to x, converted to a real value; see warning at start of section step-like functions

R ceil(T x)
ceiling of x, which is the smallest integer greater than or equal to x, converted to a real value; see warning at start of section step-like functions

R round(T x)
nearest integer to x, converted to a real value; see warning at start of section step-like functions

R trunc(T x)
integer nearest to but no larger in magnitude than x, converted to a double value; see warning at start of section step-like functions