\part{Commands and Data Formats}


\chapter{Compiling \Stan Programs}

\noindent
Preparing a \Stan program to be run involves two steps,
%
\begin{enumerate}
\item translating the \Stan program to \Cpp, and
\item compiling the resulting \Cpp to an executable.
\end{enumerate}
%
This chapter discusses both steps, as well as their encapsulation into
a single make target.  

\section{Installing Stan}

Before Stan can be run, it must be installed; see
\refappendix{install} for complete platform-specific installation
details.

\section{Translating and Compiling through {\tt\bfseries make}}\label{make-models.section}

The simplest way to compile a Stan program is through the \code{make}
build tool, which encapsulates the translation and compilation step
into a single command.  The commands making up the \code{make} target
for compiling a model are described in the following sections, and the
following chapter describes how to run a compiled model.

\subsection{Translating and Compiling Test Models}

There are a number of test models distributed with Stan which unpack
into the path \code{src/models}.  To build the simple example
\nolinkurl{src/models/basic\_estimators/bernoulli.stan}, the following call
to \code{make} suffices.  First the directory is changed to Stan's home
directory by replacing \code{<stan-home>} with the appropriate path.
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> cd <stan-home>
\end{Verbatim}
\end{quote}
%
The current directory should now contain the file named
\code{makefile}, which is the default instructions used by
\code{make}.  From within the top-level Stan directory, the following call
will build an executable form of the Bernoulli estimator.
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> make src/models/basic_estimators/bernoulli
\end{Verbatim}
\end{quote}
%
This will translate the model \code{bernoulli.stan} to a \Cpp file and
compile that \Cpp file, putting the executable in
\nolinkurl{src/models/basic_distributions/bernoulli(.exe)}.  Although
the make command including arguments is itself portable, the target it
creates is different under Windows than in Unix-like platforms.  Under
Linux and the Mac, the executable will be called \code{bernoulli},
whereas under Windows it will be called \code{bernoulli.exe}.

\subsection{Dependencies in {\tt\bfseries make}}

A \code{make} target can depend on other \code{make} targets.  When
executing a \code{make} target, first all of the targets on which it
depends are checked to see if they are up to date, and if they are
not, they are rebuilt.  This includes the top-level target itself.  If
the \code{make} target to build the Bernoulli estimator is invoked a
second time, it will see that it is up to date, and not compile
anything.  But if one of the underlying files has changes since the
last invocation \code{make}, such as the model specification file, it
will be retranslated to \Cpp and recompiled to an executable.

There is a dependency included in the make target that will
automatically build the \code{bin/stanc} compiler and the
\code{bin/libstan.a} library whenever building a model.


%\subsection{Making Other Models}
%
%A \code{make} target can be invoked from a directory other than the
%one that contains the \code{makefile} with the \code{-f} option.  Thus
%an alternative way to compile this model from its own source directory
%would be as follows (again replacing \code{<stan-home>} with the
%appropriate path to the top-level directory in which Stan was
%unpacked).
%\begin{quote}
%\begin{Verbatim}[fontshape=sl]
%> cd <stan-home>src/models/basic_estimators
%> make -f ../../../makefile bernoulli
%\end{Verbatim}
%\end{quote}
%%
%The expression \code{../../../makefile} is a relative path to the
%file named \code{makefile}; this says to go up three directories
%(i.e., back to \code{<stan-home>}) and then look for a file named
%\code{makefile}.  This can be an absolute path, too.  The Unix-like
%forward slashes can be used under Windows as well as under Linux and
%Mac.  


\subsection{Getting Help from the {\tt makefile}}

Stan's \code{makefile}, which contains the top-level instructions to
\code{make}, provides extensive help in terms of targets and options.
It is located at the top-level of the distribution, so first change
directories to that location.
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> cd <stan-home>
\end{Verbatim}
\end{quote} 
and then invoke make with the target \code{help},

\begin{quote}
\begin{Verbatim}[fontshape=sl]
> make help
\end{Verbatim}
\end{quote}


\subsection{Options to \code{make}}

Stan's \code{make} targets allow the user to change compilers,
library versions for Eigen and Boost, as well as compilation options
such as optimization.

These options should be placed right after the call to \code{make}
itself.  For instance, to specify the \code{clang++} compiler at
optimization level 0, use
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> make CC=clang++ O=0 ...
\end{Verbatim}
\end{quote}


\subsubsection{Compiler Option}

The option \code{CC=g++} specifies the \code{g++} compiler and
\code{CC=clang++} specifies the \code{clang++} compiler.  Other
compilers with other names may be specified the same way.  A full path
may be used, or just the name of the program if it can be found on the
system execution path.  

\subsubsection{Optimization Option}

