types.qmd

---
pagetitle: Data Types and Declarations
---

# Data Types and Declarations {#data-types.chapter}

This chapter covers the data types for expressions in Stan.  Every
variable used in a Stan program must have a declared data type.  Only
values of that type will be assignable to the variable (except for
temporary states of transformed data and transformed parameter
values).  This follows the convention of programming languages like
C++, not the conventions of scripting languages like Python or
statistical languages such as R or BUGS.

The motivation for strong, static typing is threefold.

1. Strong typing forces the programmer's intent to be declared with
  the variable, making programs easier to comprehend and hence easier
  to debug and maintain.
2. Strong typing allows programming errors relative to the declared
  intent to be caught sooner (at compile time) rather than later (at
  run time).  The Stan compiler (called through an interface such as
  CmdStan, RStan, or PyStan) will flag any type errors and indicate
  the offending expressions quickly when the program is compiled.
3. Constrained types will catch runtime data, initialization, and
  intermediate value errors as soon as they occur rather than allowing
  them to propagate and potentially pollute final results.

Strong typing disallows assigning the same variable to objects of
different types at different points in the program or in different
invocations of the program.


## Overview of data types

Arguments for built-in and user-defined functions and local variables
are required to be basic data types, meaning an unconstrained scalar,
vector, or matrix type, or an array of such.

Passing arguments to functions in Stan works just like assignment to
basic types.  Stan functions are only specified for the basic data
types of their arguments, including array dimensionality, but not for
sizes or constraints.  Of course, functions often check constraints as
part of their behavior.

### Primitive types {-}

Stan provides two primitive data types, `real` for continuous
values and `int` for integer values.  These are both considered scalar
types.

### Complex types {-}

Stan provides a complex number data type `complex`, where a complex
number contains both a real and an imaginary component, both of which
are of type `real`.  Complex types are considered scalar types.

### Vector and matrix types {-}

Stan provides three real-valued matrix data types, `vector` for column
vectors, `row_vector` for row vectors, and `matrix` for
matrices.

Stan also provides three complex-valued matrix data types,
`complex_vector` for column vectors, `complex_row_vector` for row
vectors, and `complex_matrix` for matrices.

### Array types {-}

Any type (including the constrained types discussed in the next
section) can be made into an array type by declaring array arguments.
For example,

```stan
array[10] real x;
array[6, 7] matrix[3, 3] m;
array[12, 8, 15] complex z;
```

declares `x` to be a one-dimensional array of size 10 containing
real values, declares `m` to be a two-dimensional array of
size $6 \times 7$ containing values that are $3 \times 3$ matrices,
and declares `z` to be a $12 \times 8 \times 15$ array of complex numbers.

Prior to 2.26 Stan models used a different syntax which has since been removed.
See the [Removed Features](removals.qmd) chapter for more details.

### Tuple types {-}

For any sequence of types, Stan provides a tuple data type.  For example,

```stan
tuple(real, array[5] int) xi;
```

declares `xi` to be a tuple holding two values, the first of which is
of type type `real` and the second of which a 5-dimensional array of
type `int`.


### Constrained data types

Declarations of variables other than local variables may be provided
with constraints.  These constraints are not part of the underlying
data type for a variable, but determine error checking in the
transformed data, transformed parameter, and generated quantities
block, and the transform from unconstrained to constrained space in
the parameters block.

All of the basic data types other than `complex` may be given lower
and upper bounds using syntax such as

```stan
int<lower=1> N;
real<upper=0> log_p;
vector<lower=-1, upper=1>[3] rho;
```

There are also special data types for structured vectors and
matrices. There are five constrained vector data types, `simplex`
for unit simplexes, `unit_vector` for unit-length vectors,
`sum_to_zero_vector` for vectors that sum to zero,
`ordered` for ordered vectors of scalars, and
`positive_ordered` for vectors of positive ordered
scalars. There are specialized matrix data types `corr_matrix`
and `cov_matrix` for correlation matrices (symmetric, positive
definite, unit diagonal) and covariance matrices (symmetric, positive
definite).  The type `cholesky_factor_cov` is for Cholesky
factors of covariance matrices (lower triangular, positive diagonal,
product with own transpose is a covariance matrix).  The type
`cholesky_factor_corr` is for Cholesky factors of correlation
matrices (lower triangular, positive diagonal, unit-length rows).

Constraints provide error checking for variables defined in the
`data`, `transformed data`, `transformed parameters`,
and `generated quantities` blocks.  Constraints are critical for
variables declared in the `parameters` block, where they
determine the transformation from constrained variables (those
satisfying the declared constraint) to unconstrained variables (those
ranging over all of $\mathbb{R}^n$).

It is worth calling out the most important aspect of constrained data
types:

<div style="margin:0 2em 0 2em">
*The model must have support (non-zero density, equivalently finite
log density) at parameter values that satisfy the declared
constraints.*
</div>

If this condition is violated with parameter values that satisfy
declared constraints but do not have finite log density, then the
samplers and optimizers may have any of a number of pathologies
including just getting stuck, failure to initialize, excessive
Metropolis rejection, or biased draws due to inability to explore
the tails of the distribution.


## Primitive numerical data types {#numerical-data-types}

Unfortunately, the lovely mathematical abstraction of integers and
real numbers is only partially supported by finite-precision computer
arithmetic.

### Integers {-}

Stan uses 32-bit (4-byte) integers for all of its integer
representations.  The maximum value that can be represented
as an integer is $2^{31}-1$; the minimum value is $-(2^{31})$.

When integers overflow, their value is determined by the underlying architecture.
On most, their values wrap, but this cannot be guaranteed.  Thus it is up to the Stan
programmer to make sure the integer values in their programs stay in
range.  In particular, every intermediate expression must have an
integer value that is in range.

