6.5 Arithmetic and matrix operations on expressions
For integer and real-valued expressions, Stan supports the basic
binary arithmetic operations of addition (+), subtraction
(-), multiplication (*) and division (/) in the
usual ways.
For integer expressions, Stan supports the modulus (%) binary
arithmetic operation. Stan also supports the unary operation of
negation for integer and real-valued expressions. For example,
assuming n and m are integer variables and x and
y real variables, the following expressions are legal.
3.0 + 0.14
-15
2 * 3 + 1
(x - y) / 2.0
(n * (n + 1)) / 2
x / n
m % nThe negation, addition, subtraction, and multiplication operations are
extended to matrices, vectors, and row vectors. The transpose
operation, written using an apostrophe (') is also supported
for vectors, row vectors, and matrices. Return types for matrix
operations are the smallest types that can be statically guaranteed to
contain the result. The full set of allowable input types and
corresponding return types is detailed in the list of functions.
For example, if y and mu are variables of type vector and
Sigma is a variable of type matrix, then (y - mu)' * Sigma * (y - mu) is a well-formed expression of type real. The type of the
complete expression is inferred working outward from the
subexpressions. The subexpression(s) y - mu are of type vector
because the variables y and mu are of type vector. The
transpose of this expression, the subexpression (y - mu)' is of type
row_vector. Multiplication is left associative and transpose has
higher precedence than multiplication, so the above expression is
equivalent to the following fully specified form (((y - mu)') * Sigma) * (y - mu).
The type of subexpression (y - mu)' * Sigma is inferred to be
row_vector, being the result of multiplying a row vector by a
matrix. The whole expression’s type is thus the type of a row vector
multiplied by a (column) vector, which produces a real value.
Stan provides elementwise matrix multiplication (e.g., a .* b) and
division (e.g., a ./ b) operations. These provide a shorthand to
replace loops, but are not intrinsically more efficient than a version
programmed with an elementwise calculations and assignments in a loop.
For example, given declarations,
vector[N] a;
vector[N] b;
vector[N] c;the assignment,
c = a .* b;produces the same result with roughly the same efficiency as the loop
for (n in 1:N)
c[n] = a[n] * b[n];Stan supports exponentiation (^) of integer and
real-valued expressions. The return type of exponentiation is always
a real-value. For example, assuming n and m are integer
variables and x and y real variables, the following
expressions are legal.
3 ^ 2
3.0 ^ -2
3.0 ^ 0.14
x ^ n
n ^ x
n ^ m
x ^ yExponentiation is right associative, so the expression 2 ^ 3 ^ 4
is equivalent to the fully specified form 2 ^ (3 ^ 4).
Operator precedence and associativity
The precedence and associativity of operators, as well as built-in syntax such as array indexing and function application is given in tabular form in the operator precedence table.
Operator Precedence Table.
Stan’s unary, binary, and ternary
operators, with their precedences, associativities, place in an
expression, and a description. The last two lines list the precedence
of function application and array, matrix, and vector indexing. The
operators are listed in order of precedence, from least tightly
binding to most tightly binding. The full set of legal arguments and
corresponding result types are provided in the function documentation
for the operators (i.e., operator*(int,int):int indicates the
application of the multiplication operator to two integers, which
returns an integer). Parentheses may be used to group expressions
explicitly rather than relying on precedence and
associativity.
| Op. | Prec. | Assoc. | Placement | Description |
|---|---|---|---|---|
? ~ : |
10 | right | ternary infix | conditional |
|| |
9 | left | binary infix | logical or |
&& |
8 | left | binary infix | logical and |
== |
7 | left | binary infix | equality |
!= |
7 | left | binary infix | inequality |
< |
6 | left | binary infix | less than |
<= |
6 | left | binary infix | less than or equal |
> |
6 | left | binary infix | greater than |
>= |
6 | left | binary infix | greater than or equal |
+ |
5 | left | binary infix | addition |
- |
5 | left | binary infix | subtraction |
* |
4 | left | binary infix | multiplication |
.* |
4 | left | binary infix | elementwise multiplication |
/ |
4 | left | binary infix | (right) division |
./ |
4 | left | binary infix | elementwise division |
% |
4 | left | binary infix | modulus |
\ |
3 | left | binary infix | left division |
! |
2 | n/a | unary prefix | logical negation |
- |
2 | n/a | unary prefix | negation |
+ |
2 | n/a | unary prefix | promotion (no-op in Stan) |
^ |
1 | right | binary infix | exponentiation |
' |
0 | n/a | unary postfix | transposition |
() |
0 | n/a | prefix, wrap | function application |
[] |
0 | left | prefix, wrap | array, matrix indexing |
Other expression-forming operations, such as function application and subscripting bind more tightly than any of the arithmetic operations.
The precedence and associativity determine how expressions are
interpreted. Because addition is left associative, the expression
a + b + c is interpreted as (a + b) + c. Similarly,
a / b * c is interpreted as (a / b) * c.
Because multiplication has higher precedence than addition, the
expression a * b + c is interpreted as (a * b) + c and the
expression a + b * c is interpreted as a + (b * c). Similarly,
2 * x + 3 * - y is interpreted as (2 * x) + (3 * (-y)).
Transposition and exponentiation bind more tightly
than any other arithmetic or logical operation.
For vectors, row vectors, and matrices,
-u' is interpreted as -(u'), u * v' as
u* (v'), and u' * v as (u') * v.
For integer and reals, -n ^ 3 is interpreted as -(n ^ 3).