The option \code{O=0} (that's letter `O', equal sign, digit `0'),
specifies optimization level 0 (no optimization), whereas \code{O=3}
specifies optimization level 3 (effectively full optimization), with
levels 1 and 2 in between.

With higher optimization levels, generated executable tends to be bigger
(in terms of bytes in memory) and faster.  For best results on
computationally-intensive models, use optimization level 3 for the
Stan library and for compiling models.

\subsubsection{Library Options}

Alternative versions of Eigen, Boost, and Google Test may be specified
using the properties \code{EIGEN}, \code{BOOST}, and \code{GTEST}.
Just set them equal to a path that resolves to an appropriate library.
See the libraries distributed under \code{lib} to see which
subdirectory of the library distribution should be specified in order
for the include paths in the \Cpp code to resolve properly.


\subsection{Additional  \code{make} Targets}

All of these targets are intended to be invoked from the top-level
directory in which Stan was unpacked (i.e., the directory that
contains the file named \code{makefile}).

\subsubsection{Clean Targets}

A very useful target is \code{clean-all}, invoked as
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> make clean-all
\end{Verbatim}
\end{quote}
%
This removes everything that's created automatically by \code{make},
including the \code{stanc} translator, the Stan libraries, and all the
automatically generated documentation.  

\subsubsection{Make Target for \code{stanc}}

To make the \code{stanc} compiler, use
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> make bin/stanc
\end{Verbatim}
\end{quote}
%
As with other executables, the executable \code{bin/stanc} will be
created under Linux and Mac, whereas \code{bin/stanc.exe} will be
created under Windows.

\subsubsection{Make Target for Stan Library}

To build the Stan library, use the following target,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> make bin/libstan.a
\end{Verbatim}
\end{quote}



\section{Translating \Stan to C++ with {\tt\bfseries stanc}}\label{stanc.section}


\subsection{Building the \stanc Compiler and the Stan Library}

Before the \stanc compiler can be used, it must be built.  Use the
following command from the top-level distribution directory containing
the file named \code{makefile}.
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> make bin/stanc
\end{Verbatim}
\end{quote}
%
This invocation produces the executable \code{bin/stanc} under Linux
and Mac, and \code{bin/stanc.exe} under Windows.  The invocation of
\code{make}, including the forward slash, is the same on both platforms.

The default compiler option is \code{CC=g++} and the default
optimization level is \code{O=3} (the letter `O');  to see how to
change these, see the previous section in this chapter on \code{make}.


\subsection{The \stanc Compiler}

The \stanc compiler converts \Stan programs to \Cpp programs.  The
first stage of compilation involves parsing the text of the \Stan
program.  If the parser is successful, the second stage of compilation
generates \Cpp code.  If the parser fails, it will provide a
diagnostic error message indicating the location in the input where
the failure occurred and reason for the failure.

The following example illustrates a fully qualified call to \stanc
to build the simple Bernoulli model; just replace \code{<stan-home>}
with the top-level directory containing Stan (i.e., the directory
containing the file named \code{makefile}). 

For Linux and Mac:
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> cd <stan-home>
> bin/stanc --name=bernoulli --o=bernoulli.cpp \
  src/models/basic_estimators/bernoulli.stan 
\end{Verbatim}
\end{quote}
%
The backslash (\Verb|\|) indicates a continuation of the same line.

For Windows:
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> cd <stan-home>
> bin\stanc --name=bernoulli --o=bernoulli.cpp ^
    src/models/basic_estimators/bernoulli.stan 
\end{Verbatim}
\end{quote}
%
The caret (\Verb|^|) indicates continuation on Windows.

This call specifies the name of the model, here {\tt bernoulli}.
This will determine the name of the class implementing the model in
the \Cpp code.  Because this name is the name of a \Cpp class, it must
start with an alphabetic character (\code{a--z} or \code{A--Z}) and
contain only alphanumeric characters (\code{a--z}, \code{A--Z}, and
\code{0--9}) and underscores (\code{\_}) and should not conflict with
any \Cpp reserved keyword.  

The \Cpp code implementing the class is written to the file
\code{bernoulli.cpp} in the current directory.  The final argument,
\code{bernoulli.stan}, is the file from which to read the \Stan
program.

\subsection{Command-Line Options for {\tt\bfseries stanc}}

The model translation program \code{stanc} is called as follows.
%
\begin{quote}
\code{> stanc [options] {\slshape model\_file}}
\end{quote}
%
The argument \code{\slshape model\_file} is a path to a Stan model file ending
in suffix \code{.stan}.  The options are as follows.
%
\begin{description}
%
\item[\tt {-}-help] 
\mbox{ } \\ 
Displays the manual page for \stanc.  If this option is selected,
nothing else is done.
%
\item[\tt {-}-version]
\mbox{ } \\ 
Prints the version of \stanc.  This is useful for bug reporting
and asking for help on the mailing lists.
%
\item[\tt {-}-name={\slshape class\_name}]
\mbox{ } \\ 
Specify the name of the class used for the implementation of the
\Stan model in the generated \Cpp code.  
\\[2pt]
Default: {\tt {\slshape class\_name = model\_file}\_model}
%
\item[\tt {-}-o={\slshape cpp\_file\_name}]
\mbox{ } \\ 
Specify the name of the file into which the generated \Cpp is written.
\\[2pt]
Default: {\tt {\slshape cpp\_file\_name} = {\slshape class\_name}.cpp}
%
\item[\tt {-}-no\_main]
\mbox{ } \\
Include this flag to prevent the generation of a main function in the
output.
\\[2pt]
Default: generate a main function
\end{description}



\section{Compiling C++ Programs}\label{compiling-cpp.section}

\noindent
As shown in the previous section (\refsection{stanc}), \Stan converts
a program in the \Stan modeling language to a \Cpp program.  This \Cpp
program must then be compiled using a \Cpp compiler.  

The \Cpp compilation step described in this chapter, the model
translation step described in the last chapter, and the compilation of
the dependent binaries \code{bin/stanc} and \code{bin/libstan.a} may
be automated through make; see \refsection{make-models} for details.

\subsection{Which Compiler?}

\Stan has been developed using two portable, open-source \Cpp
compilers, \gpp and \clang, both of which run under and generate code
for Windows, Macintosh, and Unix/Linux.%
%
\footnote{As of the current version, \Stan cannot be compiled using
  \MSVC, the Windows-specific compiler from Microsoft.  \MSVC is able
  to compile the \code{stanc} compiler, but not the templates required
  for algorithmic differentiation and the Eigen matrix library.}

The \clang compiler is almost twice as fast at low levels of
optimization, but the machine code generated by \gpp at high
optimization levels is faster.


\subsection{What the Compiler Does}

A \Cpp compiler like \gpp or \clang performs several lower-level
operations in sequence,
% 
\begin{enumerate}
\item
parsing the input \Cpp source file(s), 
\item 
generating (static or dynamically) relocatable object code, and
\item 
linking the relocatable object code into executable code.
\end{enumerate}
%
These stages may be called separately, though the examples in this
manual perform them in a single call.  The compiler invokes the
assembler to convert assembly language code to machine code, and the
linker to resolve the location of references in the relocatable object
files.

\subsection{Compiler Optimization}

\Stan was written with an optimizing compiler in mind, which allows
the code to be kept relatively clean and modular.  As a result, \Stan
code runs as much as an order of magnitude or more faster with
optimization turned on.

For development of \Cpp code for \Stan, use optimization level 0; for
sampling, use optimization level 3.  These are controlled through
\Stan's makefile using \code{O=0} and directly through \clang or \gpp
with \code{-O0}; in both cases, the first character is the letter `O'
and the second the digit `0'.


\subsection{Building the \Stan Library}

Before compiling a \Stan-generated \Cpp program, the \Stan object
library archive must be built using the makefile.  This only needs to
be done once and then the archive may be reused.  The recommended
build command for the \Stan archive is as follows (replacing
\code{<stan-home>} with the directory into which Stan was unpacked and
which contains the file named \code{makefile}).
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> cd <stan-home>
> make CC=g++ O=3 bin/libstan.a 
\end{Verbatim}
\end{quote}
%
Please be patient and ignore the (unused function) warning messages.
Compilation with high optimization on \code{g++} takes time (as much
as 10 minutes or more) and memory (as much as 3GB). 

This example uses the \code{g++} compiler for \Cpp (makefile option
\code{CC=g++}).  The \clang compiler may be used by specifying
\code{CC=clang++}.

This example uses compiler optimization level 3 (makefile option
\code{O=3}).  Turning the optimization level down to 0 allows the code
to built in under a minute in less than 1GB of memory.  This will slow
down sampling as much as an order of magnitude or more, so it is not
recommended for running models.  It can be useful for working on
\Stan's \Cpp code.


\subsection{Compiling a \Stan Model}

Suppose following the instructions in the last chapter
(\refsection{stanc}) that a \Stan program has been converted to a \Cpp
program that resides in the source file \code{<stan-home>/my\_model.cpp}.

The following commands will produce an executable in the file
\code{my\_model} in the current working directory (\code{<stan-home>}).
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> cd <stan-home>
> g++ -O3 -Lbin -Isrc -isystem lib/boost_1.54.0              \
    -isystem lib/eigen_3.2.0 my_model.cpp -o my_model -lstan
\end{Verbatim}
\end{quote} %
The backslash (\Verb|\|) is used to indicate that the command is
continued; it should be entered all one one line.
%
The options used here are as follows.
\begin{quote}
\begin{description}
\item[\code{-O3}] sets optimization level 3,
\item[\code{-Lbin}] specifies that the archive is in the \code{bin}
  directory,
\item[\code{-Isrc}] specifies that the directory \code{src} should be
  searched for code (it contains the top-level \Stan headers),
\item[\code{-isystem lib/boost\_1.54.0}] specifies the include directory for the 
  Boost library,
\item[\code{-isystem lib/eigen\_3.2.0}] specifies the include directory for
  the Eigen library,
\item[\code{my\_model.cpp}] specifies the name of the source file to
  compile, and 
\item[\code{-o my\_model}] is the name of the resulting executable
  produced by the command (suffixed by \code{.exe} in Windows).
\item[\code{-lstan}] specifies the name of the archived library (not
  the name of the file in which it resides),
\end{description}
\end{quote}
%
The library binary and source specifications are required, as is the
name of the \Cpp file to compile.  User-supplied directories may be
included in header or archive form by specifying additional \code{-L},
\code{-l}, and \code{-I} options.
 
A lower optimization level may be specified.  If there is no
executable name specified using the \code{-o} option, then the model
is written into a file named \code{a.out}.
 

\subsection{Library Dependencies}

\Stan depends on two open-source libraries,
%
\begin{enumerate}
\item the Boost general purpose \Cpp libraries, and 
\item the Eigen matrix and linear algebra \Cpp libraries.
\end{enumerate}
%
These are both distributed along with \Stan in the directory
\code{<stan-home>/lib}.  

The code for \Stan itself is located in the directory
\code{<stan-home>/src}.  Because not all of \Stan is included in the
archive \code{bin/libstan.a}, the \code{src} directory must also be
included for compilation.





\chapter{Running a \Stan Program}\label{stan-cmd.chapter}

\noindent 
Once a \Stan program is compiled, it can be run in many different
ways.  It can be used to sample or optimize parameters, or to diagnose
a model.  Before diving into the detailed configurations, the first
section provides some simple examples.


\section{Getting Started by Example}\label{command-getting-started.section}

Once a \Stan program defining a model has been converted to a \Cpp
program for that model (see \refsection{stanc}) and the resulting \Cpp
program compiled to a platform-specific executable (see
\refsection{compiling-cpp}), the model is ready to be run.

All of the Stan functionality is highly configurable from the command
line; the options are defined later in this chapter.  Each command
option also has defaults, which are used in this section.

\subsection{Sampling}

Suppose the executable is in file \code{my\_model} and the data is in
file \code{my\_data}, both in the current working directory.  To
generate samples from a data set using the default settings, use one
of the following, depending on platform.
%
\subsubsection{Windows}
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> my_model sample data file=my_data
\end{Verbatim}
\end{quote}
%

\subsubsection{Mac OS and Linux}
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./my_model sample data file=my_data
\end{Verbatim}
\end{quote}
%
On both platforms, this command reads the data from file
\code{my\_data}, runs warmup tuning for 1000 iterations (the values
of which are discarded), and then runs the fully-adaptive \NUTS
sampler for 1000 iterations, writing the parameter (and other) values
to the file \code{samples.csv} in the current working directory.  When
no random number seed is specified, a seed is generated from the
system time.

\subsection{Sampling in Parallel}

The previous example executes one chain, which can be repeated to 
generate multiple chains. However, users may want to execute chains
in parallel on a multicore machine. 

\subsubsection{Mac OS and Linux}

To sample four chains using a Bash shell on Mac OS or Linux, execute
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> for i in {1..4}                            \
  do                                         \
    ./my_model sample random seed=12345      \ 
       id=$i data file=my_data               \
       output file=samples$i.csv refresh=0 & \
 done
\end{Verbatim}
\end{quote}
%
The backslash (\code{\textbackslash}) indicates that the big command
continues on the next display line; the blank line at the end that
returns control to the prompt. The ampersand (\code{\&}) at the end of
the nested command pushes each process into the background, so that
the loop can continue without waiting for the current chain to
finish. This example requires several command-line options that are
explained in further detail in the next subsection.

\subsubsection{Windows}

On Windows, the following is functionally equivalent to the Bash
snippet above
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> for /l %x in (1, 1, 4) do start /b model  sample  ^
   random seed=12345 id=%x data file=my_data        ^
   output file=samples%x.csv refresh=0
\end{Verbatim}
\end{quote}
%
The caret (\code{\textasciicircum}) indicates a line continuation in
DOS.

\subsubsection{Combining Parallel Chains}

Stan has commands to analyze the output of multiple chains, each
stored in their own file;  see \refchapter{print-command}.  RStan also
has commands to read in multiple CSV files produced by Stan's
command-line sampler.  

To compute posterior quantities, it is sometimes easier to have the
chains merged into a single CSV file.  If the grep and sed programs
are installed, then the following will combine the four
comma-separated values files into a single comma-separated values
file.  The command is the same on Windows, Mac OS and Linux.
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> grep lp__ samples1.csv > combined.csv
> sed '/^[#l]/d' samples*.csv >> combined.csv 
\end{Verbatim}
\end{quote}

\subsubsection{Scripting and Batching}

The previous examples show how to sample in parallel from the command
line.  Operations like these can also be scripted, using shell scripts
(\code{.sh}) on Mac OS and Linux and DOS batch (\code{.bat}) files on
Windows.  A sequence of several such commands can be executed from a
single script file.  Such scripts might contain \code{stanc} commands
(see \refsection{stanc}) and \code{bin/print} commands (see
\refchapter{print-command}) can be executed from a single script
file.  At some point, it is worthwhile to move to something with
stronger dependency control such as makefiles.


\subsection{Optimization}

Stan can find the posterior mode (assuming there is one).  If the
posterior is not convex, there is no guarantee Stan will be able to
find the global mode as opposed to a local optimum of log probability.

For optimization, the mode is calculated without the Jacobian
adjustment for constrained variables, which shifts the mode due to the
change of variables.  Thus modes correspond to modes of the model as
written.  

\subsubsection{Windows}
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> my_model optimize data file=my_data
\end{Verbatim}
\end{quote}

\subsubsection{Mac OS and Linux}
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./my_model optimize data file=my_data
\end{Verbatim}
\end{quote}



\section{Diagnostics}\label{diagnostics.section}

Stan has a basic diagnostic feature that will calculate gradients of
the initial state and compare them with those calculated with finite
differences.  If there are discrepancies, there is a problem with the
model or initial states (or a bug in Stan).  To run on the different
platforms, use one of the following.

\subsubsection{Windows}
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> my_model diagnose data file=my_data
\end{Verbatim}
\end{quote}

\subsubsection{Mac OS and Linux}
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./my_model diagnose data file=my_data
\end{Verbatim}
\end{quote}




\section{Command-Line Options}\label{stan-command-line-options.section}

\Stan executables are highly configurable, allowing the user to specify
and customize not only the calculation method but also the data, output,
initialization, and random number generation.  The arguments are defined
hierarchically so that, for example, optimization settings are not necessary
when sampling.  

The atomic elements of the hierarchy (i.e., those without
corresponding values) are \textit{categorical arguments} (sometimes
called ``flags'') which define self-contained categories of arguments.

Arguments grouped within a category are not ordered with respect
to each other.  For example, the following four commands all define
the same configuration:%
%
\footnote{
  Stan's commands have more hierarchical structure than is typical of
  command line executables, which usually have at most two subgroups
  of commands.  For instance, the Git version control system has
  global control arguments (e.g., username and password), then a
  ``method'' specification (e.g., pull or commit), and then arguments
  specific to the method.  The only ordering is that the global
  options come before the method argument and subcommand-specific
  options after the method argument.}
\footnote{
The backslash (\code{\textbackslash}) is used at the end of a line in
a command to indicate that it continues on the next line.  The
indentation to indicate the structure of the command is for
pedagogical purposes only; the same result would be obtained writing
each command on one line with single spaces separating the elements.
}
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model sample output file=samples.csv                \
                        diagnostic_file=diagnostics.csv \
                 random seed=1

> ./model sample output diagnostic_file=diagnostics.csv \
                        file=samples.csv                \
                 random seed=1

> ./model sample random seed=1                          \
                 output file=samples.csv                \
                        diagnostic_file=diagnostics.csv 

> ./model sample random seed=1                          \
                 output diagnostic_file=diagnostics.csv \
                        file=samples.csv 
\end{Verbatim}
\end{quote}
%
The categorical arguments \code{output} and \code{random} can be
in any order provided that the subarguments follow their respective
parent, here \code{diagnostic\_file} and \code{file} following \code{output}
and \code{seed} coming after \code{random}.  These four configurations
exhaust all valid combinations.

Categorical arguments may appear is isolation, for example when
introducing \code{sample} or \code{random}, or they may appear as
the values for other arguments, such as \code{hmc} which not only 
introduces a category of HMC related arguments but also defines the
value of the argument \code{algorithm}.  A visual diagram of the available 
categorical arguments is shown in \reffigure{hierarchy}, with the mutual 
exclusivity of these arguments as values shown in \reffigure{configuration}.  
Specifying conflicting arguments
causes the execution to immediately terminate.

\begin{figure}
\setlength{\unitlength}{0.01in} 
\centering
\begin{picture}(480, 480)
\small\tt
%
\put(10, 460) { \makebox(50, 10)[l]{id, data, init} }
%
\put(0, 410) { \framebox(470, 45) }
\put(10, 440) { \makebox(50, 10)[l]{random} }
\put(50, 420) { \makebox(50, 10)[l]{seed} }
%
\put(0, 360) { \framebox(470, 45) }
\put(10, 390) { \makebox(65, 10)[l]{output} }
\put(50, 370) { \makebox(500, 10)[l]{file, append\_sample,
    diagnostic\_file, append\_diagnostic, ... } } % refresh, save\_warmup} }