Integer arithmetic works in the expected way for addition,
subtraction, and multiplication, but truncates the result of division
(see [the Stan Functions Reference integer-valued arithmetic operators
section](https://mc-stan.org/docs/functions-reference/integer-valued_basic_functions.html#int-arithmetic)
for more information).

### Reals {-}

Stan uses 64-bit (8-byte) floating point representations of real
numbers.  Stan roughly^[Stan compiles integers to `int` and reals to `double` types in C++.  Precise details of rounding will depend on the compiler and hardware architecture on which the code is run.]
follows the IEEE 754 standard for floating-point computation.
The range of a 64-bit number is roughly $\pm 2^{1022}$, which is
slightly larger than $\pm 10^{307}$.  It is a good idea to stay well
away from such extreme values in Stan models as they are prone to
cause overflow.

64-bit floating point representations have roughly 15 decimal digits
of accuracy.  But when they are combined, the result often has less
accuracy.  In some cases, the difference in accuracy between two
operands and their result is large.

There are three special real values used to represent (1) not-a-number
value for error conditions, (2) positive infinity for overflow, and
(3) negative infinity for overflow.  The behavior of these special
numbers follows standard IEEE 754 behavior.

#### Not-a-number {-}

The not-a-number value propagates.  If an argument to a real-valued
function is not-a-number, it either rejects (an exception in the
underlying C++) or returns not-a-number itself.  For boolean-valued
comparison operators, if one of the arguments is not-a-number, the
return value is always zero (i.e., false).

#### Infinite values {-}

Positive infinity is greater than all numbers other than itself and
not-a-number; negative infinity is similarly smaller.  Adding an
infinite value to a finite value returns the infinite value.  Dividing
a finite number by an infinite value returns zero; dividing an
infinite number by a finite number returns the infinite number of
appropriate sign.  Dividing a finite number by zero returns positive
infinity. Dividing two infinite numbers produces a not-a-number value
as does subtracting two infinite numbers.  Some functions are
sensitive to infinite values; for example, the exponential function
returns zero if given negative infinity and positive infinity if given
positive infinity.  Often the gradients will break down when values
are infinite, making these boundary conditions less useful than they
may appear at first.


### Promoting integers to reals {-}

Stan automatically promotes integer values to real values if
necessary, but does not automatically demote real values to integers.
For very large integers, this will cause a rounding error to fewer
significant digits in the floating point representation than in the
integer representation.

Unlike in C++, real values are never demoted to integers.  Therefore,
real values may only be assigned to real variables.  Integer values
may be assigned to either integer variables or real variables.
Internally, the integer representation is cast to a floating-point
representation.  This operation is not without overhead and should
thus be avoided where possible.

## Complex numerical data type

The `complex` data type is a scalar, but unlike `real` and `int`
types, it contains two components, a real and imaginary component,
both of which are of type `real`.  That is, the real and imaginary
components of a complex number are 64-bit, IEEE 754-complaint floating
point numbers.

### Constructing and accessing complex numbers {-}

Imaginary literals are written in mathematical notation using a
numeral followed by the suffix `i`.  For example, the following
example constructs a complex number $2 - 1.3i$ and assigns it to
the variable `z`.

```stan
complex z = 2 - 1.3i;
real re = get_real(z);  // re has value 2.0
real im = get_imag(z);  // im has value -1.3
```

The getter functions then extract the real and imaginary components of
`z` and assign them to `re` and `im` respectively.

The function `to_complex` constructs a complex number from its real
and imaginary components.  The functional form needs to be used
whenever the components are not literal numerals, as in the following
example.

```stan
vector[K] re;
vector[K] im;
// ...
for (k in 1:K) {
  complex z = to_complex(re[k], im[k]);
  // ...
}
```

### Promoting real to complex {-}

Expressions of type `real` may be assigned to variables of type
`complex`.  For example, the following is a valid sequence of Stan
statements.

```stan
real x = 5.0;
complex z = x;  // get_real(z) == 5.0, get_imag(z) == 0
```

The real number assigned to a complex number determine's the complex
number's real component, with the imaginary component set to zero.

Assignability is transitive, so that expressions of type `int` may
also be assigned to variables of type `complex`, as in the following
example.

```stan
int n = 2;
complex z = n;
```

Function arguments also support promotion of integer or real typed
expressions to type `complex`.


## Scalar data types and variable declarations

All variables used in a Stan program must have an explicitly declared
data type.  The form of a declaration includes the type and the name
of a variable.  This section covers scalar types, namely integer,
real, and complex.  The next section covers vector and matrix types,
and the following section array types.

### Unconstrained integer {-}

Unconstrained integers are declared using the `int` keyword.
For example, the variable `N` is declared to be an integer as follows.

```stan
int N;
```


### Constrained integer {-}

Integer data types may be constrained to allow values only in a
specified interval by providing a lower bound, an upper bound, or
both.  For instance, to declare `N` to be a positive integer, use
the following.

```stan
int<lower=1> N;
```

This illustrates that the bounds are inclusive for integers.

To declare an integer variable `cond` to take only binary values,
that is zero or one, a lower and upper bound must be provided, as in
the following example.

```stan
int<lower=0, upper=1> cond;
```


### Unconstrained real {-}

Unconstrained real variables are declared using the keyword
`real`. The following example declares `theta` to be an
unconstrained continuous value.

```stan
real theta;
```

### Unconstrained complex {-}

Unconstrained complex numbers are declared using the keyword
`complex`.  The following example declares `z` to be an unconstrained
complex variable.

```stan
complex z;
```


### Constrained real {-}

Real variables may be bounded using the same syntax as integers.  In
theory (that is, with arbitrary-precision arithmetic), the bounds on
real values would be exclusive.  Unfortunately, finite-precision
arithmetic rounding errors will often lead to values on the
boundaries, so they are allowed in Stan.

The variable `sigma` may be declared to be non-negative as follows.

```stan
real<lower=0> sigma;
```

The following declares the variable `x` to be less than or equal
to $-1$.

```stan
real<upper=-1> x;
```

To ensure `rho` takes on values between $-1$ and $1$, use the
following declaration.

```stan
real<lower=-1, upper=1> rho;
```

#### Infinite constraints {-}

Lower bounds that are negative infinity or upper bounds that are
positive infinity are ignored.  Stan provides constants
`positive_infinity()` and `negative_infinity()` which may
be used for this purpose, or they may be supplied as data.


### Affinely transformed real {#affine-transform.section}

Real variables may be declared on a space that has been transformed using an
affine transformation $x\mapsto \mu + \sigma * x$ with offset $\mu$ and
(positive) multiplier $\sigma$, using a syntax similar to
that for bounds.
While these transforms do not change the asymptotic sampling behaviour of
the resulting Stan program (in a sense, the model the program implements),
they can be useful for making the sampling process
more efficient by transforming the geometry of the problem to a more natural
multiplier and to a more natural offset for the sampling process,
for instance by facilitating a non-centered parameterisation.
While these affine transformation declarations do not impose a hard constraint
on variables, they behave like the bounds constraints in many ways and could
perhaps be viewed as acting as a sort of soft constraint.

The variable `x` may be declared to have offset $1$ as follows.

```stan
real<offset=1> x;
```

Similarly, it can be declared to have multiplier $2$ as follows.

```stan
real<multiplier=2> x;
```

Finally, we can combine both declarations to declare a variable with offset
$1$ and multiplier $2$.

```stan
real<offset=1, multiplier=2> x;
```

As an example, we can give `x` a normal distribution with non-centered parameterization.
In this program, the affine transform is applied to every element of vector `x`.

```stan
parameters {
  real<offset=mu, multiplier=sigma> x;
}
model {
  x ~ normal(mu, sigma);
}
```

Recall the Stan code for the centered parameterization of this model.

```stan
parameters {
  real x;
}
model {
  x ~ normal(mu, sigma);
}
```

Adding the offset, multiplier transform results in the equivalent non-centered parameterization.

```stan
parameters {
  real<offset=mu, multiplier=sigma> x;
}
model {
  x ~ normal(mu, sigma);
}
```

Sampling is done on the unconstrained parameters.
After applying the affine transform, the unconstrained parameters are standard normal,
thus the above model is equivalent to the hand-coded non-centered parameterization.

```stan
parameters {
  real x_raw;
}
transformed parameters {
  real x = mu + x_raw * sigma;
}
model {
  x_raw ~ std_normal();
}
```

Use of the affine transform removes the overhead of declaring additional transformed parameters
and directly expresses the hierarchical relationship between parameters.

For a container variable, the affine transform is applied to each element of that variable.
As an example, the non-centered parameterization of Neal's Funnel in the
[Stan User's Guide reparameterization section](https://mc-stan.org/docs/stan-users-guide/reparameterization.html),
$$
p(y,x) = \textsf{normal}(y \mid 0,3) \times \prod_{n=1}^9
\textsf{normal}(x_n \mid 0,\exp(y/2)).
$$
can be written as:

```stan
parameters {
  real<multiplier=3> y;
  vector<multiplier=exp(0.5 * y)>[9] x;
}
model {
  y ~ normal(0, 3); 
  x ~ std_normal(0, 0.5 * y);
}
```
where the affine transform is applied to every element of vector `x`.

### Expressions as bounds and offset/multiplier {-}

Bounds (and offset and multiplier)
for integer or real variables may be arbitrary expressions.
The only requirement is that they only include variables that have
been declared (though not necessarily defined) before the declaration.  array[N] row_vector[D] x;
If the bounds themselves are parameters, the behind-the-scenes
variable transform accounts for them in the log Jacobian.

For example, it is acceptable to have the
following declarations.

```stan
data {
 real lb;
}
parameters {
   real<lower=lb> phi;
}
```

This declares a real-valued parameter `phi` to take values
greater than the value of the real-valued data variable `lb`.
Constraints may be arbitrary expressions, but must be of type `int`
for integer variables and of type `real` for real variables
(including constraints on vectors, row vectors, and matrices).
Variables used in constraints can be any variable that has been
defined at the point the constraint is used.  For instance,
```stan
data {
   int<lower=1> N;
   array[N] real y;
}
parameters {
   real<lower=min(y), upper=max(y)> phi;
}
```

This declares a positive integer data variable `N`, an array
`y` of real-valued data of length `N`, and then a parameter
ranging between the minimum and maximum value of `y`.  As shown
in the example code, the functions `min()` and `max()` may
be applied to containers such as arrays.

A more subtle case involves declarations of parameters or transformed
parameters based on parameters declared previously.  For example, the
following program will work as intended.

```stan
parameters {
  real a;
  real<lower=a> b;  // enforces a < b
}
transformed parameters {
  real c;
  real<lower=c> d;
  c = a;
  d = b;
}
```

The parameters instance works because all parameters are defined
externally before the block is executed.  The transformed parameters
case works even though `c` isn't defined at the point it is used,
because constraints on transformed parameters are only validated at
the end of the block.  Data variables work like parameter variables,
whereas transformed data and generated quantity variables work like
transformed parameter variables.

### Declaring optional variables {-}

A variable may be declared with a size that depends on a boolean
constant.  For example, consider the definition of `alpha` in the
following program fragment.

```stan
data {
  int<lower=0, upper=1> include_alpha;
  // ...
}
parameters {
  vector[include_alpha ? N : 0] alpha;
  // ...
}
```

If `include_alpha` is true, the model will include the vector
`alpha`;  if the flag is false, the model will not include
`alpha` (technically, it will include `alpha` of size 0,
which means it won't contain any values and won't be included in any
output).

This technique is not just useful for containers.  If the value of
`N` is set to 1, then the vector `alpha` will contain a
single element and thus `alpha[1]` behaves like an optional
scalar, the existence of which is controlled by `include_alpha`.

This coding pattern allows a single Stan program to define different
models based on the data provided as input.  This strategy is used
extensively in the implementation of the [RStanArm package](https://mc-stan.org/rstanarm).

## Vector and matrix data types

Stan provides three types of container objects: arrays, vectors, and
matrices. Vectors and matrices are more limited kinds of data
structures than arrays.  Vectors are intrinsically one-dimensional
collections of real or complex values, whereas matrices are
intrinsically two dimensional.  Vectors, matrices, and arrays are not
assignable to one another, even if their dimensions are identical.  A
$3 \times 4$ matrix is a different kind of object in Stan than a $3
\times 4$ array.

The intention of using matrix types is to call out their usage in the
code.  There are three situations in Stan where *only* vectors and
matrices may be used,

* matrix arithmetic operations (e.g., matrix multiplication)
* linear algebra functions (e.g., eigenvalues and determinants),
  and
* multivariate function parameters and outcomes (e.g.,
  multivariate normal distribution arguments).

Vectors and matrices cannot be typed to return integer values.  They
are restricted to `real` and `complex` values.

For constructing vectors and matrices in Stan, see [Vector, Matrix,
and Array Expressions](expressions.qmd#vector-matrix-array-expressions.section).

### Indexing from 1 {-}

Vectors and matrices, as well as arrays, are indexed starting from one
(1) in Stan.  This follows the convention in statistics and linear
algebra as well as their implementations in the statistical software
packages R, MATLAB, BUGS, and JAGS.  General computer programming
languages, on the other hand, such as C++ and Python, index arrays
starting from zero.

### Vectors {-}

Vectors in Stan are column vectors; see below for information on row
vectors.  Vectors are declared with a size (i.e., a dimensionality).
For example, a 3-dimensional real vector is declared with the keyword
`vector`, as follows.

```stan
vector[3] u;
```

Vectors may also be declared with constraints, as in the following
declaration of a 3-vector of non-negative values.

```stan
vector<lower=0>[3] u;
```

Similarly, they may be declared with a offset and/or multiplier, as in the
following example
```stan
vector<offset=42, multiplier=3>[3] u;
```

### Complex vectors {-}

Like real vectors, complex vectors are column vectors and are declared
with a size.  For example, a 3-dimensional complex vector is declared
with the keyword `complex_vector`, as follows.

```stan
complex_vector[3] v;
```

Complex vector declarations do not support any constraints.

### Unit simplexes {-}

A unit simplex is a vector with non-negative values whose entries sum
to 1.  For instance, $[0.2,0.3,0.4,0.1]^{\top}$ is a unit 4-simplex.
Unit simplexes are most often used as parameters in categorical
or multinomial distributions, and they are also the sampled variate in
a Dirichlet distribution.  Simplexes are declared with their full
dimensionality.  For instance, `theta` is declared to
be a unit $5$-simplex by

```stan
simplex[5] theta;
```

Unit simplexes are implemented as vectors and may be assigned to other
vectors and vice-versa.  Simplex variables, like other constrained
variables, are validated to ensure they contain simplex values; for
simplexes, this is only done up to a statically specified accuracy
threshold $\epsilon$ to account for errors arising from floating-point
imprecision.

In high dimensional problems, simplexes may require smaller step sizes
in the inference algorithms in order to remain stable; this can be
achieved through higher target acceptance rates for samplers and
longer warmup periods, tighter tolerances for optimization with more
iterations, and in either case, with less dispersed parameter
initialization or custom initialization if there are informative
priors for some parameters.

### Stochastic Matrices {-}

A stochastic matrix is a matrix where each column or row is a
unit simplex, meaning that each column (row) vector has non-negative
values that sum to 1. The following example is a $3 \times 4$
column-stochastic matrix.

$$
\begin{bmatrix}
0.2 & 0.5 & 0.1 & 0.3 \\
0.3 & 0.3 & 0.6 & 0.4 \\
0.5 & 0.2 & 0.3 & 0.3
\end{bmatrix}
$$

An example of a $3 \times 4$ row-stochastic matrix is the following.

$$
\begin{bmatrix}
0.2 & 0.5 & 0.1 & 0.2 \\
0.2 & 0.1 & 0.6 & 0.1 \\
0.5 & 0.2 & 0.2 & 0.1
\end{bmatrix}
$$


In the examples above, each column (or row) sums to 1, making the matrices
valid `column_stochastic_matrix` and `row_stochastic_matrix` types.

Column-stochastic matrices are often used in models where
each column represents a probability distribution across a
set of categories such as in multiple multinomial distributions,
factor models, transition matrices in Markov models,
or compositional data analysis.
They can also be used in situations where you need multiple simplexes
of the same dimensionality.

The `column_stochastic_matrix` and `row_stochastic_matrix` types are declared
with row and column sizes. For instance, a matrix `theta` with
3 rows and 4 columns, where each
column is a 3-simplex, is declared like a matrix with 3 rows and 4 columns.

```stan
column_stochastic_matrix[3, 4] theta;
```

A matrix `theta` with 3 rows and 4 columns, where each row is a 4-simplex,
is similarly declared as a matrix with 3 rows and 4 columns.

```stan
row_stochastic_matrix[3, 4] theta;
```

As with simplexes, `column_stochastic_matrix` and `row_stochastic_matrix`
variables are subject to validation, ensuring that each column (row)
satisfies the simplex constraints. This validation accounts for
floating-point imprecision, with checks performed up to a statically
specified accuracy threshold $\epsilon$.

#### Stability Considerations {-}

In high-dimensional settings, `column_stochastic_matrix` and `row_stochastic_matrix`
types may require careful tuning of the inference
algorithms. To ensure stability:

- **Smaller Step Sizes:** In samplers like Hamiltonian Monte Carlo (HMC),
smaller step sizes can help maintain stability, especially in high dimensions.
- **Higher Target Acceptance Rates:** Setting higher target acceptance
rates can improve the robustness of the sampling process.
- **Longer Warmup Periods:** Increasing the warmup period allows the sampler
to better explore the parameter space before the actual sampling begins.
- **Tighter Optimization Tolerances:** For optimization-based inference,
tighter tolerances with more iterations can yield more accurate results.
- **Custom Initialization:** If prior information about the parameters is
available, custom initialization or less dispersed initialization can lead
to more efficient inference.

### Unit vectors {-}

A unit vector is a vector with a norm of one.  For instance, $[0.5,
0.5, 0.5, 0.5]^{\top}$ is a unit 4-vector.  Unit vectors are sometimes
used in directional statistics.  Unit vectors are declared with their
full dimensionality.  For instance, `theta` is declared to be a unit
$5$-vector by

```stan
unit_vector[5] theta;
```

Unit vectors are implemented as vectors and may be assigned to other
vectors and vice-versa.  Unit vector variables, like other constrained
variables, are validated to ensure that they are indeed unit length; for
unit vectors, this is only done up to a statically specified accuracy
threshold $\epsilon$ to account for errors arising from floating-point
imprecision.

### Vectors that sum to zero {-}

A zero-sum vector is constrained such that the
sum of its elements is always $0$. These are sometimes useful
for resolving identifiability issues in regression models.
While the underlying vector has only $N - 1$ degrees of freedom,
zero sum vectors are declared with their full dimensionality.
For instance, `beta` is declared to be a zero-sum $5$-vector (4 DoF) by

```stan
sum_to_zero_vector[5] beta;
```

Zero sum vectors are implemented as vectors and may be assigned to other
vectors and vice-versa.  Zero sum vector variables, like other constrained
variables, are validated to ensure that they are indeed unit length; for
zero sum  vectors, this is only done up to a statically specified accuracy
threshold $\epsilon$ to account for errors arising from floating-point
imprecision.

### Ordered vectors {-}

An ordered vector type in Stan represents a vector whose entries are
sorted in ascending order.  For instance, $(-1.3,2.7,2.71)^{\top}$ is
an ordered 3-vector.  Ordered vectors are most often employed as cut
points in ordered logistic regression models (see
[section](https://mc-stan.org/docs/stan-users-guide/regression.html#ordered-logistic.section)).

The variable `c` is declared as an ordered 5-vector by

```stan
ordered[5] c;
```

After their declaration, ordered vectors, like unit simplexes, may be
assigned to other vectors and other vectors may be assigned to them.
Constraints will be checked after executing the block in which the
variables were declared.

### Positive, ordered vectors {-}

There is also a positive, ordered vector type which operates similarly
to ordered vectors, but all entries are constrained to be positive.
For instance, $(2,3.7,4,12.9)$ is a positive, ordered 4-vector.

The variable `d` is declared as a positive, ordered 5-vector by

```stan
positive_ordered[5] d;
```

Like ordered vectors, after their declaration, positive ordered vectors
may be assigned to other vectors and other vectors may be assigned to them.
Constraints will be checked after executing the block in which the
variables were declared.



### Row vectors {-}

Row vectors are declared with the keyword `row_vector`.
Like (column) vectors, they are declared with a size.  For example,
a 1093-dimensional row vector `u` would be declared as

```stan
row_vector[1093] u;
```

Constraints are declared as for vectors, as in the following example
of a 10-vector with values between -1 and 1.
```stan
row_vector<lower=-1, upper=1>[10] u;
```
Offset and multiplier are also similar as for the following 3-row-vector with
offset -42 and multiplier 3.
```stan
row_vector<offset=-42, multiplier=3>[3] u;
```

Row vectors may not be assigned to column vectors, nor may column
vectors be assigned to row vectors.  If assignments are required, they
may be accommodated through the transposition operator.

### Complex row vectors {-}

Complex row vectors are declared with the keyword
`complex_row_vector` and given a size in basic declarations.  For
example, a 12-dimensional complex row vector `v` would be declared as

```stan
complex_row_vector[12] v;
```

Complex row vectors do not allow constraints.

### Matrices {-}

Matrices are declared with the keyword `matrix` along with a
number of rows and number of columns.  For example,

```stan
matrix[3, 3] A;
matrix[M, N] B;
```

declares `A` to be a $3 \times 3$ matrix and `B` to be a $M
\times N$ matrix.  For the second declaration to be well formed, the
variables `M` and `N` must be declared as integers in either
the data or transformed data block and before the matrix declaration.

Matrices may also be declared with constraints, as in this ($3 \times 4$)
matrix of non-positive values.

```stan
matrix<upper=0>[3, 4] B;
```

Similarly, matrices can be declared to have a set offset and/or multiplier, as in
this matrix with multiplier 5.
```stan
matrix<multiplier=5>[3, 4] B;
```

#### Assigning to rows of a matrix {-}

Rows of a matrix can be assigned by indexing the left-hand side of an
assignment statement. For example, this is possible.

```stan
matrix[M, N] a;
row_vector[N] b;
// ...
a[1] = b;
```

This copies the values from row vector `b` to `a[1]`, which
is the first row of the matrix `a`.  If the number of columns in
`a` is not the same as the size of `b`, a run-time error is
raised;  the number of columns of `a` is `N`, which is also the
number of columns of `b`.

Assignment works by copying values in Stan.  That means any subsequent
assignment to `a[1]` does not affect `b`, nor does an
assignment to `b` affect `a`.

### Complex matrices {-}

Complex matrices are declared with the keyword `complex_matrix` and a
number of rows and columns.  For example,

```stan
complex_matrix[3, 3] C;
```

Complex matrices do not allow constraints.


### Covariance matrices {-}

Matrix variables may be constrained to represent covariance matrices.
A matrix is a covariance matrix if it is symmetric and positive
definite.  Like correlation matrices, covariance matrices only need a
single dimension in their declaration.  For instance,

```stan
cov_matrix[K] Sigma;
```

declares `Sigma` to be a $K \times K$ covariance matrix, where
$K$ is the value of the data variable `K`.


### Correlation matrices {-}

Matrix variables may be constrained to represent correlation matrices.
A matrix is a correlation matrix if it is symmetric and positive
definite, has entries between $-1$ and $1$, and has a unit diagonal.
Because correlation matrices are square, only one dimension needs
to be declared.  For example,

```stan
corr_matrix[3] Omega;
```

declares `Omega` to be a $3 \times 3$ correlation matrix.

Correlation matrices may be assigned to other matrices, including
unconstrained matrices, if their dimensions match, and vice-versa.


### Cholesky factors of covariance matrices {-}

Matrix variables may be constrained to represent the Cholesky factors
of a covariance matrix.  This is often more convenient or more
efficient than representing covariance matrices directly.

A Cholesky factor $L$ is an $M \times N$ lower-triangular matrix (if
$m < n$ then $L[m, n] =0$) with a strictly positive diagonal ($L[k, k]
> 0$) and $M \geq N$.  If $L$ is a Cholesky factor, then $\Sigma = L
\, L^{\top}$ is a covariance matrix (i.e., it is positive definite).
The mapping between positive definite matrices and their Cholesky
factors is bijective---every covariance matrix has a unique Cholesky
factorization.

The typical case of a square Cholesky factor may be declared with a
single dimension,

```stan
cholesky_factor_cov[4] L;
```

#### Cholesky factors of positive semi-definite matrices {-}

In general, two dimensions may be declared, with the above being equal to
`cholesky_factor_cov[4, 4]`.  The
type `cholesky_factor_cov[M, N]` may be used for the general
$M \times N$ case to produce positive semi-definite matrices of rank $M$.


### Cholesky factors of correlation matrices {-}

Matrix variables may be constrained to represent the Cholesky factors
of a correlation matrix.

A Cholesky factor for a correlation matrix $L$ is a $K \times K$
lower-triangular matrix with positive diagonal entries and rows that
are of length 1 (i.e., $\sum_{n=1}^K L_{m,n}^2 = 1$).  If $L$ is a
Cholesky factor for a correlation matrix, then $L\,L^{\top}$ is a
correlation matrix (i.e., symmetric positive definite with a unit
diagonal).

To declare the variable `L` to be a `K` by `K` Cholesky factor of a
correlation matrix, the following code may be used.

```stan
cholesky_factor_corr[K] L;
```


### Assigning constrained variables {-}

Constrained variables of all types may be assigned to other variables
of the same unconstrained type and vice-versa.  Matching is interpreted strictly
as having the same basic type and number of array dimensions.
Constraints are not considered, but basic data types are. For instance, a
variable declared to be `real<lower=0, upper=1>` could be assigned
to a variable declared as `real` and vice-versa.  Similarly, a
variable declared as `matrix[3, 3]` may be assigned to a variable
declared as `cov_matrix[3]` or
`cholesky_factor_cov[3]`, and vice-versa.

Checks are carried out at the end of each relevant block of statements
to ensure constraints are enforced.  This includes run-time size
checks.  The Stan compiler isn't able to catch the fact that an
attempt may be made to assign a matrix of one dimensionality to a
matrix of mismatching dimensionality.

### Promoting real to complex matrixes {-}

Real-valued vectors, row vectors and matrices may be assigned to
complex-valued vectors, row vectors and matrices, respectively.  For
example, the following is legal.

```stan
vector[N] v = ...;
complex_vector[N] u = 2 * v;
```

Row vectors and matrices work the same way.


### Expressions as size declarations {-}

Variables may be declared with sizes given by expressions.  Such
expressions are constrained to only contain data or transformed data
variables.  This ensures that all sizes are determined once the data
is read in and transformed data variables defined by their statements.
For example, the following is legal.

```stan
data {
  int<lower=0> N_observed, N_missing;
  // ...
transformed parameters {
  vector[N_observed + N_missing] y;
  // ...
```

### Accessing vector and matrix elements {-}

If `v` is a column vector or row vector, then `v[2]` is the
second element in the vector.  If `m` is a matrix, then
`m[2, 3]` is the value in the second row and third column.

Providing a matrix with a single index returns the specified row.  For
instance, if `m` is a matrix, then `m[2]` is the second row.
This allows Stan blocks such as

```stan
matrix[M, N] m;
row_vector[N] v;
real x;
// ...
v = m[2];
x = v[3];   // x == m[2][3] == m[2, 3]
```

The type of `m[2]` is `row_vector` because it is the second
row of `m`.  Thus it is possible to write `m[2][3]` instead
of `m[2, 3]` to access the third element in the second row.  When
given a choice, the form `m[2, 3]` is preferred.

Complex versions work the same way,

```stan
complex_matrix[M, N] m = ...;
complex_row_vector[N] u = m[3];
complex_vector[M] v = m[ , 2];
```


#### Array index style {#array-index-style}

The form `m[2, 3]` is more efficient because it does not require the creation and use of an intermediate expression template for `m[2]`.  In later versions, explicit calls to `m[2][3]` may be optimized to be as efficient as `m[2, 3]` by the Stan compiler.


### Size declaration restrictions {-}

An integer expression is used to pick out the sizes of vectors,
matrices, and arrays.  For instance, we can declare a vector of size
`M + N` using

```stan
vector[M + N] y;
```

Any integer-denoting expression may be used for the size declaration,
providing all variables involved are either data, transformed data, or
local variables.  That is, expressions used for size declarations may
not include parameters or transformed parameters or generated
quantities.

## Array data types {#array-data-types.section}

Stan supports arrays of arbitrary dimension.  The values in an array
can be any type, so that arrays may contain values that are simple
reals or integers, vectors, matrices, or other arrays.  Arrays are the
only way to store sequences of integers, and some functions in Stan,
such as discrete distributions, require integer arguments.

A two-dimensional array is just an array of arrays, both conceptually
and in terms of current implementation.  When an index is supplied to
an array, it returns the value at that index.  When more than one
index is supplied, this indexing operation is chained.  For example, if
`a` is a two-dimensional array, then `a[m, n]` is just
a convenient shorthand for `a[m][n]`.

Vectors, matrices, and arrays are not assignable to one another, even
if their dimensions are identical.

For constructing arrays in Stan, see [Vector, Matrix, and Array Expressions](expressions.qmd#vector-matrix-array-expressions.section).

### Declaring array variables {-}

Arrays are declared with the keyword `array` followed by the dimensions
enclosed in square brackets, the element type, and the name of the variable.

The variable `n` is declared as an array of five integers as follows.

```stan
array[5] int n;
```

A two-dimensional array of complex values with three rows and four columns is
declared as follows.

```stan
array[3, 4] complex a;
```

A three-dimensional array `z` of positive reals with five rows, four
columns, and two shelves can be declared as follows.

```stan
array[5, 4, 2] real<lower=0> z;
```


Arrays may also be declared to contain vectors.  For example,

```stan
array[3] vector[7] mu;
```

declares `mu` to be an array of size 3 containing vectors with 7
elements.  Arrays may also contain matrices.  The example

```stan
array[15, 12] complex_matrix[7, 2] mu;
```

declares a 15 by 12 array of $7 \times 2$ complex matrices.  Any of
the constrained types may also be used in arrays, as in the
declaration

```stan
array[2, 3, 4] cholesky_factor_cov[5, 6] mu;
```

of a $2 \times 3 \times 4$ array of $5 \times 6$ Cholesky factors of
covariance matrices.


### Accessing array elements and subarrays {-}

If `x` is a 1-dimensional array of length 5, then `x[1]` is
the first element in the array and `x[5]` is the last.  For a $3
\times 4$ array `y` of two dimensions, `y[1, 1]` is the first
element and `y[3, 4]` the last element.  For a three-dimensional
array `z`, the first element is `z[1, 1, 1]`, and so on.

Subarrays of arrays may be accessed by providing fewer than the full
number of indexes.  For example, suppose `y` is a two-dimensional
array with three rows and four columns.  Then `y[3]` is
one-dimensional array of length four.  This means that `y[3][1]`
may be used instead of `y[3, 1]` to access the value of the first
column of the third row of `y`.  The form `y[3, 1]` is the
preferred form (see [note](#array-index-style) in this chapter).

### Assigning {-}

Subarrays may be manipulated and assigned just like any other
variables.  Similar to the behavior of matrices, Stan allows blocks
such as

```stan
array[9, 10, 11] real w;
array[10, 11] real x;
array[11] real y;
real z;
// ...
x = w[5];
y = x[4];  // y == w[5][4] == w[5, 4]
z = y[3];  // z == w[5][4][3] == w[5, 4, 3]
```

Complex-valued arrays work the same way.


### Arrays of matrices and vectors {-}

Arrays of vectors and matrices are accessed in the same way as arrays
of doubles.  Consider the following vector and scalar declarations.

```stan
array[3, 4] vector[5] a;
array[4] vector[5] b;
vector[5] c;
real x;
```

With these declarations, the following assignments are legal.

```stan
b = a[1];       // result is array of vectors
c = a[1, 3];    // result is vector
c = b[3];       //   same result as above
x = a[1, 3, 5]; // result is scalar
x = b[3, 5];    //   same result as above
x = c[5];       //   same result as above
```

Row vectors and other derived vector types (simplex and ordered)
behave the same way in terms of indexing.

Consider the following matrix, vector and scalar declarations.

```stan
array[3, 4] matrix[6, 5] d;
array[4] matrix[6, 5] e;
matrix[6, 5] f;
row_vector[5] g;
real x;
```

With these declarations, the following definitions are legal.

```stan
e = d[1];           // result is array of matrices
f = d[1, 3];        // result is matrix
f = e[3];           //   same result as above
g = d[1, 3, 2];     // result is row vector
g = e[3, 2];        //   same result as above
g = f[2];           //   same result as above
x = d[1, 3, 5, 2];  // result is scalar
x = e[3, 5, 2];     //   same result as above
x = f[5, 2];        //   same result as above
x = g[2];           //   same result as above
```

As shown, the result `f[2]` of supplying a single index to a
matrix is the indexed row, here row 2 of matrix `f`.


### Partial array assignment {-}

Subarrays of arrays may be assigned by indexing on the left-hand side
of an assignment statement.  For example, the following is legal.

```stan
array[I, J, K] real x;
array[J, K] real y;
array[K] real z;
// ...
x[1] = y;
x[1, 1] = z;
```

The sizes must match.  Here, `x[1]` is a `J` by `K`
array, as is `y`.

Partial array assignment also works for arrays of matrices, vectors,
and row vectors.


### Mixing array, vector, and matrix types {-}

Arrays, row vectors, column vectors and matrices are not
interchangeable in Stan.  Thus a variable of any one of these
fundamental types is not assignable to any of the others, nor may it
be used as an argument where the other is required (use as arguments
follows the assignment rules).



#### Mixing vectors and arrays {-}

For example, vectors cannot be assigned to arrays or vice-versa.

```stan
array[4] real a;
vector[4] b;
row_vector[4] c;
// ...
a = b; // illegal assignment of vector to array
b = a; // illegal assignment of array to vector
a = c; // illegal assignment of row vector to array
c = a; // illegal assignment of array to row vector
```

#### Mixing row and column vectors {-}

It is not even legal to assign row vectors to column vectors or vice
versa.
```stan
vector[4] b;
row_vector[4] c;
// ...
b = c; // illegal assignment of row vector to column vector
c = b; // illegal assignment of column vector to row vector
```


#### Mixing matrices and arrays {-}

The same holds for matrices, where 2-dimensional arrays may not be
assigned to matrices or vice-versa.

```stan
array[3, 4] real a;
matrix[3, 4] b;
// ...
a = b;  // illegal assignment of matrix to array
b = a;  // illegal assignment of array to matrix
```


#### Mixing matrices and vectors {-}

A $1 \times N$ matrix cannot be assigned a row vector or
vice versa.

```stan
matrix[1, 4] a;
row_vector[4] b;
// ...
a = b;  // illegal assignment of row vector to matrix
b = a;  // illegal assignment of matrix to row vector
```

Similarly, an $M \times 1$ matrix may not be assigned to a column vector.

```stan
matrix[4, 1] a;
vector[4] b;
// ...
a = b;  // illegal assignment of column vector to matrix
b = a;  // illegal assignment of matrix to column vector
```

### Size declaration restrictions {-}

An integer expression is used to pick out the sizes of arrays.  The
same restrictions as for vector and matrix sizes apply, namely that
the size is declared with an integer-denoting expression that does not
contain any parameters, transformed parameters, or generated quantities.

### Size zero arrays {-}

If any of an array's dimensions is size zero, the entire array will be
of size zero.  That is, if we declare

```stan
array[3, 0] real a;
```

then the resulting size of `a` is zero and querying any of its
dimensions at run time will result in the value zero.  Declared as
above, `a[1]` will be a size-zero one-dimensional array.  For
comparison, declaring

```stan
array[0, 3] real b;
```

also produces an array with an overall size of zero, but in this case,
there is no way to index legally into `b`, because `b[0]` is
undefined.  The array will behave at run time as if it's a $0 \times
0$ array.  For example, the result of `to_matrix(b)` will be a
$0 \times 0$ matrix, not a $0 \times 3$ matrix.


## Tuple data type

Stan supports tuples of arbitrary size.  The values in a tuple can be
of arbitrary type, but the component types must be declared along with
the declaration of the tuple.  Tuples can be manipulated as a whole,
or their elements may be accessed and set individually.

### Declaring tuple variables {-}

Tuples are declared with the keyword `tuple` followed by a
parenthesized sequence of types, which determine the types of the
respective tuple entries.  For example, a tuple with three elements
may be declared as

```stan
tuple(int, vector[3], complex) abc;
```

Tuples must have at least two entries, so the following declarations
are illegal.

```stan
tuple() nil;  // ILLEGAL
tuple(int) n;  // ILLEGAL
```

Tuples can be assigned as a whole if their elements can be assigned
individually.  For example, `a` can be assigned to `b` in the
following example because `int` can be promoted to `complex`.

```stan
tuple(int, real) a;
...
tuple(complex, real) b = a;
```

Tuple types may have elements which are declared as tuples, such as
the following example.

```stan
tuple(int, tuple(real, complex)) x;
```

In this case, it would probably be simpler to use a 3-tuple type,
`tuple(int, real, complex)`.


Tuples can be declared with constraints anywhere that ordinary
variables can (i.e., as top-level block variables).  That means any
context in which it is legal to have a declaration

```stan
real<lower=0> sigma;
real<lower=0, upper=1> theta;
```

it is legal to have a tuple with constraints such as

```stan
tuple(real<lower=0>, real<lower=0, upper=1>) sigma_theta;
```



### Accessing tuple elements {-}

Tuple elements may be accessed directly.  For example, with our
declaration of `abc` from the last section, Stan uses `abc.1` for the
first element, `abc.2` for the second, and `abc.3` for the third.
These numbers must be integer literals (i.e., they cannot be
variables), and must be within the size of the number of elements of
tuples.  The types of elements are as declared, so that `abc.1` is of
type `int`, `abc.2` of type `vector[3]` and `abc.3` of type `complex`.

### Assigning tuple elements {-}

Tuple elements can be assigned individually, allowing, e.g.,

```stan
tuple(int, real) ab;
ab.1 = 123;
ab.2 = 12.9;
```

As with other assignments, promotions will happen if necessary (of
`int` to `real` and of `real` to `complex`, along with the
corresponding container type promotions).

### Unpacking assignment of tuples {-}

For convenience of using values stored in tuples, Stan supports
"unpacking" (or "destructuring") of tuples in an assignment statement.

Given a tuple `t` of type `tuple(T1, ..., Tn)` and a sequence of
[assignable expressions](#rhs-expressions) of types
`v1`, ..., `vn`, where each `vi` has a [type which is assignable](statements.qmd#promotion)
from type `Ti`, individual elements of the tuple may be assigned to the
corresponding variables in the sequence by the statement

```stan
(v1, /*...*/, vn) = t;
```

Note that the above parenthesis are required, unlike in some other
languages with similar features (e.g., Python).

These unpacking assignments can be nested if the tuple on the right hand
side contains nested tuples.

For example, if `T` is a tuple of type `tuple(int, (real, real), complex)`,
then the program

```stan
int i;
real x, y;
complex z;

(i, (x, y), z) = T;
```

Assigns the result of `T.1` to `i`, the result of `T.2.1` to `x`,
the result of `T.2.2` to `y`, and the result of `T.3` to `z`.

The left hand side must match in size the tuple on the right.
Additionally, the same variable may not appear more
than once in the left hand side of an unpacking assignment.


## Variable types vs. constraints and sizes

The type information associated with a variable only contains the
underlying type and dimensionality of the variable.

### Type information excludes sizes {-}

The size associated with a given variable is not part of its data
type.  For example, declaring a variable using
```stan
array[3] real a;
```

declares the variable `a` to be an array.  The fact that it was
declared to have size 3 is part of its declaration, but not part of
its underlying type.

#### When are sizes checked? {-}

Sizes are determined dynamically (at run time) and thus cannot be
type-checked statically when the program is compiled.  As a result,
any conformance error on size will raise a run-time error.  For
example, trying to assign an array of size 5 to an array of size 6
will cause a run-time error.  Similarly, multiplying an $N \times M$
by a $J \times K$ matrix will raise a run-time error if $M \neq J$.

### Type information excludes constraints {-}

Like sizes, constraints are not treated as part of a variable's type
in Stan when it comes to the compile-time check of operations it may
participate in.  Anywhere Stan accepts a matrix as an argument, it
will syntactically accept a correlation matrix or covariance matrix or
Cholesky factor.  Thus a covariance matrix may be assigned to a matrix
and vice-versa.

Similarly, a bounded real may be assigned to an unconstrained real and
vice-versa.

#### When are function argument constraints checked? {-}

For arguments to functions, constraints are sometimes, but not always
checked when the function is called.  Exclusions include C++ standard
library functions.  All probability functions and cumulative
distribution functions check that their arguments are appropriate at
run time as the function is called.

#### When are declared variable constraints checked? {-}

For data variables, constraints are checked after the variable is read
from a data file or other source.  For transformed data variables, the
check is done after the statements in the transformed data block have
executed.  Thus it is legal for intermediate values of variables to
not satisfy declared constraints.

For parameters, constraints are enforced by the transform applied and
do not need to be checked.  For transformed parameters, the check is
done after the statements in the transformed parameter block have
executed.

For all blocks defining variables (transformed data, transformed
parameters, generated quantities), real values are initialized to
`NaN` and integer values are initialized to the smallest legal
integer (i.e., a large absolute value negative number).

For generated quantities, constraints are enforced after the
statements in the generated quantities block have executed.


### Type naming notation {-}

In order to refer to data types, it is convenient to have a way to
refer to them.  The type naming notation outlined in this section is
not part of the Stan programming language, but rather a convention
adopted in this document to enable a concise description of a type.

Because size information is not part of a data type, data types will
be written without size information.  For instance, `array[] real` is the
type of one-dimensional array of reals and `matrix` is the type of
matrices.  The three-dimensional integer array type is written as
`array[,,] int`, indicating the number slots available for indexing.
Similarly, `array[,] vector` is the type of a two-dimensional array of
vectors.



## Variable declaration {#variable-declaration.section}

Variables in Stan are declared by giving a type and a name. For example

```stan
int N;
vector[N] y;
array[5] matrix[3, 4] A;
```

declares a variable `N` that is an integer, a variable `y` that is
a vector of length `N` (the previously declared variable), and a
variable `A`, which is a length-5 array where each element is a 3 by 4
matrix.

The size of top-level variables in the `parameters`, `transformed parameters`, and `generated quantities`
must remain constant across all iterations, therefore only data variables can be used in top-level size declarations.

```stan
// illegal and will be flagged by the compiler:
generated quantities {
  int N = 10;
  array[N] int foo;
```

Depending on where the variable is declared in the Stan program,
it either must or cannot have size information, and constraints
are either optional or not allowed.

```stan
// valid block variables, but not locals or function parameters
vector<lower=0>[N] u;

// valid as a block or local variable, but not a function parameter
array[3] int is;

// function parameters exclude sizes and cannot be constrained
void pretty_print_tri_lower(matrix x) { ... }
```

Top-level variables can have [constraints](#constrained-data-types) and
must include sizes for their types, as in the above examples.
Local variables, like those defined inside loops or local blocks cannot be constrained, but still include sizes.
Finally, variables declared as [function parameters](user-functions.qmd#argument-types-and-qualifiers)
are not constrained types and _exclude_ sizes.

In the following table, the leftmost column is a list of the
unconstrained and undimensioned basic types; these are used as
function return types and argument types.  The middle column is of
unconstrained types with dimensions; these are used as local variable
types. The variables `M` and `N` indicate number of columns and rows,
respectively.  The variable `K` is used for square matrices, i.e., `K`
denotes both the number of rows and columns.
The rightmost column lists the corresponding constrained types.
An expression of any right-hand
column type may be assigned to its corresponding left-hand column basic
type.  At runtime, dimensions are checked for consistency for all
variables; containers of any sizes may be assigned to function
arguments.  The constrained matrix types `cov_matrix[K]`,
`corr_matrix[K]`, `cholesky_factor_cov[K]`, and
`cholesky_factor_corr[K]` are only assignable to matrices of
dimensions `matrix[K, K]` types.

+---------------------+-------------------------+----------------------------------------------+
| Function Argument   |        Local            |                   Block                      |
|     (unsized)       |    (unconstrained)      |               (constrained)                  |
+:====================+:========================+:=============================================+
| `int`               | `int`                   | `int`                                        |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `int<lower=L>`                               |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `int<upper=U>`                               |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `int<lower=L, upper=U>`                      |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `int<offset=O>`                              |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `int<multiplier=M>`                          |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `int<offset=O, multiplier=M>`                |
+---------------------+-------------------------+----------------------------------------------+
| `real`              | `real`                  | `real`                                       |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `real<lower=L>`                              |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `real<upper=U>`                              |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `real<lower=L, upper=U>`                     |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `real<offset=O>`                             |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `real<multiplier=M>`                         |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `real<offset=O, multiplier=M>`               |
+---------------------+-------------------------+----------------------------------------------+
| `complex`           | `complex`               | `complex`                                    |
+---------------------+-------------------------+----------------------------------------------+
| `vector`            | `vector[N]`             | `vector[N]`                                  |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `vector[N]<lower=L>`                         |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `vector[N]<upper=U>`                         |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `vector[N]<lower=L, upper=U>`                |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `vector[N]<offset=O>`                        |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `vector[N]<multiplier=M>`                    |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `vector[N]<offset=O, multiplier=M>`          |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `ordered[N]`                                 |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `positive_ordered[N]`                        |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `simplex[N]`                                 |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `unit_vector[N]`                             |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `sum_to_zero_vector[N]`                      |
+---------------------+-------------------------+----------------------------------------------+
| `row_vector`        | `row_vector[N]`         | `row_vector[N]`                              |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `row_vector[N]<lower=L>`                     |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `row_vector[N]<upper=U>`                     |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `row_vector[N]<lower=L, upper=U>`            |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `row_vector[N]<offset=O>`                    |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `row_vector[N]<multiplier=M>`                |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `row_vector[N]<offset=O, multiplier=M>`      |
+---------------------+-------------------------+----------------------------------------------+
| `matrix`            | `matrix[M, N]`          | `matrix[M, N]`                               |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `matrix[M, N]<lower=L>`                      |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `matrix[M, N]<upper=U>`                      |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `matrix[M, N]<lower=L, upper=U>`            |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `matrix[M, N]<offset=O>`                     |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `matrix[M, N]<multiplier=M>`                 |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `matrix[M, N]<offset=O, multiplier=M>`       |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `column_stochastic_matrix[M, N]`             |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `row_stochastic_matrix[M, N]`                |
+---------------------+-------------------------+----------------------------------------------+
|                     | `matrix[K, K]`          | `corr_matrix[K]`                             |
+---------------------+-------------------------+----------------------------------------------+
|                     | `matrix[K, K]`          | `cov_matrix[K]`                              |
+---------------------+-------------------------+----------------------------------------------+
|                     | `matrix[K, K]`          | `cholesky_factor_corr[K]`                    |
+---------------------+-------------------------+----------------------------------------------+
|                     | `matrix[K, K]`          | `cholesky_factor_cov[K]`                     |
+---------------------+-------------------------+----------------------------------------------+
| `complex_vector`    | `complex_vector[M]`     | `complex_vector[M]`                          |
+---------------------+-------------------------+----------------------------------------------+
| `complex_row_vector`| `complex_row_vector[N]` | `complex_row_vector[N]`                      |
+---------------------+-------------------------+----------------------------------------------+
| `complex_matrix`    | `complex_matrix[M, N]`  | `complex_matrix[M,N]`                        |
+---------------------+-------------------------+----------------------------------------------+
| `array[] vector`    | `array[M] vector[N]`    | `array[M] vector[N]`                         |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] vector[N]<lower=L>`                |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] vector[N]<upper=U>`                |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] vector[N]<lower=L, upper=U>`       |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] vector[N]<offset=O>`               |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] vector[N]<multiplier=M>`           |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] vector[N]<offset=O, multiplier=M>` |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] ordered[N]`                        |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] positive_ordered[N]`               |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] simplex[N]`                        |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] unit_vector[N]`                    |
+---------------------+-------------------------+----------------------------------------------+
|                     |                         | `array[M] sum_to_zero_vector[N]`             |
+---------------------+-------------------------+----------------------------------------------+

<a name="id:constrained-types.figure"></a>

Additional array types follow the same basic template as the final
example in the table and can contain any of the previous types.
The unsized version of arrays with more than one dimension is
specified by using commas, e.g. `array[ , ]` is a 2-D array.

For more on how function arguments and return types are declared,
consult the [User's Guide chapter on
functions](https://mc-stan.org/docs/stan-users-guide/user-functions.html#basic-functions.section#type-declarations-for-functions).

## Compound variable declaration and definition

Stan allows assignable variables to be declared and defined in a
single statement.  Assignable variables are


* local variables, and
* variables declared in the transformed data,
transformed parameters, or generated quantities blocks.


For example, the statement

```stan
int N = 5;
```

declares the variable `N` to be an integer scalar type and at the
same time defines it to be the value of the expression `5`.

### Assignment typing {-}

The type of the expression on the right-hand side of the assignment
must be assignable to the type of the variable being declared.  For
example, it is legal to have

```stan
real sum = 0;
```

even though `0` is of type `int` and `sum` is of type `real`, because
integer-typed scalar expressions can be assigned to real-valued scalar
variables.  In all other cases, the type of the expression on the
right-hand side of the assignment must be identical to the type of the
variable being declared.

Variables of any type may have values assigned to them.  For example,

```stan
matrix[3, 2] a = b;
```

declares a $3 \times 2$ matrix variable `a` and assigns a copy
of the value of `b` to the variable `a`.  The variable `b` must
be of type `matrix` for the statement to be well formed.  For
the code to execute successfully, `b` must be the same shape as `a`,
but this cannot be validated until run time.  Because a copy is
assigned, subsequent changes to `a` do not affect `b` and subsequent
changes to `b` do not affect `a`.


### Right-hand side expressions {#rhs-expressions}

The right-hand side may be any expression which has a type which is
assignable to the variable being declared.  For example,

```stan
matrix[3, 2] a = 0.5 * (b + c);
```

assigns the matrix variable `a` to half of the sum of `b` and `c`.
The only requirement on `b` and `c` is that the expression `b + c` be
of type `matrix`.  For example, `b` could be of type `matrix` and `c`
of type `real`, because adding a matrix to a scalar produces a matrix,
and the multiplying by a scalar produces another matrix.

Similarly,

```stan
complex z = 2 + 3i;
```

assigns the  the complex number $2 + 3i$ to the complex scalar `z`.
The right-hand side expression can be a call to a user defined
function, allowing general algorithms to be applied that might not be
otherwise expressible as simple expressions (e.g., iterative or
recursive algorithms).


### Scope within expressions {-}

Any variable that is in scope and any function that is available in
the block in which the compound declaration and definition appears may
be used in the expression on the right-hand side of the compound
declaration and definition statement.


## Declaring multiple variables at once

Stan will interpret multiple comma-separated variable names following a single
type as declaring multiple new variables.
This is available for all variable declarations in all blocks.

### Types for multiple declarations {-}

The code:

```stan
real x, y;
```
is equivalent to

```stan
real x;
real y;
```

As a result, all declarations on the same line must be of the same type.

### Combining with other features {-}

The ability to declare multiple variables can be combined with assignments
whenever a declare-define is valid, as documented in
[the section introducing compound declarations and definitions](#compound-variable-declaration-and-definition)
:

```stan
real x = 3, y = 5.6;
```

[Constrained data types](#constrained-data-types) can also be declared
together, so long as the constraint for each variable is the same:

```stan
real<lower=0> x, y;
```