9.4 Argument types and qualifiers
Stan’s functions all have declared types for both arguments and returned value. As with built-in functions, user-defined functions are only declared for base argument type and dimensionality. This requires a different syntax than for declaring other variables. The choice of language was made so that return types and argument types could use the same declaration syntax.
The type void may not be used as an argument type, only a
return type for a function with side effects.
Base variable type declaration
The base variable types are integer, real, complex, vector,
row_vector, and matrix. No lower-bound or upper-bound constraints
are allowed (e.g., real<lower=0> is illegal). Specialized
constrained types are also not allowed (e.g., simplex is illegal).
Tuple types of the form tuple(T1, ..., TN) are also allowed, with
all of the types T1 to TN being function argument types (i.e., no
constraints and no sizes).
Dimensionality declaration
Arguments and return types may be arrays, and these are indicated with
optional brackets and commas as would be used for indexing. For
example, int denotes a single integer argument or return,
whereas array[] real indicates a one-dimensional array of reals,
array[,] real a two-dimensional array and array[,,] real a
three-dimensional array; whitespace is optional, as usual.
The dimensions for vectors and matrices are not included, so that
matrix is the type of a single matrix argument or return type.
Thus if a variable is declared as matrix a, then a has
two indexing dimensions, so that a[1] is a row vector and
a[1, 1] a real value. Matrices implicitly have two indexing
dimensions. The type declaration matrix[ , ] b specifies that
b is a two-dimensional array of matrices, for a total of four
indexing dimensions, with b[1, 1, 1, 1] picking out a real value.
Dimensionality checks and exceptions
Function argument and return types are not themselves checked for dimensionality. A matrix of any size may be passed in as a matrix argument. Nevertheless, a user-defined function might call a function (such as a multivariate normal density) that itself does dimensionality checks.
Dimensions of function return values will be checked if they’re assigned to a previously declared variable. They may also be checked if they are used as the argument to a function.
Any errors raised by calls to functions inside user functions or return type mismatches are simply passed on; this typically results in a warning message and rejection of a proposal during sampling or optimization.
Data-only qualifiers
Some of Stan’s built-in functions, like the differential equation solvers, have arguments that must be data. Such data-only arguments must be expressions involving only data, transformed data, and generated quantity variables.
In user-defined functions, the qualifier data may be placed before
an argument type declaration to indicate that the argument must be
data only. For example,
real foo(data real x) {
return x^2;
}requires the argument x to be data only.
Declaring an argument data only allows type inference to proceed in the body of the function so that, for example, the variable may be used as a data-only argument to a built-in function.