%
\put(10, 340) { \makebox(50, 10)[l]{method} }
\put(20, 117.5) { \line(0, 1){212.5} }
\put(20, 117.5) { \vector(1, 0){15} }
\put(20, 257.5) { \vector(1, 0){15} }
\put(20, 307.5) { \vector(1, 0){15} }
%
\put(40, 285) { \framebox(430, 45) }
\put(50, 315) { \makebox(65, 10)[l]{ diagnose } }
\put(90, 295) { \makebox(50, 10)[l]{ $\ldots$ } }
%
\put(40, 235) { \framebox(430, 45) }
\put(50, 265) { \makebox(63, 10)[l]{ optimize } }
\put(90, 245) { \makebox(50, 10)[l]{ $\ldots$ } }
%
\put(40, 5) { \framebox(430, 225) }
\put(50, 215) { \makebox(55, 10)[l]{sample} }
\put(90, 195) { \makebox(350, 10)[l]{num\_samples, num\_warmup, save\_warmup, thin} }
%
\put(80, 140) { \framebox(380, 45) }
\put(90, 170) { \makebox(55, 10)[l]{adapt} }
\put(130, 150) { \makebox(50, 10)[l]{$\ldots$} }
%
\put(90, 120) { \makebox(55, 10)[l]{algorithm} }
\put(100, 37.5) { \line(0, 1){70} }
\put(100, 87.5) { \vector(1, 0){15} }
\put(100, 37.5) { \vector(1, 0){15} }
%
\put(120, 65) { \framebox(340, 45) }
\put(130, 95) { \makebox(55, 10)[l]{hmc} }
\put(170, 75) { \makebox(50, 10)[l]{$\ldots$} }
%
\put(120, 15) { \framebox(340, 45) }
\put(130, 45) { \makebox(115, 10)[l]{ rw\_metropolis } }
\put(170, 25) { \makebox(50, 10)[l]{ $\ldots$ } }
\end{picture}
\caption{\small\it In the hierarchical argument structure, certain
  arguments, such as \code{random} and \code{output}, introduce new
  categories of arguments.  Categorical arguments may also
  appear as values of other arguments, such as \code{diagnose},
  \code{optimize}, and \code{sample}, which define the mutually
  exclusive values for the argument \code{method}. }%
\label{hierarchy.figure}
\end{figure}

\begin{figure}
\setlength{\unitlength}{0.01in} 
\centering
\begin{picture}(480, 480)
%
\small\tt
\put(10, 460) { \makebox(50, 10)[l]{id, data, init} }
%
\put(0, 410) { \framebox(470, 45) }
\put(10, 440) { \makebox(50, 10)[l]{random} }
\put(50, 420) { \makebox(50, 10)[l]{seed} }
%
\put(0, 360) { \framebox(470, 45) }
\put(10, 390) { \makebox(65, 10)[l]{output} }
\put(50, 370) { \makebox(450, 10)[l]{file, append\_sample,
    diagnostic\_file, append\_diagnostic, ...} }  % refresh, ...
%
\put(10, 340) { \makebox(50, 10)[l]{method} }
\put(20, 117.5) { \line(0, 1){212.5} }
\put(20, 117.5) { \vector(1, 0){15} }
\put(20, 257.5) { \color{gray!30}\vector(1, 0){15} }
\put(20, 307.5) { \color{gray!30}\vector(1, 0){15} }
%
\put(40, 285) { \color{gray!30}\framebox(430, 45) }
\put(50, 315) { \makebox(65, 10)[l]{ \textcolor{gray!30}{diagnose} } }
\put(90, 295) { \makebox(50, 10)[l]{ \textcolor{gray!30}{$\ldots$} } }
%
\put(40, 235) { \color{gray!30}\framebox(430, 45) }
\put(50, 265) { \makebox(63, 10)[l]{ \textcolor{gray!30}{optimize} } }
\put(90, 245) { \makebox(50, 10)[l]{ \textcolor{gray!30}{$\ldots$} } }
%
\put(40, 5) { \framebox(430, 225) }
\put(50, 215) { \makebox(55, 10)[l]{sample} }
\put(90, 195) { \makebox(350, 10)[l]{num\_samples, num\_warmup, save\_warmup, thin} }
%
\put(80, 140) { \framebox(370, 45) }
\put(90, 170) { \makebox(55, 10)[l]{adapt} }
\put(130, 150) { \makebox(50, 10)[l]{$\ldots$} }
%
\put(90, 120) { \makebox(55, 10)[l]{algorithm} }
\put(100, 37.5) { \color{gray!30}\line(0, 1){70} }
\put(100, 87.5) { \line(0, 1){20} }
\put(100, 87.5) { \vector(1, 0){15} }
\put(100, 37.5) { \color{gray!30}\vector(1, 0){15} }
%
\put(120, 65) { \framebox(330, 45) }
\put(130, 95) { \makebox(55, 10)[l]{hmc} }
\put(170, 75) { \makebox(50, 10)[l]{$\ldots$} }
%
\put(120, 15) { \color{gray!30}\framebox(330, 45) }
\put(130, 45) { \makebox(95, 10)[l]{ \textcolor{gray!30}{rw\_metropolis} } }
\put(170, 25) { \makebox(50, 10)[l]{ \textcolor{gray!30}{$\ldots$} } }
\end{picture}
\caption{\small\it A valid argument configuration defines only one
    mutually exclusive argument.  If conflicting arguments are
    specified, for example \code{method=optimize method=sample}, then
    execution immediately terminates with a warning
    message.}\label{configuration.figure}
\end{figure}

Note that any valid argument configuration must either specify a method
or a help request.

\subsection{Method}

All commands other than \code{help} must include at least one
method, specified explicitly as \code{method=\farg{method\_name}} or
implicitly with only \farg{method\_name}.  Currently Stan supports
the following methods:
%
\begin{center}
\begin{tabular}{r|l}
{\it Method} & {\it Description} \\ \hline \hline
{\tt sample}   &  sample using MCMC
\\
{\tt optimize} &  find posterior mode using optimization
\\
{\tt diagnose} &  diagnose models
\end{tabular}
\end{center}
%
All remaining configurations are option, with default values
provided for all arguments not explicitly specified.

\subsection{Help}

Informative output can be retrieved either globally, by requesting help
at the top-level, or locally, by requesting help deeper into the hierarchy.
Note that after any help has been displayed the execution immediately
terminates, even if a method has been specified.

\subsubsection{Top-Level Help}

If \code{help} is specified as the only argument then a usage message is
displayed.  Similarly, specifying \code{help\_all} by itself displays the entire
argument hierarchy.

\subsubsection{Context-Sensitive Help}

Specifying \code{help} after any argument displays a description and
valid options for that argument.  For example,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
./my_model sample help
\end{Verbatim}
\end{quote}
%
provides the top-level options for the \code{sample} method.

Detailed information on the argument, and all arguments deriving
from it, can accessed by specifying \code{help-all} instead,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
./my_model sample help-all
\end{Verbatim}
\end{quote}

