
\part*{Appendices}
\addcontentsline{toc}{part}{Appendices}


\chapter{Licensing}\label{licensing.appendix}

\noindent
\Stan and its two dependent libraries, Boost and Eigen, are
distributed under liberal freedom-respecting%
%
\footnote{The link
  \url{http://www.gnu.org/philosophy/open-source-misses-the-point.html}
  leads to a discussion about terms ``open
  source'' and ``freedom respecting.''}
%
licenses approved by the Open Source Initiative.%
\footnote{See \url{http://opensource.org}.}  

In particular, the licenses for Stan and its dependent libraries have
no ``copyleft'' provisions requiring applications of \Stan to be
open source if they are redistributed.

This chapter describes the licenses for the tools that are distributed
with \Stan.  The next chapter explains some of the build tools that
are not distributed with \Stan, but are required to build and run
\Stan models.

\section{\Stan's License}

\Stan is distributed under the BSD 3-clause license (BSD New).
%
\begin{quote}
\url{http://www.opensource.org/licenses/BSD-3-Clause}
\end{quote}

\section{Boost License}

Boost is distributed under the Boost Software
License version 1.0.
%
\begin{quote}
\url{http://www.opensource.org/licenses/BSL-1.0}
\end{quote}

\section{Eigen License} 
%
Eigen is distributed under the Mozilla Public License,
version 2.
%
\begin{quote}
\url{http:/http://opensource.org/licenses/mpl-2.0}
\end{quote}

\section{Google Test License}

\Stan uses Google Test for unit testing; it is not required to compile
or execute models.  Google Test is distributed under the BSD 2-clause
license.
%
\begin{quote}
\url{http://www.opensource.org/licenses/BSD-License}
\end{quote}


\chapter{Installation and Compatibility}\label{install.appendix}

\noindent
This appendix describes the hardware and software required to run
\Stan.  The software includes \Stan and its libraries, as well as a
contemporary \Cpp compiler.  \Stan requires hardware powerful enough
to build and execute the models.  Ideally, that will be a 64-bit
computer with at least 4GB of memory and multiple processor cores.

\section{Operating System}

\Stan is written in portable \Cpp without {\Cpp}11 features, as are the
libraries on which it depends.  Therefore, \Stan should run on any machine
for which a suitable \Cpp compiler is available.  In practice, \Stan,
like the Boost and Eigen libraries on which it depends, is very hard
on the compiler and linker.

\Stan has been tested on the following operating systems.
%
\begin{itemize}
\item Linux (Debian, Ubuntu, Red Hat), 
\item Mac OS X (Snow Leopard, Lion, Mountain Lion), and
\item Windows (XP, 7, 8).
\end{itemize}
%
\Stan should work on other versions of these operating systems if
compatible \Cpp compilers can be found.  The plan is to keep up with
new versions of these operating systems and gradually phase out
testing on older versions.


\section{Step-by-Step Mac Install Instructions}

This section provides step-by-step install instructions for the Mac;
Linux and Windows sections follow.  It repeats the step-by-step
install instructions on Stan's home page at \url{http://mc-stan.org/}.

Stan has been tested on Mac OS X versions Snow Leopard, Lion, and
Mountain Lion.

\subsection{Tips for Mac Users}

\subsubsection{Finding and Opening Mac Applications and Files}

To open an application, use \code{[Command-Space]} (press both keys at
once on the keyboard) to open Spotlight, enter the application's name
in the text field, then click on the application in the pop-up menu or
\code{[Return]} if the right file or application is highlighted.

Spotlight can be used in the same way to find files or folders,
such as the default \code{Downloads} folder for web downloads.

\subsubsection{Open a Terminal for Shell Commands}

To run shell commands, open the built-in Terminal application (see the
previous subsection for details on how to find and open applications).

\subsection{Install Xcode C++ Development Environment}

The easiest (but not the only) way to install a \Cpp
development environment on a Mac is to use Apple's Xcode
development environment.

From the Xcode home page, 
%
\begin{quote}
\url{https://developer.apple.com/xcode/}
\end{quote}
%
click \code{View in Mac App Store}.

From the App Store, click \code{Install}, enter an Apple ID,
and wait for Xcode to finish installing.

Open the Xcode application, click top-level menu
\code{Preferences}, click top-row button \code{Downloads},
click button for \code{Components}, click on the \code{Install}
button to the right of the \code{Command Line Tools} entry, then
wait for it to finish installing.  

Click the top-level menu item \code{Xcode}, then click item 
\code{Quit Xcode} to quit.

To test, open the Terminal application and enter

\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> make --version
> g++ --version
\end{Verbatim}
\end{quote}
%
Verify that \code{make} is at version 3.81 or later and \code{g++}
is at 4.2.1 or later.


\subsection{Download and Unpack Stan Source}

Download the most recent version of \code{stan-2.m.p.tar.gz}
(\code{m} is the minor version and \code{p} the patch level) from
the Stan downloads list,
%
\begin{quote}
\url{https://github.com/stan-dev/stan/releases}
\end{quote}

Open the folder containing the download in the Finder
(typically, the user's top-level \code{Downloads} folder).

If the Mac OS has not automatically unpacked the \code{.tar.gz}
file into file \code{stan-2.m.p.tar},
double-click the \code{.tar.gz} file to unpack.

Double click on the \code{.tar} file to unarchive
directory \code{stan-2.m.p}.

Move the resulting directory to a location where it will not be
deleted, henceforth called \code{<stan-home>}.


\section{Step-by-Step Linux Install Instructions}

Stan has been tested on various Linux installations, including
Ubuntu, Debian, and Red Hat.

\subsection{Installing C++ Development Tools}

On Linux, \Cpp compilers and \code{make} are often installed by default.

To see if the \code{g++} compiler and \code{make} build system
are already installed, use the commands
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> g++ --version
\end{Verbatim}
\end{quote}
% 
and
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> make --version
\end{Verbatim}
\end{quote}
%

If these are at least at \code{g++} version 4.2.1 or later and \code{make}
version 3.81 or later, no additional installations are necessary.  It
may still be desirable to update the \Cpp compiler \code{g++}, because
later versions are faster.

To install the latest version of these
tools (or upgrade an older version), use the commands
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> sudo apt-get install g++ 
\end{Verbatim}
\end{quote}
%
and
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> sudo apt-get install make 
\end{Verbatim}
\end{quote}
% 
A password will likely be required by the superuser command \code{sudo}.


\subsection{Downloading and Unpacking Stan Source}

Download the most recent stable version of Stan,
\code{stan-2.m.p.tar.gz}, where \code{m} is the minor version and
\code{p} the patch level), from the Stan downloads page,
%
\begin{quote}
\url{https://github.com/stan-dev/stan/releases}
\end{quote}
%
to the directory where Stan will reside.

In a command shell, change directories to where the
tarball was downloaded, say \code{<download-dir>}, with
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> cd <download-dir>
\end{Verbatim}
\end{quote}
%
where \code{<download-dir>} is replaced with the actual path to the directory.

Then, unpack the distribution into the subdirectory
\begin{quote}
\nolinkurl{<download-dir>/stan-2.m.p}
\end{quote}
%
with
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> tar -xzf stan-2.m.p.tar.gz
\end{Verbatim}
\end{quote}



\section{Step-by-Step Windows Install Instructions}

Stan has been tested on Windows XP, Windows 7, and Windows 8.  See
Section~\refsection{cygwin} for instructions for installing for Cygwin
on Windows.

\subsection{Windows Tips}

\subsubsection{Opening a Command Shell}

To open a Windows command shell, first open the \code{Start Menu}
(usually in the lower left of the screen), select option
\code{All Programs}, then option \code{Accessories}, then
program \code{Command Prompt}.

Alternatively, enter \code{[Windows+r]} (both keys together on the
keyboard), and enter \code{cmd} into the text field that pops up in
the Run window, then press \code{[Return]} on the keyboard to run.

\subsection{Rtools C++ Development Environment}

The simplest way to install a full \Cpp build environment that will
work for Stan is to use the Rtools package designed for R developers
on Windows (even if you don't plan to use R).

First, download the latest \emph{frozen} (i.e., stable) version of
Rtools from the Rtools home page, using
%
\begin{quote}
\url{http://cran.r-project.org/bin/windows/Rtools/}
\end{quote}

Next, double click on the downloaded file to open the Rtools
install wizard, then proceed through its options.
\begin{itemize}
\item \emph{Language}: select language, click \code{Next},
\item \emph{Welcome}: click \code{Next},
\item \emph{Information}: click \code{Next},
\item \emph{Setup Location}: accept default (\Verb|c:\Rtools|), click \code{Next},
\item \emph{Select Components}: select default, \code{Package
   Authoring}, click \code{Next},
\item \emph{Select Additional Tasks}: check \code{Edit Path} and \code{Save
 Version in Registry}, click \code{Next},
\item \emph{System Path Report}: click \code{Next},
\item \emph{Ready to Install}: click \code{Next}, wait for the
  install to complete, then
\item \emph{Finish}: click \code{Finish}.
\end{itemize}

\subsection{Downloading and Unpacking Stan}

The Stan source code distributions are named
\code{stan-2.m.p.tar.gz}, where \code{m} is the minor version and
\code{p} the patch level.

Download the latest Stan source from the Stan downloads page,
%
\begin{quote}
\url{https://github.com/stan-dev/stan/releases}
\end{quote}
%
to any non-temporary folder.  (If in doubt, select \code{My Documents}
on Windows XP or \code{Documents} on Windows 7.)  

Change to the download directory (aka folder) using one of the
following commands, replacing \code{<username>} with
a Windows user name.
%
\begin{itemize}
\item \emph{Windows XP}: \ From the default starting directory, use
the following commands (quotes and all):
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> cd "My Documents"
\end{Verbatim}
\end{quote}
%
The full path (including quotes) will work from anywhere,
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> cd "c:\Documents and Settings\<username>\My Documents"
\end{Verbatim}
\end{quote}
\item \emph{Windows 7}:  \  From the default starting directory, use
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> cd Documents
\end{Verbatim}
\end{quote} 
or use the full path, including quotes, from anywhere,
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> cd "c:\Users\<username>\Documents"
\end{Verbatim}
\end{quote}
\end{itemize}
%
To verify that the downloaded Stan \code{.tar.gz} file is there,
list the directory contents using:
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> dir
\end{Verbatim}
\end{quote}

Finally, unpack the distribution using the \code{tar} command (which is
installed as part of Rtools).
%
\begin{quote}
\begin{Verbatim}[fontshape=sl,fontsize=\small]
> tar --no-same-owner -xzf stan-2.m.p.tar.gz 
\end{Verbatim}
\end{quote}
%
The \code{--no-same-owner} flag is not strictly necessary,
but it removes a bunch of irrelevant warnings.


\subsection{64-bit Cygwin Install Instructions}\label{cygwin.section}

Stan can be run under Cygwin, the Unix look-and-feel environment for
Windows.  Cygwin must have recent versions of \code{make} and
\code{g++} (part of gcc) installed.  Within a Cygwin shell, Stan
will behave as under other Unixes.

Thanks to Kevin van Horn for mailing the following instructions into
the Stan-users mailing list.  They only cover 64-bit R and 64-bit
Cygwin, but that is what you should be using for Stan anyway.

\begin{enumerate}
\item Kill all Cygwin bash shells and shut down R.
\item After installing R and Rtools, make sure that R and Rtools are
  in the \code{PATH} environment variable. My R installation directory was
  \Verb|c:\Program Files\R\R-3.0.1| and my Rtools installation
  directory was \Verb|c:\Rtools|, so I added the following to the end
  of my user \code{PATH} variable:
  \begin{itemize}
  \item \Verb|C:\Program Files\R\R-3.0.1\bin\x64|
  \item \Verb|C:\Rtools\bin|
  \item \Verb|C:\Rtools\gcc-4.6.3\bin|
  \end{itemize}
\item Now there could be a conflict between Cygwin and Rtools when
  running a bash shell under Cygwin, so I added the following lines to
  my \Verb|.bash_profile| file to remove any \code{PATH} directory
  referencing Rtools:
  \begin{Verbatim}
> TMP=`echo $PATH | /usr/bin/tr ':' '\n'                      \
                  | /usr/bin/egrep -iv '^/cygdrive/c/Rtools/' \
                  | tr '\n' ':'`
> PATH=${TMP%:}
\end{Verbatim}
(Note that the backslash characters signal that the line continues
after a return.)  This was only necessary to allow me to continue
using Cygwin.
\item Apparently there is something in \code{Rcpp} or \code{inline} or
  \code{rstan} that doesn't like \code{UNC} paths. My home directory
  was \Verb|\\server\users\kevinv| and apparently this caused my
  local R library directory to be \Verb|\server\users\kevinv\R|
  as verified by \code{.libPaths()} from the R command prompt. 

  I fixed this by copying the entire directory tree rooted at
  \Verb|\server\users\kevinv\R| over to a local directory on my workstation,
  \Verb|C:\Users\KevinV\R|, then adding the user environment variable
  \Verb|R_LIBS_USER=C:\Users\KevinV\R|. I shut down R and restarted it.
\item At this point the instructions given for installing Rstan
  finally worked.
\end{enumerate}


\section{Required Software and Tools}

The only two absolute requirements for running \Stan are the
\Stan source code (and dependent libraries) and a \Cpp compiler.

\subsection{\Stan Source}

In order to compile \Stan models, the \Stan source code is required.
The latest version of \Stan can be downloaded from the following link.
%
\begin{quote}
\url{http://mc-stan.org/}
\end{quote}
%
The \Stan source code distribution includes \Stan's source code,
documentation, build tools, unit tests, demo models, documentation and
source for the required libraries Boost and Eigen, and the source for
an optional testing library, Google Test.

\subsubsection{Boost C++ Library Source}

\Stan's parser and some of its mathematical functions and 
template metaprogramming facilities are implemented with the Boost
\Cpp Library.  
%
\begin{itemize}
\item Home: http://www.boost.org/users/license.html
\item License: Boost Software License
\item Tested Version: 1.54.0
\end{itemize}
%
The Boost source code is distributed with \Stan.


\subsubsection{Eigen Matrix and Linear Algebra Library Source}

\Stan's matrix algebra depends on the Eigen \Cpp matrix and linear
algebra library.  
%
\begin{itemize}
\item Home: \url{http://eigen.tuxfamily.org}
\item License: Mozilla Public License, version 2.0
\item Tested Version: 3.2.0
\end{itemize}
%
The Eigen source code is distributed with \Stan.


\subsection{\Cpp Compiler}

Compiling \Stan models requires a \Cpp compiler.  \Stan has been
primarily developed with \clang and \gpp and no promises are made for
other compilers.  The full set of compilers for which \Stan has been
tested is
%
\begin{itemize}
%
\item \gpp
\\
Tested Versions: Mac 4.2.1, 4.6, Linux 4.4--4.7, Windows 4.6.3
\\
Home: \url{http://gcc.gnu.org/}
\\
License: GPL3+
%
\item \clang, Mac 2.9--3.1, Linux 2.9--3.1
\\
Home: \url{http://clang.llvm.org/}
\\
License: BSD
%
\item mingw-64, version 2.0 (Windows 7, cross-compiled from Debian Linux)
%
\item Intel \Cpp, Linux version 12.1.3
%
\end{itemize}
%

\subsubsection{\Cpp-11 Support} 

Stan 2.0 does not support \Cpp-11.  The remaining incompatibility with
the parser will be included soon after Stan 2.0 is released.  This
will include support for the latest versions of \code{g++} and
\code{clang++}.


\section{Optional Components for Developers}

\Stan is developed using the following set of tools.  The various
command examples in this manual have assumed they can be found on
the command path.  The makefile allows precise locations to be plugged
in. 

\subsection{GNU Make Build Tool}

\Stan automates the build, test, documentation, and deployment tasks
using scripts in the form of makefiles to run with GNU Make.
%
\begin{itemize}
\item Home: \url{http://www.gnu.org/software/make}
\item License: GPLv3+
\item Tested Versions: 3.81 (Mac OS X), 3.79 (Windows 7)
\end{itemize}
%


\subsection{Doxygen Documentation Generator}

\Stan's API documentation is generated using the Doxygen Tool.
%
\begin{itemize}
\item Home: \url{http://www.stack.nl/~dimitri/doxygen/index.html}
\item License: GPL2
\item Tested Version(s): Mac OS X 1.8.2, Windows 1.8.2
\end{itemize}


\subsection{Git Version Control System}

\Stan uses the Git version control system for its software, libraries,
and documentations.  Git is required to interact with the most recent
versions of code in the version control repository.
% 
\begin{itemize}
\item Home: \url{http://git-scm.com/}
\item License: GPL2
\item Tested Version(s): Mac version 1.7.8.4, Windows version 1.7.9
\end{itemize}


\subsubsection{Google Test C++ Testing Framework}

\Stan's unit testing is based on the Google's googletest \Cpp testing
framework.  
%
\begin{itemize}
\item
Home: \url{http://code.google.com/p/googletest/}
\item
License: BSD
\item
Tested Version(s): 1.6.0
\end{itemize}
%
The Google Test framework is distributed with \Stan.


\section{Tips for Mac OS X}

\subsection{Install Xcode}

Apple's Xcode contains both the \clang and \gpp compilers and make, all of the tools 
needed to work with \Stan as a user. 
The version of Xcode to install depends on the
version of Mac OS X.  

\subsubsection{Official Apple Xcode Distribution}

Xcode 4 may be downloaded for free for Mac OS X 10.7 (``Lion'') or
later directly from Apple:

\begin{quote}
Xcode 4: \url{https://developer.apple.com/xcode/}
\end{quote}

Once you've installed Xcode, you need to start it, then open
menu option \code{Xcode}, select \code{Preferences}, then click on the
\code{Downloads} icon and then click on the \code{Install} button next
to the option labeled ``Command Line Tools.''

At this point, you should have the make system \code{make} and the two
\Cpp compilers/linkers, \gpp and \clang, installed.  This is all you
need to run \Stan.  Xcode will also install the \code{git} version
control system at this point.

\subsubsection{Alternative, GCC-Only Installer}

A stripped down installer for just the GCC package, including the \Cpp
compilers \code{g++} and \code{clang++}, available for 
Mac OS X 10.6 (``Snow Leopard'') or later,
%
\begin{quote}
\url{https://github.com/kennethreitz/osx-gcc-installer/}
\end{quote}
%
The fill list of tools in this distribution is available at:
%
\begin{quote}
\url{http://www.opensource.apple.com/release/developer-tools-41/}
\end{quote}



\subsection{More Recent Compilers}

Alternative compilers to those distributed by Apple as part of Xcode
are available at the following locations.

\subsubsection{Homebrew}

One way to get pre-built binaries for Mac OS X is to use Homebrew,
which is available from the following link.
\begin{quote}
\url{http://mxcl.github.com/homebrew/}
\end{quote}

\subsubsection{MacPorts}

MacPorts hosts recent versions of compilers for the Macintosh.
%
\begin{quote}
\url{https://distfiles.macports.org/MacPorts/}
\end{quote}
%
After finding the appropriate \code{.dmg} file, clicking on it, then
double clicking on the resulting \code{.pkg} file, and clicking
through some more menus, the following will need to be entered from a
terminal window to install it.
%
\begin{quote}
\code{> sudo port install {\slshape gccVersion}}
\end{quote}
%
In this command, {\slshape gccVersion} is the name of a compiler
version, such as \code{g++=mp-4.6}, for version 4.6.  Errors may arise
during the install such as the following.
%
\begin{quote}\small\tt
  Error: Target org.macports.activate returned: Image error:
  /opt/local/include/gmp.h already exists and does not belong to a
  registered port.  Unable to activate port gmp. Use 'port -f activate
  gmp' to force the activation.
\end{quote}
%
This issue can be resolved by running the following command.
%
\begin{quote}
\code{> sudo port -f activate gmp}
\end{quote}
%


\subsection{Git Installer}

A standalone version of Git for Mac OS X is available from the
following site. 
%
\begin{quote}
\url{http://code.google.com/p/git-osx-installer/}
\end{quote}
%
Although (at the time of this writing) there were only versions listed
up to OS X version ``Snow Leopard,'' they work on ``Lion.''

\subsection{\LaTeX\ Typesetting Package}

\Stan uses the \LaTeX\ typesetting package for generating manuals,
talks, and other materials (Doxygen is used for API documentation; see
below).  The first step is to download the MacTeX \code{.mpkg} file
from the following URL [warning: the download is approximately 2GB and
the installation approximately 3.5GB].
%
\begin{quote}
\url{http://www.tug.org/mactex/2011/}
\end{quote}
%
Once it is downloaded, just click on the \code{.mpkg} file and then
follow the installer instructions.  The installer will add the command
to the \code{PATH} environment variable so that the \code{pdflatex}
used by \Stan is available from the command line.


\subsection{Lucida Console Font}

A free TrueType version of Lucida Console for the Mac is available
at the following URL.
%
\begin{quote}
\url{http://www.fontpalace.com/font-details/Lucida+Console/}
\end{quote}
%
Download the \code{.ttf} file, then click on it to install.  It
will then be available as a preference in the Mac terminal application.

\subsection{Doxygen API Documentation}

\Stan's API documentation is generated using the Doxygen tool.   This
tool is available from
%
\begin{quote}
\url{http://www.doxygen.org}
\end{quote}
%
Select the \code{Download} link from the second of the right-hand side
navigation bars, then select the binary distribution \code{.dmg} file
for Mac OS X.  Clicking on the \code{.dmg} file opens the finder with
a view of the unpacked Doxygen executable.  Just drag the Doxygen icon
into the Applications folder (or wherever you want to keep it).  Then
add the path to the Doxygen executable, 
%
\begin{quote}
\url{/Applications/Doxygen.app/Contents/Resources/doxygen}
\end{quote}
%
to the system \code{PATH} environment variable.  You can do add to the
\code{PATH} environment by adding this line to the end of the
top-level \Verb|~/.profile| file.  
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
export PATH=/Applications/Doxygen.app/Contents/Resources:$PATH
\end{Verbatim}
\end{quote}
%
The next shell started will then be able to find the \code{doxygen} command.


\section{Tips for Windows}

\subsection{Install Rtools}

The easiest way to get a complete \Cpp build environment on Windows is
to install the most recent version of Rtools.  

The latest version verified to work with \Stan is Rtools 2.15.  Rtools
2.15 includes the \gpp 4.6.3 (pre-release) compiler and many other
useful command line tools including many Unix commands, such as the
following.
%
\begin{quote}
\tt basename, cat, cmp, comm, cp, cut, date,
diff, du, echo, expr, gzip, ls, make, makeinfo, mkdir, mv, rm, rsync,
sed, sh, sort, tar, texindex, touch, uniq
\end{quote}

Rtools can be downloaded from the following location.
%
\begin{quote}
  \url{http://cran.r-project.org/bin/windows/Rtools/}
\end{quote}
%
Install it using the Windows installer.  Allow it to edit the
\code{PATH} environment variable so that commands are available from
the command tool.

To verify the installation was successful, open a command window by
selecting the following menu items.
%
\begin{quote}
  \code{Start} 
  $\rightarrow$ Accessories 
  $\rightarrow$ Command Prompt
\end{quote}
%
To verify that \gpp is installed, use the following command.
%
\begin{quote}
  \Verb|> g++ -v|
\end{quote}
%
This should report version information for \gpp.  Next, verify that
\code{make} is installed with the following command.
%
\begin{quote}
  \Verb|> make -v|
\end{quote}
%
This should print version information for make.

\subsection{Install Git}

There are a number of Git clients for Windows that will work.  The
official Git installer for Windows can be found at the following
location.
%
\begin{quote}
\url{http://code.google.com/p/msysgit/downloads}
\end{quote}
%
Select the latest full installer and install it. 

\chapter{Stan for Users of BUGS}\label{stan-for-bugs.appendix}

From the outside, Stan and \BUGS%
%
\footnote{Except where otherwise noted, we use ``\BUGS'' to refer to
  Win\BUGS, Open\BUGS, and \JAGS, indiscriminately.}
%
are similar --- they use statistically-themed modeling languages
(which are similar but with some differences; see below), they can be
called from R, running some specified number of chains to some
specified length, producing posterior simulations that can be assessed
using standard convergence diagnostics.  This is not a coincidence:
in designing Stan, we wanted to keep many of the useful features of
Bugs.

To start, take a look at the files of translated \BUGS models at
\url{http://mc-stan.org/}.  These are 40 or so models from the \BUGS
example volumes, all translated and tested (to provide the same
answers as \BUGS) in Stan.  For any particular model you want to fit,
you can look for similar structures in these examples.

\section{Some Differences in How BUGS and Stan Work}

\begin{itemize}
\item \BUGS is interpreted; Stan is compiled in two steps, first a
  model is is translated to templated C++ and then to a
  platform-specific executable.  \Stan, unlike \BUGS, allows the user
  to directly program in C++, but we do not describe how to do this in
  this Stan manual (see the getting started with \Cpp section of
  \url{http://mc-stan.org} for more information on using Stan directly
  from \Cpp). 
\item \BUGS performs \MCMC updating one scalar parameter at a time
  (with some exceptions such as \JAGS's implementation of regression
  and generalized linear models and some conjugate multivariate
  parameters), using conditional distributions (Gibbs sampling) where
  possible and otherwise using adaptive rejection sampling, slice
  sampling, and Metropolis jumping.  \BUGS figures out the dependence
  structure of the joint distribution as specified in its modeling
  language and uses this information to compute only what it needs at
  each step.  Stan moves in the entire space of all the parameters
  using Hamiltonian Monte Carlo (more precisely, the no-U-turn
  sampler), thus avoiding some difficulties that occur with
  one-dimension-at-a-time sampling in high dimensions but at the cost
  of requiring the computation of the entire log density at each step.
\item \BUGS tunes its adaptive jumping (if necessary) during its
  warmup phase (traditionally referred to as "burn-in").  Stan uses
  its warmup phase to tune the no-U-turn sampler (\NUTS).
\item The \BUGS modeling language is not directly executable.  Rather,
  \BUGS parses its model to determine the posterior density and then
  decides on a sampling scheme.  In contrast, the statements in a Stan
  model are directly executable: they translate exactly into C++ code
  that is used to compute the log posterior density (which in turn is
  used to compute the gradient).
\item In \BUGS, the order in which statements are written does not
  matter.  They are executed according to the directed graphical model
  so that variables are always defined when needed.  A side effect of
  the direct execution of \Stan's modeling language is that statements
  execute in the order in which they are written.  For instance, the
  following \Stan program, which sets \code{mu} before using it to
  sample \code{y}.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
mu <- a + b * x;
y ~ normal(mu,sigma);
\end{Verbatim}
\end{quote}
%
It translates to the following \Cpp code.
%
\begin{quote}
\begin{Verbatim} 
mu = a + b * x; 
lp += normal_log(mu,sigma);
\end{Verbatim}
\end{quote} 
%
Contrast this with the \Stan program
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
y ~ normal(mu,sigma)
mu <- a + b * x
\end{Verbatim}
\end{quote}
%
This program is well formed, but is almost certainly  
a coding error, because it attempts to use \code{mu} before 
it is set. It translates to the following \Cpp code.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
lp += normal_log(mu,sigma);
mu = a + b * x;
\end{Verbatim}
\end{quote}
%
The direct translation to the imperative language of \Cpp code
highlights the potential error of using \code{mu} in the first
statement.
\\[8pt]
To trap these kinds of errors, variables are initialized to the
special not-a-number (\code{NaN}) value.  If \code{NaN} is passed to a
log probability function, it will raise a domain exception, which will
in turn be reported by the sampler.  The sampler will reject the
sample out of hand as if it had zero probability.
%
\item Stan uses its own \Cpp algorithmic differentiation packages to
  compute the gradient of the log density (up to a proportion).
  Gradients are required during the Hamiltonian dynamics simulations
  within the leapfrog algorithm of the Hamiltonian Monte Carlo and
  \NUTS samplers.  \BUGS computes the log density but not its
  gradient.
\item Both \BUGS and Stan are semi-automatic in that they run by
  themselves with no outside tuning required. Nevertheless, the user
  needs to pick the number of chains and number of iterations per
  chain.  We usually pick 4 chains and start with 10 iterations per
  chain (to make sure there are no major bugs and to approximately
  check the timing), then go to 100, 1000, or more iterations as
  necessary.  Compared to Gibbs or Metropolis, Hamiltonian Monte Carlo
  can take longer per iteration (as it typically takes many "leapfrog
  steps" within each iteration), but the iterations typically have lower
  autocorrelation.  So Stan might work fine with 1000 iterations in an
  example where \BUGS would require 100,000 for good mixing.  We 
  recommend monitoring potential scale reduction statistics ($\hat{R}$)
  and the effective sample size to judge when to stop (stopping when
  $\hat{R}$ values do not counter-indicate convergence and when enough
  effective samples have been collected).
\item WinBUGS is closed source.  OpenBUGS and JAGS are both licensed
  under the Gnu Public License (GPL), otherwise known as copyleft due
  to the restrictions it places on derivative works.  Stan is licensed
  under the much more liberal new BSD license.
\item Like WinBUGS, OpenBUGS and JAGS, Stan can be run directly from
  the command line or through R (Python and MATLAB interfaces are in
  the works)
\item Like OpenBUGS and JAGS, Stan can be run on Linux, Mac, and
  Windows platforms.
\end{itemize}

\section{Some Differences in the Modeling Languages}

\begin{itemize}
\item The \BUGS modeling language follows an R-like syntax in which
  line breaks are meaningful.  Stan follows the rules of C, in which
  line breaks are equivalent to spaces, and each statement ends in a
  semicolon.  For example:
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
y ~ normal(mu, sigma);
\end{Verbatim}
\end{quote}
%
and
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
for (i in 1:n) y[i] ~ normal(mu, sigma);
\end{Verbatim}
\end{quote}
%
Or, equivalently (recall that a line break is just another form of whitespace),
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
for (i in 1:n)
  y[i] ~ normal(mu, sigma);
\end{Verbatim}
\end{quote}
%
and also equivalently, 
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
for (i in 1:n) {
  y[i] ~ normal(mu, sigma);
}
\end{Verbatim}
\end{quote}
%
There's a semicolon after the model statement but not after the
brackets indicating the body of the for loop.
%
\item Another C thing: In Stan, variables can have names constructed
  using letters, numbers, and the underscore (\code{\_}) symbol, but
  nothing else (and a variable name cannot begin with a number).
  \BUGS variables can also include the dot, or period (\code{.}) symbol.
%
\item In Stan, the second argument to the "normal" function is the
  standard deviation (i.e., the scale), not the variance (as in {\it
    Bayesian Data Analysis}) and not the inverse-variance (i.e.,
  precision) (as in \BUGS).  Thus a normal with mean 1 and standard
  deviation 2 is \code{normal(1,2)}, not \code{normal(1,4)} or
  \code{normal(1,0.25)}.
%
\item Similarly, the second argument to the "multivariate normal" 
  function is the covariance matrix and not the inverse covariance matrix
  (i.e., the precision matrix) (as in \BUGS). The same is true for
  the "multivariate student" distribution.
%  
\item
The distributions have slightly different names:
%
\begin{quote}
\begin{tabular}{l|l}
{\it BUGS} & {\it Stan} \\ \hline \hline
\code{dnorm} & \code{normal} \\
\code{dbinom} & \code{binomial} \\
\code{dpois} & \code{poisson} \\
$\vdots$ & $\vdots$
\end{tabular}
\end{quote}
%
\item Stan, unlike \BUGS, allows intermediate quantities, in the form
  of local variables, to be reassigned.  For example, the following is
  legal and meaningful (if possibly inefficient) Stan code.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
{
  total <- 0;
  for (i in 1:n){
    theta[i] ~ normal(total, sigma);
    total <- total + theta[i];
  }
}
\end{Verbatim}
\end{quote}
%
In \BUGS, the above model would not be legal because the variable
\code{total} is defined more than once.  But in Stan, the loop is
executed in order, so \code{total} is overwritten in each step.  
%
\item Stan uses explicit declarations.  Variables are declared with
  base type integer or real, and vectors, matrices, and arrays have
  specified dimensions.  When variables are bounded, we give that
  information also.  For data and transformed parameters, the bounds
  are used for error checking.  For parameters, the constraints
  are critical to sampling as they determine the geometry over which
  the Hamiltonian is simulated.  
  \\[6pt]
  Variables can be declared as data, transformed data, parameters, transformed
  parameters, or generated quantities.  They can also be declared as
  local variables within blocks.  For more information, see
  the part of this manual devoted to the Stan programming language and
  examine at the example models.
%
\item Stan allows all sorts of tricks with vector and matrix
  operations which can make Stan models more compact.  For example,
  arguments to probability functions may be vectorized,%
%
\footnote{Most distributions have been vectorized, but currently the
truncated versions may not exist and may not be vectorized.}
%
allowing
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
for (i in 1:n) 
  y[i] ~ normal(mu[i], sigma[i]);
\end{Verbatim}
\end{quote}
%
to be expressed more compactly as 
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
y ~ normal(mu,sigma);
\end{Verbatim}
\end{quote}
%
The vectorized form is also more efficient because Stan can unfold the
computation of the chain rule during algorithmic differentiation.
%
\item Stan also allows for arrays of vectors and matrices.
  For example, in a hierarchical model might have a vector of \code{K}
  parameters for each of \code{J} groups; this can be declared using
\begin{quote}
\begin{Verbatim}[fontsize=\small]
vector[K] theta[J];
\end{Verbatim}
\end{quote}
%
Then \code{theta[j]} is an expression denoting a \code{K}-vector and
may be used in the code just like any other vector variable.
\\[6pt]
An alternative encoding would be with a two-dimensional array, as in
\begin{quote}
\begin{Verbatim}[fontsize=\small]
real theta[J,K];
\end{Verbatim}
\end{quote}
%
The vector version can have some advantages, both in convenience and
in computational speed for some operations.
\\[6pt]
A third encoding would use a matrix:
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
matrix[J,K] theta;
\end{Verbatim}
\end{quote}
%
but in this case, \code{theta[j]} is a row vector, not a vector, and
accessing it as a vector is less efficient than with an array of
vectors.  The transposition operator, as in \code{theta[j]'}, may be
used to convert the row vector \code{theta[j]} to a (column) vector.
Column vector and row vector types are not interchangeable everywhere
in Stan; see the function signature declarations in the programming
language section of this manual.
%
\item Stan supports general conditional statements using a standard
  if-else syntax.  For example, a zero-inflated (or -deflated) Poisson
  mixture model of the form defined by \citet{Lambert:1992} 
  may be defined as follows, where there is a probability $\theta$ of
  drawing a zero, and a probability $1 - \theta$ of drawing from
  $\distro{Poisson}(\lambda)$.  The probability function is thus
\[
p(y_n|\theta,\lambda) 
= 
\left\{
\begin{array}{ll}
\theta + (1 - \theta) \times \distro{Poisson}(0|\lambda) & \mbox{ if } y_n = 0, \mbox{ and}
\\[3pt]
(1-\theta) \times \distro{Poisson}(y_n|\lambda) & \mbox{ if } y_n > 0.
\end{array}
\right.
\] 
%
The log probability function can be implemented directly in Stan as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
data {
  int<lower=0> N;
  int<lower=0> y[N];
  ...
}
model {
  for (n in 1:N) {
    if (y[n] == 0)
      increment_log_prob(log_sum_exp(bernoulli_log(1,theta),
                                     bernoulli_log(0,theta) 
                                     + poisson_log(y[n],lambda)));
    else
      increment_log_prob(bernoulli_Log(0,theta)
                         + poisson_log(y[n],lambda));
  }
  ...
}
\end{Verbatim}
\end{quote}
%
The \code{log\_sum\_exp(lp1,lp2)} function adds the log probabilities
on the linear scale; it is defined to be equal to \code{log(exp(lp1) +
  exp(lp2))}, but is more arithmetically stable.
%
\item Stan supports general while loops using a standard syntax.  
While loops give Stan full Turing equivalent computational power.
They are useful for defining iterative functions with complex
termination conditions.  As an illustration of their syntax,
the for-loop
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
model {
    ....
    for (n in 1:N) {
        ... do something with n ....
    }
}
\end{Verbatim}
\end{quote}
%
may be recoded using the following while loop.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
model {
    int n;
    ...
    n <- 1;
    while (n <= N) {
        ... do something with n ...
        n <- n + 1;
    }
}
\end{Verbatim}
\end{quote}
%


\end{itemize}


\section{Some Differences in the Statistical Models that are Allowed}

\begin{itemize}
\item Stan does not yet support sampling discrete parameters (discrete
  data is supported).  We plan to implement discrete sampling using a
  combination of Gibbs and slice sampling but we haven't done so yet.
\item Stan has some distributions on covariance matrices that do not
  exist in \BUGS, including a uniform distribution over correlation
  matrices which may be rescaled, and the priors based on C-vines
  defined in \citep{LewandowskiKurowickaJoe:2009}.  In particular, the
  Lewandowski et al.\ prior allows the correlation matrix to be shrunk
  toward the unit matrix while the scales are given independent priors.
\item In \BUGS you need to define all variables.  In Stan, if you
  declare but don't define a parameter it implicitly has a flat prior
  (on the scale in which the parameter is defined).  For example, if
  you have a parameter \code{p} declared as 
\begin{quote}
\begin{Verbatim}[fontsize=\small]
real<lower=0,upper=1> p;
\end{Verbatim}
\end{quote}
%
and then have no sampling statement for \code{p} in the \code{model}
block, then you are implicitly assigning a uniform $[0,1]$ prior on
\code{p}.
On the other hand, if you have a parameter \code{theta} declared with
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
real theta;
\end{Verbatim}
\end{quote}
%
and have no sampling statement for \code{theta} in the
\code{model} block, 
 then you are implicitly assigning an improper uniform prior
on $(-\infty,\infty)$ to \code{theta}.  
%
% Then if
% you define a transformed parameter \code{p} using
% \begin{quote}
% \begin{Verbatim} 
% p <- invlogit(theta);
% \end{Verbatim}
% \end{quote}
% %
% then you get a $\distro{Beta}(0,0)$ on \code{p}.
% then you are implicitly assigning an improper uniform
% (-infinity, infinity) prior on theta, which corresponds to a Beta
% (0,0) prior on p.  You could also assign this latter prior directly by
% defining p as the parameter and then writing the following within the
% model: p ~ beta (0, 0);
\item \BUGS models are always proper (being constructed as a product
  of proper marginal and conditional densities).  Stan models can be
  improper.  Here is the simplest improper Stan model: 
\begin{quote}
\begin{Verbatim}[fontsize=\small]
parameters {
  real theta;
} 
model { }
\end{Verbatim}
\end{quote}
% \item You can also define some improper models in \BUGS directly, for
%   example, \Verb|p ~ beta (0, 0);| Remember how Stan works:
%   lines in the model are executables that correspond directly to
%   factors in the posterior density.  So you can define beta(0,0), it's
%   simply a mathematical function.  Stan doesn't "care" if it has a
%   finite integral.
\item Although parameters in Stan models may have improper priors, we
  do not want improper \emph{posterior} distributions, as we are trying to
  use these distributions for Bayesian inference.  There is no general
  way to check if a posterior distribution is improper.  But if all
  the priors are proper, the posterior will be proper also.
\item
  As noted earlier, each statement in a Stan model is directly translated into the \Cpp code for computing the log posterior.  Thus, for example, the following pair of statements is legal in a Stan model:
\begin{quote}
\begin{Verbatim}[fontsize=\small]
y ~ normal(0,1);
y ~ normal(2,3);
\end{Verbatim}
\end{quote}
%
The second line here does \emph{not} simply overwrite the first;
rather, \emph{both} statements contribute to the density function that
is evaluated.  The above two lines have the effect of including the
product, $\distro{Norm}(y|0,1) \times \distro{Norm}(y|2,3)$, into the
density function.
\\[6pt] 
For a perhaps more confusing example, consider the following two lines in a Stan model:
\begin{quote}
\begin{Verbatim}[fontsize=\small]
x ~ normal(0.8*y, sigma);
y ~ normal(0.8*x, sigma);
\end{Verbatim}
\end{quote}
%
At first, this might look like a joint normal distribution with a
correlation of 0.8.  But it is not.  The above are \emph{not}
interpreted as conditional entities; rather, they are factors in the
joint density.  Multiplying them gives, $\distro{Norm}(x|0.8y,\sigma)
\times \distro{Norm}(y|0.8x,\sigma)$, which is what it is (you can
work out the algebra) but it is not the joint distribution where the
conditionals have regressions with slope 0.8.
%
\item With censoring and truncation, Stan uses the censored-data or
  truncated-data likelihood---this is not always done in \BUGS.  All
  of the approaches to censoring and truncation discussed in
  \citep{GelmanCarlinSternRubin:2003} and \citep{GelmanHill:2007} may
  be implemented in Stan directly as written.
%
\item Stan, like \BUGS, can benefit from human intervention in the
  form of reparameterization.  More on this topic to come.
  % For example, with the 8 schools: . . .
\end{itemize}

\section{Some Differences when Running from R}

\begin{itemize}

\item Stan can be set up from within R using two lines of code.
  Follow the instructions for running Stan from R on
  \url{http://mc-stan.org/}.  You don't need to separately download
  Stan and RStan.  Installing RStan will automatically set up Stan.
  When RStan moves to CRAN, it will get even easier.
\item In practice we typically run the same Stan model repeatedly.  If
  you pass RStan the result of a previously fitted model the model will 
  not need be recompiled. An example is given on the running
  Stan from R pages available from \code{http://mc-stan.org/}.
\item When you run Stan, it saves various conditions including
  starting values, some control variables for the tuning and running
  of the no-U-turn sampler, and the initial random seed. You can
  specify these values in the Stan call and thus achieve exact
  replication if desired.  (This can be useful for debugging.)
\item When running \BUGS from R, you need to send exactly the data
  that the model needs.  When running RStan, you can include extra
  data, which can be helpful when playing around with models.  For
  example, if you remove a variable \code{x} from the model, you can keep
  it in the data sent from R, thus allowing you to quickly alter the
  Stan model without having to also change the calling information in
  your R script.
\item As in R2WinBUGS and R2jags, after running the Stan model, you
  can quickly summarize using \code{plot()} and \code{print()}.  You
  can access the simulations themselves using various extractor
  functions, as described in the RStan documentation.  
\item Various information about the sampler, such as number of
  leapfrog steps, log probability, and step size, is available through
  extractor functions.   These can be useful for understanding what is
  going wrong when the algorithm is slow to converge.
\end{itemize}

\section{The Stan Community}

\begin{itemize}
\item Stan, like WinBUGS, OpenBUGS, and JAGS, has an active community,
  which you can access via the user's mailing list and the developer's
  mailing list; see \code{http://mc-stan.org/} for information on
  subscribing and posting and to look at archives.
\end{itemize}


\chapter{Stan Program Style Guide}

\noindent
This appendix describes the preferred style for laying out Stan
models. These are not rules of the language, but simply
recommendations for laying out programs in a text editor.  Although
these recommendations may seem arbitrary, they are similar to those of
many teams for many programming languages.  Like rules for typesetting
text, the goal is to achieve readability without wasting white space
either vertically or horizontally.

\section{Choose a Consistent Style}

The most important point of style is consistency.  Consistent coding
style makes it easier to read not only a single program, but multiple
programs.  So when departing from this style guide, the number one
recommendation is to do so consistently.

\section{Line Length}

Line lengths should not exceed 80 characters.%
%
\footnote{Even 80 characters may be too many for rendering in print;
  for instance, in this manual, the number of code characters that fit
  on a line is about 65.}
%
This is a typical recommendation for many programming language style
guides because it makes it easier to lay out text edit windows side by
side and to view the code on the web without wrapping, easier to view
diffs from version control, etc.  About the only thing that is
sacrificed is laying out expressions on a single line.

\section{File Extensions}

The recommended file extension for Stan model files is \code{.stan}.  
For Stan data dump files, the recommended extension is \code{.R}, or
more informatively, \code{.data.R}.

\section{Variable Naming}

The recommended variable naming is to follow C/\Cpp naming
conventions, in which variables are lowercase, with the underscore
character (\Verb|_|) used as a separator.  Thus it is preferred to use
\Verb|sigma_y|, rather than the run together \Verb|sigmay|, camel-case
\Verb|sigmaY|, or capitalized camel-case \Verb|SigmaY|.  Even matrix
variables should be lowercased.

The exception to the lowercasing recommendation, which also follows
the C/\Cpp conventions, is for size constants, for which the
recommended form is a single uppercase letter.  The reason for this is
that it allows the loop variables to match.  So loops over the indices of
an $M \times N$ matrix $a$ would look as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
for (m in 1:M)
  for (n in 1:N)
     a[m,n] = ...
\end{Verbatim}
\end{quote}


\section{Local Variable Scope}

Declaring local variables in the block in which they are used aids in
understanding programs because it cuts down on the amount of text
scanning or memory required to reunite the declaration and definition.

The following Stan program corresponds to a direct translation of a
BUGS model, which uses a different element of \code{mu} in each
iteration.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
model {
  real mu[N];
  for (n in 1:N) {
    mu[n] <- alpha * x[n] + beta;
    y[n] ~ normal(mu[n],sigma);
  }
}
\end{Verbatim}
\end{quote}
%
Because variables can be reused in Stan and because they should be
declared locally for clarity, this model should be recoded as follows.
%
\begin{quote}
\begin{Verbatim} 
model {
  for (n in 1:N) {
    real mu;
    mu <- alpha * x[n] + beta;
    y[n] ~ normal(mu,sigma);
  }
}
\end{Verbatim}
\end{quote}
% 
The local variable can be eliminated altogether, as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
model {
  for (n in 1:N)
    y[n] ~ normal(alpha * x[n] + beta, sigma);
}
\end{Verbatim}
\end{quote}
%
There is unlikely to be any measurable efficiency difference
between the last two implementations, but both should be a bit
more efficient than the BUGS translation.

\subsubsection{Scope of Compound Structures with Componentwise Assignment}

In the case of local variables for compound structures, such as
arrays, vectors, or matrices, if they are built up component by
component rather than in large chunks, it can be more efficient to
declare a local variable for the structure outside of the block
in which it is used.  This allows it to be allocated once and then
reused.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
model {
  vector[K] mu;
  for (n in 1:N) {
    for (k in 1:K) 
      mu[k] <- ...;
    y[n] ~ multi_normal(mu,Sigma);
}
\end{Verbatim}
\end{quote}
%
In this case, the vector \code{mu} will be allocated
outside of both loops, and used a total of \code{N} times.

\section{Parentheses and Brackets}

\subsection{Optional Parentheses for Single-Statement Blocks}

Single-statement blocks can be rendered in one of two ways.  The fully
explicit bracketed way is as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
for (n in 1:N) {
  y[n] ~ normal(mu,1);
}
\end{Verbatim}
\end{quote}
%
The following statement without brackets has the same effect.
%
\begin{quote}
\begin{Verbatim}  
for (n in 1:N)
  y[n] ~ normal(mu,1);
\end{Verbatim}
\end{quote}
%  
Single-statement blocks can also be written on a single line, as
in the following example.
%
\begin{quote}
\begin{Verbatim} 
for (n in 1:N) y[n] ~ normal(mu,1);
\end{Verbatim}
\end{quote}
%
These can be much harder to read than the first example. Only use this
style if the statement is very simple, as in this example.  Unless
there are many similar cases, it's almost always clearer to put
each sampling statement on its own line.

Conditional and looping statements may also be written without brackets.

The use of for loops without brackets can be dangerous.  For instance,
consider this program.
%
\begin{quote}
\begin{Verbatim}  
for (n in 1:N)
  z[n] ~ normal(nu,1);
  y[n] ~ normal(mu,1);
\end{Verbatim}
\end{quote}
%
Because Stan ignores whitespace and the parser completes a statement
as eagerly as possible (just as in C++), the previous program is
equivalent to the following program.
%
\begin{quote}
\begin{Verbatim}  
for (n in 1:N) {
  z[n] ~ normal(nu,1);
}
y[n] ~ normal(mu,1);
\end{Verbatim}
\end{quote}
%


\subsection{Parentheses in Nested Operator Expressions}

The preferred style for operators minimizes parentheses.  This reduces
clutter in code that can actually make it harder to read expressions.
For example, the expression \code{a~+~b~*~c} is preferred to the
equivalent \code{a~+~(b~*~c)} or \code{(a~+~(b~*~c))}.  The operator
precedences and associativities are given in
\reffigure{operator-precedence}.

Similarly, comparison operators can usually be written with minimal
bracketing, with the form \code{y[n] > 0 || x[n] != 0} preferred to
the bracketed form \code{(y[n] > 0) || (x[n] != 0)}.  

\subsection{No Open Brackets on Own Line}

Vertical space is valuable as it controls how much of a program you
can see.  The preferred Stan style is as shown in the previous
section, not as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
for (n in 1:N) 
{
  y[n] ~ normal(mu,1);
}
\end{Verbatim}
\end{quote}
%
This also goes for parameters blocks, transformed data blocks, 
which should look as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
transformed parameters {
  real sigma;
  ...
}
\end{Verbatim}
\end{quote}
%


\section{Conditionals}

Stan supports the full \Cpp-style conditional syntax,
allowing real or integer values to act as conditions, as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
real x;
...
if (x) {
   // executes if x not equal to 0
   ...
}
\end{Verbatim}
\end{quote}
%

\subsection{Explicit Comparisons of Non-Boolean Conditions}

The preferred form is to write the condition out explicitly for
integer or real values that are not produced as the result of a
comparison or boolean operation, as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
if (x != 0) ...
\end{Verbatim}
\end{quote}

% \subsection{Functional \code{ifelse} versus Conditionals}
% don't actually want this until we get proper short-circuiting conditionals!

% If possible, the functional form \code{ifelse} is preferred to full
% conditionals.  For example, the following block
% %
% \begin{quote}
% \begin{Verbatim}
% if (cond)
%   x <- foo(y);
% else 
%   x <- bar(z);
% \end{Verbatim}
% \end{quote}
% %
% should be recoded as follows.
% %
% \begin{quote}
% \begin{Verbatim}
% x <- ifelse(foo(y), bar(z));
% \end{Verbatim}
% \end{quote}

\section{White Space}

Stan allows spaces between elements of a program.  The white space
characters allowed in Stan programs include the space (ASCII
\code{0x20}), line feed (ASCII \code{0x0A}), carriage return
(\code{0x0D}), and tab (\code{0x09}).  Stan treats all whitespace
characters interchangeably, with any sequence of whitespace characters
being syntactically equivalent to a single space character.
Nevertheless, effective use of whitespace is the key to good program
layout.


\subsection{Line Breaks Between Statements and Declarations}

It is dispreferred to have multiple statements or declarations on the
same line, as in the following example.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
transformed parameters {
  real mu_centered;  real sigma;
  mu <- (mu_raw - mean_mu_raw);    sigma <- pow(tau,-2);
}
\end{Verbatim}
\end{quote}
%
These should be broken into four separate lines.

\subsection{No Tabs}

Stan programs should not contain tab characters.  They are legal and
may be used anywhere other whitespace occurs.  Using tabs to layout a
program is highly unportable because the number of spaces
represented by a single tab character varies depending on which
program is doing the rendering and how it is configured.  

\subsection{Two-Character Indents}

Stan has standardized on two space characters of indentation, which is
the standard convention for C/C++ code.  Another sensible choice is
four spaces, which is the convention for Java and Python.  Just be
consistent.  

\subsection{Space Between \code{if} and Condition}

Use a space after \code{if}s.  For instance, use \code{if (x < y) ...}, not
\code{if(x < y) ...}.

\subsection{No Space For Function Calls}

There is no space between a function name and the function it applies
to.  For instance, use \code{normal(0,1)}, not \code{normal (0,1)}.

\subsection{Spaces Around Operators}

There should be spaces around binary operators.  For instance, use
\code{y[1]~<-~x}, not \code{y[1]<-x}, use \code{(x~+~y)~*~z} not
\code{(x+y)*z}.

\subsection{Breaking Expressions across Lines}

Sometimes expressions are too long to fit on a single line.  In that
case, the recommended form is to break \emph{before} an operator,%
%
\footnote{This is the usual convention in both typesetting and other
  programming languages. Neither R nor BUGS allows breaks before an
  operator because they allow newlines to signal the end of an
  expression or statement.}
%
aligning the operator to indicate scoping.  For example, use the
following form (though not the content; inverting matrices is almost
always a bad idea).
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
increment_log_prob((y - mu)' * inv(Sigma) * (y - mu));
\end{Verbatim}
\end{quote}
%
Here, the multiplication operator (\code{*}) is aligned to clearly
signal the multiplicands in the product.  

For function arguments, break after a comma and line the next
argument up underneath as follows.
%
\begin{quote}
\begin{Verbatim}[fontsize=\small]
y[n] ~ normal(alpha + beta * x + gamma * y,
              pow(tau,-0.5));
\end{Verbatim}
\end{quote}
%

\subsection{Optional Spaces after Commas}

Optionally use spaces after commas in function arguments for clarity.
For example, \code{normal(alpha * x[n] + beta,sigma)} can also be
written as \code{normal(alpha~*~x[n]~+~beta,~sigma)}.



\subsection{Unix Newlines}

Wherever possible, Stan programs should use a single line feed 
character to separate lines.  All of the Stan developers (so far, at 
least) work on Unix-like operating systems and using a standard 
newline makes the programs easier for us to read and share.  

\subsubsection{Platform Specificity of Newlines}

Newlines are signaled in Unix-like operating systems such as Linux and
Mac OS X with a single line-feed (LF) character (ASCII code point
\code{0x0A}).  Newlines are signaled in Windows using two characters,
a carriage return (CR) character (ASCII code point \code{0x0D})
followed by a line-feed (LF) character.