\section{Full Argument Hierarchy}\label{detailed-command-arguments.section}

Here we present the full argument hierarchy, along with relevant details.  
Some typical use-case examples are provided in the next section. 

\subsection{Typographical Conventions}

The following typographical conventions are obeyed in the hierarchy.
%
\begin{itemize}
\item \code{arg=\farg{<value-type>}}
\\
Arguments with values; displays the value type, legal values, and default value
%
\item \code{\bfseries arg}
\\
Isolated categorical arguments; displays all valid subarguments
%
\item \code{\farg{value}}
\\
Values; describes effect of selecting the value
%
\item \code{\farg{\bfseries avalue}}
\\
Categorical arguments that appear as values to other arguments; displays all valid subarguments
\end{itemize}

\subsection{Top-Level Method Argument}

Every command must have exactly one method specified as the very first
argument.  The value type of \code{list element} means that the valid
values are enumerated as a list. 

\begin{description}
\hiercmdarg{}{method}{$$list element$$}
  {Analysis method (Note that \code{method=} is optional)}
  {Valid values: \  \code{sample, optimize, diagnose}}
  {Defaults to \code{sample}}
\end{description}

\subsection{Sampling-Specific Arguments}

The following arguments are specific to sampling.  The method argument
\code{sample} (or \code{method=sample}) must come first in order to
enable the subsequent arguments.  The other arguments are optional and
may appear in any order.

\begin{description}
  \hierlongcmd{\indentarrow}{\farg{\bfseries sample}}
    {Bayesian inference with Markov Chain Monte Carlo}
    {Valid subarguments: 
      \code{num\_samples, num\_warmup, save\_warmup, 
        \\ \hspace*{24pt} thin, adapt, algorithm}}
%
    \hiercmdarg{\indentarrow\indentarrow}{num\_samples}{$$int$$}
      {Number of sampling iterations}
      {Valid values: \  $0 \leq \mbox{\code{num\_samples}}$}
      {Defaults to \code{1000}}
%
    \hiercmdarg{\indentarrow\indentarrow}{num\_warmup}{$$int$$}
      {Number of warmup iterations}
      {Valid values: \  $0 \leq \mbox{\code{warmup}}$}
      {Defaults to \code{1000}}
%
    \hiercmdarg{\indentarrow\indentarrow}{save\_warmup}{$$boolean$$}
      {Stream warmup samples to output?}
      {Valid values: \ \code{0, 1}}
      {Defaults to \code{0}}
%
    \hiercmdarg{\indentarrow\indentarrow}{thin}{$$int$$}
      {Period between saved samples}
      {Valid values: \  $0 < \mbox{\code{thin}}$}
      {Defaults to \code{1}}
%
\end{description}

\subsubsection{Sampling Adaptation-Specific Parameters}

Currently all \Stan sampling algorithms utilize dual averaging to
optimize the step size (this optimization during adaptation of the
sampler should not be confused with running Stan's optimization method).
This optimization procedure is extremely flexible and for completeness
we have exposed each option, using the notation of
\citep{Hoffman-Gelman:2011, Hoffman-Gelman:2013}.  In practice the
efficacy of the optimization is sensitive to the value of these
parameters, and we do not recommend changing the defaults without
experience with the dual averaging algorithm.  For more information,
see the discussion of dual averaging in \citep{Hoffman-Gelman:2011,
  Hoffman-Gelman:2013}.

The following subarguments are introduced by the categorical argument
\code{adapt}.  Each subargument must contiguously follow \code{adapt},
though they may appear in any order.  

\begin{description}
    \hierlongcmd{\indentarrow\indentarrow}{\bfseries adapt}
      {Warmup Adaptation}
      {Valid subarguments: \code{engaged, gamma, delta, kappa, t0}}
%
      \hiercmdarg{\indentarrow\indentarrow\indentarrow}{engaged}{$$boolean$$}
        {Adaptation engaged?}
        {Valid values: \ \code{0, 1}}
        {Defaults to \code{1}}
%
      \hiercmdarg{\indentarrow\indentarrow\indentarrow}{gamma}{$$double$$}
        {Adaptation regularization scale}
        {Valid values: \  $0 < \mbox{\code{gamma}}$}
        {Defaults to \code{0.05}}
%
      \hiercmdarg{\indentarrow\indentarrow\indentarrow}{delta}{$$double$$}
        {Adaptation target acceptance statistic}
        {Valid values: \  $0 < \mbox{\code{delta}} < 1$}
        {Defaults to \code{0.65}}
%
      \hiercmdarg{\indentarrow\indentarrow\indentarrow}{kappa}{$$double$$}
        {Adaptation relaxation exponent}
        {Valid values: \  $0 < \mbox{\tt kappa}$}
        {Defaults to \code{0.75}}
%
      \hiercmdarg{\indentarrow\indentarrow\indentarrow}{t0}{$$double$$}
        {Adaptation iteration offset}
        {Valid values: \  $0 < \mbox{\code{t0}}$}
        {Defaults to \code{10}}
%
\end{description}
%
By setting the acceptance statistic \code{delta} to a value closer to
1 (its value must be strictly less than 1 and its default value is
0.65), adaptation will be forced to use smaller step sizes.  This can
improve sampling efficiency (effective samples per iteration) at the
cost of increased iteration times.  Raising the value of \code{delta}
will also allow some models that would otherwise get stuck overcome
their blockages; see also the \code{stepsize\_jitter} argument.

\subsubsection{Sampling Algorithm- and Engine-Specific Arguments}

The following batch of arguments are used to control the sampler used
for sampling.  The top-level specification is for engine, the only
valid value of which is \code{hmc} (this will change in the future as
we add new samplers).  

\begin{description}
    \hiercmdarg{\indentarrow\indentarrow}{algorithm}{$$list element$$}
      {Sampling algorithm}
      {Valid values: \  \code{hmc}}
      {Defaults to \code{hmc}}
\end{description}
%
Hamiltonian Monte Carlo is a very general approach to sampling that
utilizes techniques of differential geometry and mathematical physics
to generate efficient MCMC transitions.  This generality manifests in
a wealth of implementation choices.
%
\begin{description}
      \hierlongcmd{\indentarrow\indentarrow\indentarrow}{\farg{\bfseries hmc}}
        {Hamiltonian Monte Carlo}
        {Valid subarguments: \code{engine, metric, stepsize, stepsize\_jitter}}
\end{description}
%
All HMC implementations require at least two parameters: an
integration step size and a total integration time.  We refer to
different specifications of the latter as \textit{engines}.

In the \code{static\_hmc} implementation the total integration time
must be specified by the user, where as the \code{nuts}
implementation uses the No-U-Turn Sampler to determine
an optimal integration time dynamically. 
%
\begin{description}
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{engine}{$$list element$$}
          {Engine for Hamiltonian Monte Carlo}
          {Valid values: \  \code{static, nuts}}
          {Defaults to \code{nuts}}
\end{description}
%
The following options are activated for static HMC.
%
\begin{description}
          \hierlongcmd{\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow}{\farg{\bfseries static}}
            {Static integration time}
            {Valid subarguments: \code{int\_time}}
%
            \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow}{int\_time}{$$double$$}
              {Total integration time for Hamiltonian evolution}
              {Valid values: \  $0 < \mbox{\code{int\_time}}$}
              {Defaults to $2\pi$}
\end{description}
%
These options are for NUTS, an adaptive version of HMC.
%
\begin{description}
          \hierlongcmd{\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow}{\farg{\bfseries nuts}}
            {The No-U-Turn Sampler}
            {Valid subarguments: \code{max\_depth}}
%
            \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow}{max\_depth}{$$int$$}
              {Maximum tree depth}
              {Valid values: \  $0 < \mbox{\code{max\_depth}}$}
              {Defaults to \code{10}}
%
\end{description}
%
All HMC implementations in \Stan utilize quadratic kinetic energy
functions which are specified up to the choice of a symmetric,
positive-definite matrix known as a \textit{mass matrix} or, more
formally, a \textit{metric} \citep{Betancourt-Stein:2011}.

If the metric is constant then the resulting implementation is known
as \textit{Euclidean} HMC.  \Stan allows for three Euclidean HMC
implementations: a unit metric, a diagonal metric, and a dense
metric.  These can be specified with the values \code{unit\_e},
\code{diag\_e}, and \code{dense\_e}, respectively.

Future versions of \Stan will also include dynamic metrics associated
with \textit{Riemannian} HMC \citep{GirolamiCalderhead:2011, Betancourt:2012}.
%
\begin{description}
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{metric}{$$list element$$}
          {Geometry of base manifold}
          {Valid values: \  \code{unit\_e, diag\_e, dense\_e}}
          {Defaults to \code{diag\_e}}
%
          \hiershortcmd{\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow}{\farg{unit\_e}}
            {Euclidean manifold with unit metric}
%
          \hiershortcmd{\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow}{\farg{diag\_e}}
            {Euclidean manifold with diag metric}
%
          \hiershortcmd{\indentarrow\indentarrow\indentarrow\indentarrow\indentarrow}{\farg{dense\_e}}
            {Euclidean manifold with dense metric}
\end{description}
%
All implementations of HMC also use numerical integrators requiring a
step size.  We also allow that step size to be ``jittered'' randomly
during sampling to avoid any poor interactions with a fixed step size
and regions of high curvature.  The maximum amount of jitter is 1,
which will cause step sizes to be selected in the range of 0 to twice
the adapted step size.  Low step sizes can get HMC samplers unstuck
that would otherwise get stuck with higher step sizes.  The downside
is that jittering below the adapted value will increase the number of
leapfrog steps required and thus slow down iterations, whereas
jittering above the adapted value can cause premature rejection due to
simulation error in the Hamiltonian dynamics calculation.  See
\citep{Neal:2011} for further discussion of step-size jittering.
%
\begin{description}
%
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{stepsize}{$$double$$}
          {Step size for discrete evolution}
          {Valid values: \  $0 < \code{stepsize}$}
          {Defaults to \code{1}}
%
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{stepsize\_jitter}{$$double$$}
          {Uniformly random jitter of the stepsize, in percent}
          {Valid values: \  $0 \leq \mbox{\code{stepsize\_jitter}} \leq 1$}
          {Defaults to \code{0}}
\end{description}

\subsection{Optimization-Specific Commands}

The following arguments are for the top-level method \code{optimize}.
They allow control of the optimization algorithm, and some of its
configuration.  The other arguments may appear in any order.

\begin{description}
%
  \hierlongcmd{\indentarrow}{\farg{\bfseries optimize}}
    {Point estimation}
    {Valid subarguments: \code{algorithm, iter, save\_iterations}}
%
    \hiercmdarg{\indentarrow\indentarrow}{algorithm}{$$list element$$}
      {Optimization algorithm}
      {Valid values: \  \code{nesterov, bfgs, newton}}
      {Defaults to \code{bfgs}}
\end{description}
%
The following options are for the BFGS optimizer.  BFGS is the default
optimizer and also much faster than the other optimizers.  

Convergence monitoring in BFGS is controlled by a number of tolerance
values, any one of which being satisified causes the algorithm to
terminate with a solution.
%
\begin{itemize}
\item The log probability is considered to have converged if
\[
\left| \log p(\theta^{(i)}|y) - \log p(\theta^{(i-1)}|y) \right| <
\mbox{\code{tol\_obj}}.
\]
\item The parameters are considered to have converged if
%
\\
\[
|| \theta^{(i)} - \theta^{(i-1)} || < \mbox{\code{tol\_param}}.
\]
%
\item The gradient is considered to have converged to 0 if 
\[
|| \nabla_{\theta} \log p(\theta^{(i)}|y) || < \mbox{\code{tol\_grad}}.
\]
\end{itemize}
%
Here, $i$ is the current iteration, $\theta^{(i)}$ is the value of the
parameters at iteration $i$, $y$ is the data, $p(\theta^{(i)}|y)$ is
the posterior probability of $\theta^{(i)}$ up to a proportion,
$\nabla_{\theta}$ is the gradient operator with respect to $\theta$,
$|u|$ is absolute value (L1 norm) of $u$, and $||u||$ is vector length
(L2 norm) of $u$.

The other command-line argument for BFGS is \code{init\_alpha}, which
is first step size to try on the initial iteration. If the first
iteration takes a long time (and requires a lot of function
evaluations) set \code{init\_alpha} to be the roughly equal to the
alpha used in that first iteration.  \code{init\_alpha} has a tiny
default value, which is reasonable for many problems but might be too
large or too small depending on the objective function and
initialization. Being too big or too small just means that the first
iteration will take longer (i.e., require more gradient evaluations)
before the line search finds a good step length. It's not a critical
parameter, but for optimizing the same model multiple times (as
you tweak things or with different data) being able to change it can
save some real time.
%
\begin{description}
      \hierlongcmd{\indentarrow\indentarrow\indentarrow}{\farg{\bfseries bfgs}}
        {BFGS with linesearch}
        {Valid subarguments: \code{stepsize}}
%
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{init\_alpha}{$$double$$}
           {Line search step size for first iteration}
           {Valid values: $0 < \mbox{\code{init\_alpha}}$}
           {Defaults to \code{0.001}}
%
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{tol\_obj}{$$double$$}
           {Convergence tolerance on changes in objective function value}
           {Valid values: $0 < \mbox{\code{tol\_obj}}$}
           {Defaults to \code{1e-8}}
%
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{tol\_grad}{$$double$$}
        {Convergence tolerance on the norm of the gradient}
        {Valid values: $0 < \mbox{\code{tol\_grad}}$}
        {Defaults to \code{1e-8}}
%
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{tol\_param}{$$double$$}
        {Convergence tolerance on changes in parameter value}
        {Valid values: $0 < \mbox{\code{tol\_param}}$}
        {Defaults to \code{1e-8}}
%
\end{description}
%
The following options are for the Nesterov optimizer.
%
\begin{description}
      \hierlongcmd{\indentarrow\indentarrow\indentarrow}{\farg{\bfseries nesterov}}
        {Nesterov's accelerated gradient method}
        {Valid subarguments: \code{stepsize}}
%
        \hiercmdarg{\indentarrow\indentarrow\indentarrow\indentarrow}{stepsize}{$$double$$}
          {Step size for discrete evolution}
          {Valid values: \  $0 < \mbox{\code{stepsize}}$}
          {Defaults to \code{1}}
\end{description}
%
The following argument is for Newton's optimization method;  there are
currently no configuration parameters for Newton's method, and it is
not recommended because of the slow Hessian calcuation involving
finite differences.
%
\begin{description}
      \hiershortcmd{\indentarrow\indentarrow\indentarrow}{\farg{\bfseries
          newton}}
        {Newton's method}
%
\end{description}
%
The remaining arguments apply to all optimizers.
\begin{description}
%
    \hiercmdarg{\indentarrow\indentarrow}{iter}{$$int$$}
      {Total number of iterations}
      {Valid values: \  $0 < \mbox{\code{iter}}$}
      {Defaults to \code{2000}}
%
    \hiercmdarg{\indentarrow\indentarrow}{save\_iterations}{$$boolean$$}
      {Stream optimization progress to output?}
      {Valid values: \  \ \code{0, 1}}
      {Defaults to \code{0}}
%
\end{description}

\subsection{Diagnostic-Specific Arguments}

The following arguments are specific to diagnostics.  As of now, the
only diagnostic is gradients of the log probability function.

\begin{description}

  \hierlongcmd{\indentarrow}{\farg{\bfseries diagnose}}
    {Model diagnostics}
    {Valid subarguments: \code{test}}
%
    \hiercmdarg{\indentarrow\indentarrow}{test}{$$list element$$}
      {Diagnostic test}
      {Valid values: \  \code{gradient}}
      {Defaults to \code{gradient}}
%
      \hiershortcmd{\indentarrow\indentarrow\indentarrow}{\farg{gradient}}
        {Check model gradient against finite differences}
%
\end{description}

\subsection{General-Purpose Arguments}

The following arguments may be used with any of the previous
configurations.   They may come either before or after the other
subarguments of the top-level method.

\subsubsection{Process Identifier Argument}

\begin{description}
\hiercmdarg{}{id}{$$int$$}
  {Unique process identifier}
  {Valid values: \  $0 < \mbox{\code{id}}$}
  {Defaults to \code{0}}
%
\end{description}

\subsubsection{Input Data Arguments}

\begin{description}

\hierlongcmd{}{data}
  {Input data options}
  {Valid subarguments: \code{file}}
%
  \hiercmdarg{\indentarrow}{file}{$$string$$}
    {Input data file}
    {Valid values: \  Path to existing file}
    {Defaults to empty path}
%
\end{description}

\subsubsection{Initialization Arguments}

\begin{description}
\hiercmdarg{}{init}{$$string$$}
  {Initialization method: \\
        \hspace*{8pt} $\bullet$ \ real number $\mbox{\farg{x}} > 0$ initializes randomly bewteen [-\farg{x},
        \farg{x}]; 
        \\
        \hspace*{8pt} $\bullet$ \  \code{0} initializes to 0; 
        \\
        \hspace*{8pt} $\bullet$ \  non-number interpreted as a data file}
  {Valid values: \  All}
  {Defaults to \code{2}}
%
\end{description}


\subsubsection{Random Number Generator Arguments}

\begin{description}

\hierlongcmd{}{{\bfseries random}}
  {Random number configuration}
  {Valid subarguments: \code{seed}}
%
  \hiercmdarg{\indentarrow}{seed}{$$unsigned int$$}
    {Random number generator seed}
    {Valid values: \\
      \hspace*{8pt} $\bullet$ \ $\mbox{\code{seed}} \geq 0$ generates seed; 
      \\
      \hspace*{8pt} $\bullet$ \ $\mbox{\code{seed}} < 0$ uses seed generated from time}
    {Defaults to \code{-1}}
%
\end{description}

\subsubsection{Output Arguments}

\begin{description}
\hierlongcmd{}{{\bfseries output}}
  {File output options}
  {Valid subarguments: \code{file, append\_sample, diagnostic\_file,
      \\ \hspace*{24pt} append\_diagnostic, refresh}}
%
  \hiercmdarg{\indentarrow}{file}{$$string$$}
    {Output file}
    {Valid values: \  Path to existing file}
    {Defaults to \code{samples.csv}}
%
  \hiercmdarg{\indentarrow}{append\_sample}{$$boolean$$}
    {Append sample output to existing file?}
    {Valid values: \ \code{0, 1}}
    {Defaults to \code{0}}
%
  \hiercmdarg{\indentarrow}{diagnostic\_file}{$$string$$}
    {Auxiliary output file for diagnostic information}
    {Valid values: \  Path to existing file}
    {Defaults to empty path}
%
  \hiercmdarg{\indentarrow}{append\_diagnostic}{$$boolean$$}
    {Append diagnostic output to existing file?}
    {Valid values: \ \code{0, 1}}
    {Defaults to \code{0}}
%
  \hiercmdarg{\indentarrow}{refresh}{$$int$$}
    {Number of interations between screen updates}
    {Valid values: \  $0 < \mbox{\code{refresh}}$}
    {Defaults to \code{100}}
%
\end{description}

\section{Command-Line Option Examples}

The hierarchical structure of the command-line options can be
intimidating, and here we provide an example workflow to help ease the
introduction to new users, especially those used to \Stan 1.3 or
earlier releases.  The examples in this section are for Mac OS and
Linux; on Windows, just remove the \code{./} before the executable and
change the line-continuation character from Unix's
\code{\textbackslash} to DOS's \code{\textasciicircum}.  As in
previous sections, the indentation on continued lines is for
pedagogical purposes only and does not convey any content to the
executable.

Let's say that we've just built our model, \code{model}, and are ready to run.
We begin by specifying data and init files,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model data file=model.data.R init=model.init.R
\end{Verbatim}
\end{quote}
%
but our model doesn't run.  Instead, the above command prints
%
\begin{quote}
\begin{Verbatim}
A method must be specified!
Failed to parse arguments, terminating Stan
\end{Verbatim}
\end{quote}
%
The problem is that we forgot to specify a method.

All \Stan arguments have default values, except for the method.  This
is the only argument that must be specified by the user and a model
will not run without it (not to say that the model will run without error,
for example a model that requires data will eventually fail unless an input file 
is specified with \code{file} under \code{data}).  Assuming that we want to draw
MCMC samples from our model, we can either specify a method
implicitly,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model sample data file=model.data.R init=model.init.R
\end{Verbatim}
\end{quote}
%
or explicitly,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample data file=model.data.R  \
          init=model.init.R
\end{Verbatim}
\end{quote}
%
In either case our model now executes without any problem.

Now let's say that we want to customize our execution.  In
particular we want to set the seed for the random number generator,
but we forgot the specific argument syntax.  Information for each
argument can displayed by calling \code{help},
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model random help
\end{Verbatim}
\end{quote}
%
which returns
%
\begin{quote}
\begin{Verbatim}
random
  Random number configuration
  Valid subarguments: seed
...
\end{Verbatim}
\end{quote}
%
before printing usage information.  For information on the 
seed argument we just call help one level deeper,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model random seed help
\end{Verbatim}
\end{quote}
%
which returns
%
\begin{quote}
\begin{Verbatim}
seed=<unsigned int>
  Random number generator seed
  Valid values: seed > 0, if negative seed is generated from time
  Defaults to -1
  ...
\end{Verbatim}
\end{quote}
%
Fully informed, we can now run with a given seed,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample data fle=model.data.R  \
          init=model.init.R                    \
          random seed=5
\end{Verbatim}
\end{quote}

The arguments \code{method}, \code{data}, \code{init}, and
\code{random} are all top-level arguments.  To really see the power of
a hierarchical argument structure let's try to drill down and specify
the metric we use for HMC: instead of the default diagonal Euclidean
metric, we want to use a dense Euclidean metric.  Attempting to
specify the metric we try
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample data file=model.data.R  \
          init=model.init.R                     \
          random seed=5                         \
          metric=unit
\end{Verbatim}
\end{quote}
%
only to have the execution fail with the message
%
\begin{quote}
\begin{Verbatim}
metric=unit_e is either mistyped or misplaced.
Perhaps you meant one of the following valid configurations?
  method=sample algorithm=hmc metric=<list_element>
Failed to parse arguments, terminating Stan
\end{Verbatim}
\end{quote}
%
The argument \code{metric} does exist, but not at the top-level.  In order
to specify it we have to drill down into sample by first specifying the
sampling algorithm, as noted in the suggestion,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample algorithm=hmc metric=unit \
          data file=model.data.R                  \
          init=model.init.R                       \
          random seed=5       
\end{Verbatim}
\end{quote}
%
Unfortunately we still messed up,
%
\begin{quote}
\begin{Verbatim}
unit is not a valid value for "metric"
  Valid values: unit_e, diag_e, dense_e
Failed to parse arguments, terminating Stan
\end{Verbatim}
\end{quote}
%
Tweaking the metric name we make one last attempt,
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample algorithm=hmc metric=unit_e \
          data file=model.data.R                    \
          init=model.init.R                         \
          random seed=5
\end{Verbatim}
\end{quote}
%
which successfully runs.

Finally, let's consider the circumstance where our model runs fine but
the NUTS iterations keep saturating the default tree depth limit of 10.  We need
to change the limit, but how do we specify NUTS let alone the maximum tree depth?
To see how let's take advantage of the \code{help-all} option which prints all
arguments that derive from the given argument.  We know that NUTS is somehow
related to sampling, so we try
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample help-all
\end{Verbatim}
\end{quote}
%
which returns the verbose output,
%
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
sample
  Bayesian inference with Markov Chain Monte Carlo
  Valid subarguments: num_samples, num_warmup,
                      save_warmup, thin, adapt, algorithm

  num_samples=<int>
    Number of sampling iterations
    Valid values: 0 <= num_samples
    Defaults to 1000

  num_warmup=<int>
    Number of warmup iterations
    Valid values: 0 <= warmup
    Defaults to 1000

  save_warmup=<boolean>
    Stream warmup samples to output?
    Valid values: [0, 1]
    Defaults to 0

  thin=<int>
    Period between saved samples
    Valid values: 0 < thin
    Defaults to 1

  adapt
    Warmup Adaptation
    Valid subarguments: engaged, gamma, delta, kappa, t0

    engaged=<boolean>
      Adaptation engaged?
      Valid values: [0, 1]
      Defaults to 1

    gamma=<double>
      Adaptation regularization scale
      Valid values: 0 < gamma
      Defaults to 0.05

    delta=<double>
      Adaptation target acceptance statistic
      Valid values: 0 < delta < 1
      Defaults to 0.65

    kappa=<double>
      Adaptation relaxation exponent
      Valid values: 0 < kappa
      Defaults to 0.75

    t0=<double>
      Adaptation iteration offset
      Valid values: 0 < t0
      Defaults to 10

  algorithm=<list element>
    Sampling algorithm
    Valid values: hmc
    Defaults to hmc

    hmc
      Hamiltonian Monte Carlo
      Valid subarguments: engine, metric, stepsize, 
                          stepsize_jitter

      engine=<list element>
        Engine for Hamiltonian Monte Carlo
        Valid values: static, nuts
        Defaults to nuts

        static
          Static integration time
          Valid subarguments: int_time

          int_time=<double>
            Total integration time for Hamiltonian evolution
            Valid values: 0 < int_time
            Defaults to 2 * pi

        nuts
          The No-U-Turn Sampler
          Valid subarguments: max_depth

          max_depth=<int>
            Maximum tree depth
            Valid values: 0 < max_depth
            Defaults to 10

      metric=<list element>
        Geometry of base manifold
        Valid values: unit_e, diag_e, dense_e
        Defaults to diag_e

        unit_e
          Euclidean manifold with unit metric

        diag_e
          Euclidean manifold with diag metric

        dense_e
          Euclidean manifold with dense metric

      stepsize=<double>
        Step size for discrete evolution
        Valid values: 0 < stepsize
        Defaults to 1

      stepsize_jitter=<double>
        Uniformly random jitter of the stepsize, in percent
        Valid values: 0 <= stepsize_jitter <= 1
        Defaults to 0
...
\end{Verbatim}
\end{quote}
%
Following the hierarchy, the maximum tree depth derives from \code{nuts},
which itself is a value for the argument \code{engine} which derives from
\code{hmc}.  Adding this to our previous call we attempt
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample                       \
              algorithm=hmc                   \
                  metric=unit_e               \
                  engine=nuts max_depth=-15   \
          data file=model.data.R              \
          init=model.init.R                   \
          random seed=5                       \
\end{Verbatim}
\end{quote}
%
which yields
%
\begin{quote}
\begin{Verbatim}
-1 is not a valid value for "max_depth"
  Valid values: 0 < max_depth
Failed to parse arguments, terminating Stan
\end{Verbatim}
\end{quote}
%
Where did that negative sign come from?  Clumsy fingers are nothing
to be embarrassed about, especially with such complex argument 
configurations.  Removing the guilty character, we try
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ./model method=sample                     \
              algorithm=hmc                 \
                  metric=unit_e             \
                  engine=nuts max_depth=15  \
          data file=model.data.R            \
          init=model.init.R                 \
          random seed=5
\end{Verbatim}
\end{quote}
%
which finally runs without issue.

\section{Command Templates}

This section provides templates for all of the arguments deriving from
each of the possible methods: \code{sample}, \code{optimize}, and \code{diagnose}.  
Arguments in square brackets are optional,
those not in square brackets are required for the template.

\subsection{Sampling Templates}
%
The No-U-Turn sampler (NUTS) is the default (and recommended) sampler
for Stan.  The full set of configuration options is in
\reffigure{nuts-command}.  
%
\begin{figure}
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> ./my_model sample                                     \
                 algorithm=hmc                          \
                     engine=nuts                        \
                       [max_depth=<int>]                \
                     [metric={unit_e,diag_e,dense_e}]   \
                     [stepsize=<double>]                \
                     [stepsize_jitter=<double>]         \
                 [num_samples=<int>]                    \
                 [num_warmup=<int>]                     \
                 [save_warmup=<boolean>]                \
                 [thin=<int>]                           \
                 [adapt                                 \
                      [engaged=<boolean>]               \
                      [gamma=<double>]                  \
                      [delta=<double>]                  \
                      [kappa=<double>]                  \
                      [t0=<double>] ]                   \
             [data file=<string>]                       \
             [init=<string>]                            \
             [random seed=<int>]                        \
             [output                                    \
                  [file=<string>]                       \
                  [append_sample=<boolean>]             \
                  [diagnostic_file=<string>]            \
                  [append_diagnostic=<boolean>]         \
                  [refresh=<int>] ]
\end{Verbatim}
\end{quote}
\caption{\small\it Command skeleton for invoking the no-U-turn sampler
  (NUTS). This is the same skeleton as that for basic HMC in
  \reffigure{hmc-command}.  Elements in braces are optional.
  All arguments and their default values are described in detail in
  \refsection{detailed-command-arguments}.}
\label{nuts-command.figure}
\end{figure}
%

A standard Hamiltonian Monte Carlo (HMC) sampler with user-specified
integration time may also be used.  Its set of configuration options
are shown in \reffigure{hmc-command}.

Both NUTS and HMC may be configured with either a unit,
diagonal or dense Euclidean metric, with a diagonal metric the default.%
%
\footnote{In Euclidean HMC, a diagonal metric emulates different step
sizes for each parameter.  Explicitly varying step sizes were used in
Stan 1.3 and before; \cite{Neal:2011} discusses the equivalence.}
%
A unit metric provides no parameter-by-parameter scaling,
a diagonal metric scales each parameter independently, and
a dense metric also rotates the parameters so
that correlated parameters may move together.  Although dense metrics
offer the hope of superior simulation performance, they
require more computation per iteration.  Specifically for $m$ samples of a model with
$n$ parameters, the dense metric requires $\mathcal{O}(n^3 \log(m) +
n^2 \, m)$ operations, whereas diagonal metrics require only
$\mathcal{O}(n \, m)$.  Furthermore, dense metrics are difficult
to estimate, given the $\mathcal{O}(n^2)$ components with complex
interdependence.
%
\begin{figure}
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> ./my_model sample                                     \
                 algorithm=hmc                          \
                     engine=static                      \
                       [int_time=<double>]              \
                     [metric={unit_e,diag_e,dense_e}]   \
                     [stepsize=<double>]                \
                     [stepsize_jitter=<double>]         \
                 [num_samples=<int>]                    \
                 [num_warmup=<int>]                     \
                 [save_warmup=<boolean>]                \
                 [thin=<int>]                           \
                 [adapt                                 \
                      [engaged=<boolean>]               \
                      [gamma=<double>]                  \
                      [delta=<double>]                  \
                      [kappa=<double>]                  \
                      [t0=<double>] ]                   \
             [data file=<string>]                       \
             [init=<string>]                            \
             [random seed=<int>]                        \
             [output                                    \
                  [file=<string>]                       \
                  [append_sample=<boolean>]             \
                  [diagnostic_file=<string>]            \
                  [append_diagnostic=<boolean>]         \
                  [refresh=<int>] ]
\end{Verbatim}
\end{quote}
\caption{\small\it Command skeleton for invoking the basic Hamiltonian
  Monte Carlo sampler (HMC).  This is the same as the NUTS command
  skeleton shown in \reffigure{nuts-command} other than for the
  engine.  Elements in braces are optional.  All arguments and their
  default values are described in detail in
  \refsection{detailed-command-arguments}.}
\label{hmc-command.figure}
\end{figure}

\subsection{Optimization Templates}
%
Stan supports several optimizers.  These share many of their
configuration options with the samplers.  The default optimizer is the
Broyden-Fletcher-Goldfarb-Shanno (BFGS) method (see
\citep{NocedalWright:2006} for more information on BFGS).  The command
skeleton for BFGS is in \reffigure{bfgs-command}.
%
\begin{figure}
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> ./my_model optimize                                   \
                 algorithm=bfgs                         \
                     [init_alpha=<double>]              \
                     [tol_obj=<double>]                 \
                     [tol_grad=<double>]                \
                     [tol_param=<double>]               \
                 [iter=<int>]                           \
                 [save_iterations=<boolean>]            \
             [data file=<string>]                       \
             [init=<string>]                            \
             [random seed=<int>]                        \
             [output                                    \
                  [file=<string>]                       \
                  [append_sample=<boolean>]             \
                  [diagnostic_file=<string>]            \
                  [append_diagnostic=<boolean>]         \
                  [refresh=<int>] ]
\end{Verbatim}
\end{quote}
\caption{\small\it Command skeleton for invoking the BFGS optimizer.
  All arguments and their default values are described in detail in
  \refsection{detailed-command-arguments}.}
\label{bfgs-command.figure}
\end{figure}
%

Stan also supports Nesterov's dual-averaging method
\citep{Nesterov:2009} for optimization.  The BFGS method is the
default approach because it is more efficient.  The command skeleton
for dual averaging is shown in \reffigure{nesterov-command};  it is
identical to that for BFGS other than the algorithm name.
%
\begin{figure}
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> ./my_model optimize                                   \
                 algorithm=nesterov                     \
                   [stepsize=<double>]                  \
                 [iter=<int>]                           \
                 [save_iterations=<boolean>]            \
             [data file=<string>]                       \
             [init=<string>]                            \
             [random seed=<int>]                        \
             [output                                    \
                  [file=<string>]                       \
                  [append_sample=<boolean>]             \
                  [diagnostic_file=<string>]            \
                  [append_diagnostic=<boolean>]         \
                  [refresh=<int>] ]
\end{Verbatim}
\end{quote}
\caption{\small\it Command skeleton for invoking the Nesterov
  dual-averaging ptimizer.  All arguments and their default values are
  described in detail in
  \refsection{detailed-command-arguments}.}
\label{nesterov-command.figure}
\end{figure}
%
Stan also supports Newton's method; see \citep{NocedalWright:2006} for
more information.  This method is the least efficient of the three,
but has the advantage of setting its own step size.  Other than not
having a stepsize argument, the skeleton for Newton's method shown in
\reffigure{newton-command} is identical to that for BFGS and
Nesterov's dual averaging.
%
\begin{figure}
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> ./my_model optimize                                   \
                 algorithm=newton                       \
                 [iter=<int>]                           \
                 [save_iterations=<boolean>]            \
             [data file=<string>]                       \
             [init=<string>]                            \
             [random seed=<int>]                        \
             [output                                    \
                  [file=<string>]                       \
                  [append_sample=<boolean>]             \
                  [diagnostic_file=<string>]            \
                  [append_diagnostic=<boolean>]         \
                  [refresh=<int>] ]
\end{Verbatim}
\end{quote}
\caption{\small\it Command skeleton for invoking the Newton optimizer.
  All arguments and their default values are described in detail in
  \refsection{detailed-command-arguments}.}
\label{newton-command.figure}
\end{figure}
%

\subsection{Diagnostic Command Skeleton}

Stan reports on gradients for the model at a specified or randomly
generated initial value.  The command-skeleton in this case is very
simple, and shown in \reffigure{diagnostic-command}.
%
\begin{figure}
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> ./my_model diagnose                  \
                 [test=gradient]       \
             [data file=<string>]      \
             [init=<string>]           \
             [random seed=<int>]       \
\end{Verbatim}
\end{quote}
\caption{\small\it Command skeleton for invoking model diagnostics.  All
  arguments and their default values are described in detail in
  \refsection{detailed-command-arguments}.}
\label{diagnostic-command.figure}
\end{figure}


\chapter{Print Command for Output Analysis}\label{print-command.chapter}

\noindent
Stan is distributed with a print command that is able to read in the
output of one or more Markov chains and summarize the posterior fits.
This operation mimics the \code{print(fit)} command in RStan, which
itself was modeled on the print functions from R2WinBUGS and R2jags.

\section{Building the Print Command}

Stan's \code{print} command is built along with \code{stanc} into the
\code{bin} directory.  It can be compiled directly using the makefile
as follows from the home directory into which Stan was unpacked (here
written as \code{<stan-home>}).
%
\begin{quote}
\begin{Verbatim}
> cd <stan-home>
> make bin/print
\end{Verbatim}
\end{quote}
%
All the usual compiler options from Stan's makefile apply, such as
\code{O=\farg{N}} to set optimization level to \farg{N}, and
\code{CC=clang++} to set the compilation to use clang. 

\section{Running the Print Command}

The print command is executed on one or more samples.csv files.  These
files may be provided as command-line arguments separated by spaces.
That means that wildcards may be used, as they will be replaced by
space-separated file names by the operating system's command-line
interpreter. 

Suppose there are three samples files in a directory generated by
fitting a negative binomial model to a small data set.
%
\begin{quote}
\begin{Verbatim}[fontshape=sl]
> ls samples*.csv
\end{Verbatim}
%
\begin{Verbatim}
samples1.csv	samples2.csv	samples3.csv
\end{Verbatim}
%
\begin{Verbatim}[fontshape=sl]
> bin/print samples*.csv
\end{Verbatim}
\end{quote}
%
The result of \code{bin/print} is displayed in \reffigure{bin-print-eg}.
%
\begin{figure}
\begin{Verbatim}[fontsize=\footnotesize]
   Inference for Stan model: negative_binomial_model
   1 chains: each with iter=(1000); warmup=(0); thin=(1); 1000 iterations saved.

   Warmup took (0.054) seconds, 0.054 seconds total
   Sampling took (0.059) seconds, 0.059 seconds total

                   Mean     MCSE   StdDev    5%   50%   95%  N_Eff  N_Eff/s  R_hat
   lp__             -14  6.2e-02  1.0e+00   -16   -14   -13    283     4773   1.00
   accept_stat__   0.88  5.6e-03  1.8e-01  0.51  0.95   1.0   1000    16881   1.00
   stepsize__      0.30  1.3e-15  8.9e-16  0.30  0.30  0.30   0.50      8.5   1.00
   treedepth__      1.4  2.6e-02  8.0e-01  0.00   1.0   2.0    946    15978   1.00
   alpha             17  1.8e+00  2.5e+01   1.9   9.5    50    181     3054   1.00
   beta              10  1.1e+00  1.4e+01   1.2   6.2    31    181     3057    1.0

   Samples were drawn using hmc with nuts.
   For each parameter, N_Eff is a crude measure of effective sample size,
   and R_hat is the potential scale reduction factor on split chains (at 
   convergence, R_hat=1).\end{Verbatim}
\vspace*{-6pt}
\caption{\small\it Example output from \code{bin/print}.  The model
  parameters are \code{alpha} and \code{beta}.  The values for each
  quantity are the posterior means, standard deviations, and
  quantiles, along with Monte-Carlo standard error, effective sample
  size estimates (per second), and convergence diagnostic statistic.
  These values are all estimated from samples. In addition to the
  parameters, the value \code{lp\_\_} is the total log probability
  computed by the model (up to an additive constant).  The quantity
  \code{accept\_stat\_\_} is the NUTS acceptance statistic used by
  NUTS for slice and Metropolis rejection, \code{stepsize\_\_} the
  step size used by NUTS in its Hamiltonian simulation, and
  \code{treedepth\_\_} is the depth of tree used by NUTS, which is the
  log (base 2) of the number of leapfrog steps taken during the
  Hamiltonian simulation.  }\label{bin-print-eg.figure}
\end{figure}
%\end{quote}
%
The posterior is skewed to the high side, resulting in posterior means
($\alpha=17$ and $\beta=10$) that are a long way away from the posterior
medians ($\alpha=9.5$ and $\beta=6.2$);  the posterior median is the
value listed under \code{50\%}, which is the 50th percentile of the
posterior values.

For Windows, the forward slash in paths need to be converted to backslashes.

\section{Command-line Options}

In addition to the filenames, \code{print} includes three flags to customize the output.  

\begin{description}
\longcmd{help}
{Prints usage information}
{No help output by default}
%
\cmdarg{sig\_figs}{int}
{Sets the number of significant figures displayed in the output}
{Valid values: 0 \textless sig\_figs}
{default = \code{2} }
%
\cmdarg{autocorr}{int}
{Calculates and then displays the autocorrelation of the specified chain}
{Valid values: Any integer matching a chain index}
{No autocorrelation output by default}
%
\end{description}

\chapter{Dump Data Format}\label{dump.chapter}

\noindent 
For representing structured data in files, \Stan uses the dump format
introduced in \SPLUS and used in \R and \JAGS (and in \BUGS, but with
a different ordering).   A dump file is structured as a sequence of
variable definitions.  Each variable is defined in terms of its
dimensionality and its values.   There are three kinds of variable
declarations, one for scalars, one for sequences, and one for general
arrays.

\section{Creating Dump Files}

Dump files can be created from R using RStan.  The function is
\code{stan\_rdump} in package \code{rstan}.

Using R's native \code{dump()} function can produce dump files which
Stan cannot read in.  The underlying cause is that R gets creative in
the format it uses for output, only being constrained to something
that can be executed in R.  So it will write the array containing the
values 1, 2, 3, 4 as \code{1:4} rather than as \code{c(1,2,3,4)}.

\section{Scalar Variables}

A simple scalar value can be thought of as having an empty list of
dimensions.  Its declaration in the dump format follows the \SPLUS
assignment syntax.  For example, the following would constitute a
valid dump file defining a single scalar variable \code{y} with value
17.2.
%
\begin{quote}
\begin{Verbatim}
y <- 
17.2
\end{Verbatim}
\end{quote}
%
A scalar value is just a zero-dimensional array value.


\section{Sequence Variables}

One-dimensional arrays may be specified directly using the \SPLUS
sequence notation.  The following example defines an integer-value and
a real-valued sequence.
%
\begin{quote}
\begin{Verbatim}
n <- c(1,2,3)
y <- c(2.0,3.0,9.7)
\end{Verbatim}
\end{quote}
%
Arrays are provided without a declaration of dimensionality because
the reader just counts the number of entries to determine the size of
the array.

Sequence variables may alternatively be represented with \R's
colon-based notation.  For instance, the first example above could
equivalently be written as
%
\begin{quote}
\begin{Verbatim} 
n <- 1:3
\end{Verbatim}
\end{quote}
% 
The sequence denoted by \code{1:3} is of length 3, running from 1 to 3
inclusive.  The colon notation allows sequences going from high to
low, as in the first of the following examples, which is equivalent to
the second.
%
\begin{quote}
\begin{Verbatim}
n <- 2:-2
n <- c(2,1,0,-1,-2)
\end{Verbatim}
\end{quote}
%


\section{Array Variables}

For more than one dimension, the dump format uses a dimensionality
specification.  For example,
%
\begin{quote}
\begin{verbatim}
y <- structure(c(1,2,3,4,5,6), .Dim = c(2,3))
\end{verbatim}
\end{quote}
%
This defines a $2 \times 3$ array.  Data is stored in column-major
order, meaning the values for \code{y} will be as follows.
%
\begin{quote}
\begin{Verbatim}
y[1,1] = 1     y[1,2] = 3     y[1,3] = 5    
y[2,1] = 2     y[2,2] = 4     y[2,3] = 6
\end{Verbatim}
\end{quote}
%
The \code{structure} keyword just wraps a sequence of values and a
dimensionality declaration, which is itself just a sequence of
non-negative integer values.  The product of the dimensions must equal
the length of the array.

If the values happen to form a contiguous sequence of integers,
they may be written with colon notation.  Thus the example above is
equivalent to the following.
%
\begin{quote}
\begin{verbatim}
y <- structure(1:6, .Dim = c(2,3))
\end{verbatim}
\end{quote}
%
The same applies to the specification of dimensions, though it is
perhaps less likely to be used. In the above example,
c(2,3) could be written as \code{2:3}.

Arrays of more than two dimensions are written in a last-index major form.
For example, 
%
\begin{quote}
\begin{verbatim}
z <- structure(1:24, .Dim = c(2,3,4))
\end{verbatim}
\end{quote}
%
produces a three-dimensional \code{int} (assignable to \code{real})
array \code{z} with values
%
\begin{quote}
\begin{verbatim}
z[1,1,1] =  1   z[1,2,1] =  3   z[1,3,1] =  5
z[2,1,1] =  2   z[2,2,1] =  4   z[2,3,1] =  6

z[1,1,2] =  7   z[1,2,2] =  9   z[1,3,2] = 11
z[2,1,2] =  8   z[2,2,2] = 10   z[2,3,2] = 12

z[1,1,3] = 13   z[1,2,3] = 15   z[1,3,3] = 17
z[2,1,3] = 14   z[2,2,3] = 16   z[2,3,3] = 18

z[1,1,4] = 19   z[1,2,4] = 21   z[1,3,4] = 23
z[2,1,4] = 20   z[2,2,4] = 22   z[2,3,4] = 24
\end{verbatim}
\end{quote}

\section{Matrix- and Vector-Valued Variables}

The dump format for matrices and vectors, including arrays of matrices
and vectors, is the same as that for arrays of the same shape.

\subsection{Vector Dump Format}

The following three declarations have the same dump format for their
data.
%
\begin{quote}
\begin{Verbatim}
real a[K];
vector[K] b;
row_vector[K] c;
\end{Verbatim}
\end{quote}

\subsection{Matrix Dump Format}

The following declarations have the same dump format.
%
\begin{quote}
\begin{Verbatim}
real a[M,N];
matrix[M,N] b;
\end{Verbatim}
\end{quote}

\subsection{Arrays of Vectors and Matrices}

The key to undertanding arrays is that the array indexing comes before
any of the container indexing.  That is, an array of vectors is just
that --- provide an index and get a vector.  See
Section~\refsection{arrays-of-matrices} for more information on
indexing and assignment.

For the dump data format, the following declarations have the same
arrangement.
%
\begin{quote}
\begin{Verbatim}
real a[M,N];
matrix[M,N] b;
vector[N] c[M];
row_vector[N] d[M];
\end{Verbatim}
\end{quote}
%
Similarly, the following also have the same dump format.
%
\begin{quote}
\begin{Verbatim}
real a[P,M,N];
matrix[M,N] b[P];
vector[N] c[P,M];
row_vector[N] d[P,M];
\end{Verbatim}
\end{quote}

\section{Integer- and Real-Valued Variables}

There is no declaration in a dump file that distinguishes integer
versus continuous values.  If a value in a dump file's definition of a
variable contains a decimal point (e.g., \code{132.3}) or uses
scientific notation (e.g., \code{1.323e2}), \Stan assumes that the
values are real.

For a single value, if there is no decimal point, it may be assigned
to an \code{int} or \code{real} variable in \Stan.  An array value may
only be assigned to an \code{int} array if there is no decimal point
or scientific notation in any of the values.  This convention is
compatible with the way \R writes data.

The following dump file declares an integer value for \code{y}.
%
\begin{quote}
\begin{Verbatim} 
y <- 
2
\end{Verbatim}
\end{quote}
% 
This definition can be used for a \Stan variable \code{y} declared as
\code{real} or as \code{int}.  Assigning an integer value to a real
variable automatically promotes the integer value to a real value.

Integer values may optionally be followed by \code{L} or \code{l},
denoting long integer values.  The following example, where the type is
explicit, is equivalent to the above.
%
\begin{quote}
\begin{Verbatim} 
y <- 
2L
\end{Verbatim}
\end{quote}

The following dump file provides a real value for \code{y}.
%
\begin{quote}
\begin{Verbatim}
y <-
2.0
\end{Verbatim}
\end{quote}
%
Even though this is a round value, the occurrence of the decimal
point in the value, \code{2.0}, causes \Stan to infer that \code{y} is
real valued.  This dump file may only be used for variables \code{y}
declared as real in \Stan.

\subsection{Scientific Notation}

Numbers written in scientific notation may only be used for real
values in Stan.  R will write out the integer one million as
\code{1e+06}.  




\subsection{Infinite and Not-a-Number Values}

Stan's reader supports infinite and not-a-number values for scalar
quantities (see \refsection{real-data-type} for more information).
Both infinite and not-a-number values are supported by Stan's
dump-format readers.  
%
\begin{center}
\begin{tabular}{r||c|c}
{\it Value} & {\it Preferred Form} & {\it Alternative Forms} \\ \hline \hline
positive infinity & \code{Inf} & \code{Infinity},
\code{infinity}
\\
negative infinity & \code{-Inf} & \code{-Infinity},
\code{-infinity}
\\
not a number & \code{NaN} & 
\end{tabular}
\end{center}
%
These strings are not case sensitive, so \code{inf} may also be used
for positive infinity, or \code{NAN} for not-a-number.

\section{Quoted Variable Names}

In order to support \JAGS data files, variables may be double quoted.
For instance, the following definition is legal in a dump file.
%
\begin{quote}
\begin{Verbatim}
"y" <-
c(1,2,3)
\end{Verbatim}
\end{quote}

\section{Line Breaks}

The line breaks in a dump file are required to be consistent with
the way \R reads in data.  Both of the following declarations are
legal.
%
\begin{quote}
\begin{Verbatim}
y <- 2
y <-
3
\end{Verbatim}
\end{quote}
%
Also following \R, breaking before the assignment arrow are not
allowed, so the following is invalid.
%
\begin{quote}
\begin{Verbatim}
y
<- 2  # Syntax Error
\end{Verbatim}
\end{quote}

Lines may also be broken in the middle of sequences declared
using the \code{c(...)} notation., as well as between the comma
following a sequence definition and the dimensionality declaration.
For example, the following declaration of a $2 \times 2 \times 3$
array is valid.
%
\begin{quote}
\begin{Verbatim}
y <-
structure(c(1,2,3,
4,5,6,7,8,9,10,11,
12), .Dim = c(2,2,
3))
\end{Verbatim}
\end{quote}
%
Because there are no decimal points in the values, the resulting dump
file may be used for three-dimensional array variables declared as
\code{int} or \code{real}.

\section{BNF Grammar for Dump Data}

A more precise definition of the dump data format is provided
by the following (mildly templated) Backus-Naur form grammar.

{\small 
\begin{verbatim}
 definitions ::= definition+

 definition ::= name ("<-" | '=') value optional_semicolon

 name ::= char* 
        | ''' char* ''' 
        | '"' char* '"'

 value ::= value<int> | value<double>

 value<T> ::= T 
            | seq<T>
            | 'structure' '(' seq<T> ',' ".Dim" '=' seq<int> ')'

 seq<int> ::= int ':' int
            | cseq<int>

 seq<real> ::= cseq<real>

 cseq<T> ::= 'c' '(' vseq<T> ')'

 vseq<T> ::= T
           | T ',' vseq<T>
\end{verbatim}
}
\noindent
The template parameters \code{T} will be set to either \code{int} or
\code{real}.  Because \Stan allows promotion of integer values to real
values, an integer sequence specification in the dump data format may
be assigned to either an integer- or real-based variable in \Stan.










