updated manual for 2.6, added Bernoulli example directly to cmdstan distro

Author: Bob Carpenter

examples/bernoulli/bernoulli.data.R

@@ -0,0 +1,2 @@
+N <- 10
+y <- c(0,1,0,0,0,0,0,0,0,1)

examples/bernoulli/bernoulli.stan

@@ -0,0 +1,12 @@
+data { 
+  int<lower=0> N; 
+  int<lower=0,upper=1> y[N];
+} 
+parameters {
+  real<lower=0,upper=1> theta;
+} 
+model {
+  theta ~ beta(1,1);
+  for (n in 1:N) 
+    y[n] ~ bernoulli(theta);
+}

src/docs/cmdstan-guide/cmdstan-guide.tex

@@ -2,7 +2,7 @@
 
 \usepackage{../../../stan/src/docs/stan-reference/stan-manuals}
 
-\newcommand{\cmdstanversion}{2.5.0}
+\newcommand{\cmdstanversion}{2.6.0}
 \newcommand{\CmdStan}{CmdStan\xspace}
 
 \begin{document}
@@ -12,8 +12,11 @@
 \frontmatter
 \include{title}
 \tableofcontents
+\newcounter{savepage}
+\setcounter{savepage}{\arabic{page} + 2}
 
 \mainmatter
+\setcounter{page}{\thesavepage}
 \part{Introduction}
 \include{introduction}
 \include{getting-started}

src/docs/cmdstan-guide/getting-started.tex

@@ -43,8 +43,9 @@ \section{Building \CmdStan}
     %
   \item Use make to build \CmdStan. If multiple CPU cores are
     available, the call to make can be parallelized with the
-    \code{-j2} option, where \code{2} is the number of CPU cores. The
-    parallel option (\code{-j2}) can be safely omitted.
+    \code{-j{\slshape N}} option, where \code{{\slshape N}} is the number of CPU cores. The
+    parallel option (\code{-j{\slshape N}}) can be safely omitted.
+  For instance, to run on 2 cores, use
     %
     \begin{quote}
       \begin{Verbatim}[fontshape=sl]
@@ -54,7 +55,8 @@ \section{Building \CmdStan}
     %
     \emph{Warning:} \ The \code{make} program may take 10+ minutes and
     consume 2+ GB of memory to build \CmdStan.  Compiler warnings,
-    such as \code{uname:~not found}, may be safely ignored.
+    such as \code{uname:~not found} or \code{warning: unused
+      variable}, may be safely ignored.
 
 \end{enumerate}
 %
@@ -87,13 +89,14 @@ \section{Compiling and Executing a Stan Program}\label{compiling-model.section}
 
 \subsection{A Simple Bernoulli Model}
 
-The following simple model is distributed with \CmdStan and is located at
+The following is a simplet, complete Stan program for a Bernoulli
+model of binary data.%
 %
-\begin{quote}
-\href{https://github.com/stan-dev/example-models/blob/master/basic_estimators/bernoulli.stan}{\nolinkurl{stan/example-models/basic_estimators/bernoulli.stan}}
-\end{quote}
-%
-The file contains the following \Stan program.
+\footnote{The model is distributed with Stan's example models
+  repository,
+  \url{https://github.com/stan-dev/example-models/blob/master/basic_estimators/bernoulli.stan},
+  and is also available with the CmdStan distribution at the path
+  \nolinkurl{examples/bernoulli/bernoulli.stan}.  }
 %
 \begin{quote}
 \begin{Verbatim}
@@ -118,13 +121,15 @@ \subsection{A Simple Bernoulli Model}
 
 \subsection{Data Set}
 
-A data set of $\mbox{\code{N}}=10$ observations is available in the file
+A data set of $\mbox{\code{N}}=10$ observations is coded as follows.
 %
-\begin{quote}
-\href{https://github.com/stan-dev/example-models/blob/master/basic_estimators/bernoulli.data.R}{\nolinkurl{stan/example-models/basic_estimators/bernoulli.data.R}}
-\end{quote}
-%
-The content of the file is as follows.
+\footnote{
+The data is also available from the \code{example-models} repository
+on GitHub,
+\url{https://github.com/stan-dev/example-models/blob/master/basic_estimators/bernoulli.data.R}.
+It is also included with the CmdStan distribution and can be found at path
+\nolinkurl{stan/example-models/basic_estimators/bernoulli.data.R}.
+}
 %
 \begin{quote}
 \begin{Verbatim}
@@ -294,11 +299,11 @@ \subsubsection{Sampler Output}
 lp__,accept_stat__,stepsize__,treedepth__,n_leapfrog__,n_divergent__,theta
 \end{Verbatim}
 %
-The first column reports the unnormalized log probability of the model.  The next
-columns provide sampler-dependent information; here, it is columns two
-through five. For basic Hamiltonian Monte Carlo (HMC) and its adaptive
-variant No-U-Turn sampler (NUTS), the sampler-depedent parameters are
-described in the following table.
+The first column reports the unnormalized log probability of the
+model.  The next columns provide sampler-dependent information; here,
+it is columns two through five. For basic Hamiltonian Monte Carlo
+(HMC) and its adaptive variant, the No-U-Turn sampler (NUTS), the
+sampler-depedent parameters are described in the following table.
 %
 \begin{center}
 \begin{tabular}{l|l|l}
@@ -463,7 +468,7 @@ \subsection{Optimization}
 \end{Verbatim}
 \end{quote}
 %
-which prints out
+Executing this command prints the following.
 %
 \begin{Verbatim}[fontsize=\footnotesize]
  method = optimize
@@ -491,8 +496,8 @@ \subsection{Optimization}
    refresh = 100 (Default)
 
 initial log joint probability = -5.18908
-  Iter      log prob        ||dx||      ||grad||       alpha      alpha0  # evals  Notes 
-     4      -5.00402    0.00400907   7.80306e-05           1           1        7   
+  Iter     log prob        ||dx||      ||grad||    alpha   alpha0  # evals  Notes 
+     4     -5.00402    0.00400907   7.80306e-05        1        1        7   
 Optimization terminated normally: 
   Convergence detected: relative gradient magnitude is below tolerance
 \end{Verbatim}

src/docs/cmdstan-guide/installation.tex

@@ -20,7 +20,8 @@ \section{Operating System}
 %
 \begin{itemize}
 \item Linux (Debian, Ubuntu, Red Hat), 
-\item Mac OS X (Mavericks, Snow Leopard, Lion, Mountain Lion), and
+\item Mac OS X (10.10 ``Yosemite,'' 10.9 ``Mavericks,'' 10.8
+  ``Mountain Lion,'' 10.7 ``Lion,'' and 10.6 ``Snow Leopard'')
 \item Windows (XP, 7, 8).
 \end{itemize}
 %
@@ -36,18 +37,31 @@ \section{Required Software and Tools}
 
 \subsection{\CmdStan Source}
 
-In order to compile \Stan program, the \CmdStan source code is required.
-The latest version of \CmdStan can be downloaded from the following link.
+In order to compile \Stan program, the \CmdStan source code is
+required.  The \CmdStan source code distribution includes \CmdStan's
+source code, \Stan's source code, documentation, build scripts, unit
+tests, example models models, documentation and source for the
+required libraries Boost and Eigen, and the source for an optional
+testing library, Google Test.
+
+\subsubsection{CmdStan: Stable Releases}
+
+The latest release version of \CmdStan can be downloaded
+from the CmdStan home page:
 %
 \begin{quote}
-\url{http://mc-stan.org/}
+\url{http://mc-stan.org/cmdstan.html}
 \end{quote}
 %
-The \CmdStan source code distribution includes \CmdStan's source code,
-\Stan's source code, documentation, build scripts, unit tests, example
-models models, documentation and source for the required libraries
-Boost and Eigen, and the source for an optional testing library,
-Google Test.
+
+\subsubsection{CmdStan: Development Source Control}
+
+The source code repository is hosted by GitHub, and contains the
+latest versions of CmdStan (and Stan) underdevelopment.  See:
+%
+\begin{quote}
+http://mc-stan.org/source-repos.html
+\end{quote}
 
 \subsubsection{Boost C++ Library Source}
 
@@ -56,7 +70,7 @@ \subsubsection{Boost C++ Library Source}
 Library.
 %
 \begin{itemize}
-\item Home: http://www.boost.org/users/license.html
+\item Home: \url{http://www.boost.org/users/license.html}
 \item License: Boost Software License
 \item Tested Version: 1.54.0
 \end{itemize}
@@ -194,10 +208,10 @@ \subsection{Verifying Tools}
 
 \subsection{Downloading and Unpacking \CmdStan}
 
-The \CmdStan source code distributions are named
-\code{cmdstan-2.5.p.tar.gz}, where \code{p} is the patch
-version. Download the latest \CmdStan source tarball from the \CmdStan
-downloads page,
+The \CmdStan source code distribution is named
+\code{cmdstan-\cmdstanversion.tar.gz}; the versions here are major version 2,
+minor version 6, and patch level 0.  Download the latest \CmdStan
+source tarball from the \CmdStan downloads page,
 %
 \begin{quote}
 \url{https://github.com/stan-dev/cmdstan/releases}
@@ -253,7 +267,7 @@ \subsection{Downloading and Unpacking \CmdStan}
 %
 \begin{quote}
 \begin{Verbatim}[fontshape=sl,fontsize=\small]
-> tar --no-same-owner -xzf cmdstan-2.5.p.tar.gz 
+> tar --no-same-owner -xzf cmdstan-\cmdstanversion.tar.gz 
 \end{Verbatim}
 \end{quote}
 %
@@ -317,8 +331,7 @@ \subsection{Install Xcode C++ Development Environment}
 
 \subsection{Download and Unpack \CmdStan Source}
 
-Download the most recent version of \code{cmdstan-2.5.p.tar.gz}
-(\code{p} the patch level) from
+Download the most recent version of \code{cmdstan-\cmdstanversion.tar.gz} from
 the \CmdStan downloads list,
 %
 \begin{quote}
@@ -329,11 +342,11 @@ \subsection{Download and Unpack \CmdStan Source}
 (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{cmdstan-2.5.p.tar},
+file into file \code{cmdstan-\cmdstanversion.tar},
 double-click the \code{.tar.gz} file to unpack.
 
 Double click on the \code{.tar} file to unarchive
-directory \code{cmdstan-2.5.p}.
+directory \code{cmdstan-\cmdstanversion}.
 
 Move the resulting directory to a location where it will not be
 deleted, henceforth called \code{<cmdstan-home>}.
@@ -380,8 +393,7 @@ \subsection{Installing C++ Development Tools}
 \subsection{Downloading and Unpacking \CmdStan Source}
 
 Download the most recent stable version of \CmdStan,
-\code{cmdstan-2.5.p.tar.gz}, where \code{p} the patch level, from the
-\CmdStan downloads page,
+\code{cmdstan-\cmdstanversion.tar.gz}, from the \CmdStan downloads page,
 %
 \begin{quote}
 \url{https://github.com/stan-dev/cmdstan/releases}
@@ -402,14 +414,14 @@ \subsection{Downloading and Unpacking \CmdStan Source}
 
 Then, unpack the distribution into the subdirectory
 \begin{quote}
-\nolinkurl{<download-dir>/cmdstan-2.5.p}
+\nolinkurl{<download-dir>/cmdstan-\cmdstanversion}
 \end{quote}
 %
 with
 %
 \begin{quote}
 \begin{Verbatim}[fontshape=sl,fontsize=\small]
-> tar -xzf cmdstan-2.5.p.tar.gz
+> tar -xzf cmdstan-\cmdstanversion.tar.gz
 \end{Verbatim}
 \end{quote}
 
@@ -589,7 +601,7 @@ \subsection{Git Version Control System}
 \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
+\item Tested Version(s): Mac versions 1.8.2.3 and 1.7.8.4; Windows version 1.7.9
 \end{itemize}
 
 
@@ -604,7 +616,7 @@ \subsubsection{Google Test C++ Testing Framework}
 \item
 License: BSD
 \item
-Tested Version(s): 1.6.0
+Tested Version(s): 1.7.0
 \end{itemize}
 %
 The Google Test framework is distributed with \Stan.

src/docs/cmdstan-guide/introduction.tex

@@ -41,9 +41,10 @@ \section{Example Models}
 
 \section{Benefits of \CmdStan}
 
-Although \CmdStan has the least amount functionality among the \Stan
-interfaces, the minimal nature of \CmdStan makes it trivial to install
-and use the latest development version of the \Stan library. It also
-has the least dependencies, which makes it easy to run on limited
-environments such as clusters. The output generated can be post-processed
-using other interfaces.
+Although \CmdStan has the least amount of functionality among the
+\Stan interfaces, the minimal nature of \CmdStan makes it trivial to
+install and use the latest development version of the \Stan
+library. It also has the fewest dependencies, which makes it easier to
+run in limited environments such as clusters. The output generated is
+in CSV format and can be post-processed using other Stan interfaces or
+general tools.

src/docs/cmdstan-guide/running.tex

@@ -1565,10 +1565,40 @@ \subsection{Optimization Templates}
 %
 \CmdStan supports several optimizers.  These share many of their
 configuration options with the samplers.  The default optimizer is the
-Broyden-Fletcher-Goldfarb-Shanno (BFGS) method and a limited-memory
-version of this algorithm, L-BFGS, is also implemented (see
-\citep{NocedalWright:2006} for more information on BFGS and L-BFGS).
-The command skeleton for BFGS is in \reffigure{bfgs-command}.
+the limited memory Broyden-Fletcher-Goldfarb-Shanno (L-BFGS) method;
+\cite{NocedalWright:2006} contains an excellent overview of both the
+BFGS and L-BFGS algorithms.  The command skeleton for L-BFGS is in
+\reffigure{l-bfgs-command} and the one for BFGS is in
+\reffigure{bfgs-command}.
+%
+\begin{figure}
+\begin{quote}
+\begin{Verbatim}[fontshape=sl,fontsize=\small]
+> ./my_model optimize                                   \
+                 algorithm=lbfgs                         \
+                     [init_alpha=<double>]              \
+                     [tol_obj=<double>]                 \
+                     [tol_rel_obj=<double>]             \
+                     [tol_grad=<double>]                \
+                     [tol_rel_grad=<double>]            \
+                     [tol_param=<double>]               \
+                     [history_size=<int>]               \
+                 [iter=<int>]                           \
+                 [save_iterations=<boolean>]            \
+             [data file=<string>]                       \
+             [init=<string>]                            \
+             [random seed=<int>]                        \
+             [output                                    \
+                  [file=<string>]                       \
+                  [diagnostic_file=<string>]            \
+                  [refresh=<int>] ]
+\end{Verbatim}
+\end{quote}
+\caption{\small\it Command skeleton for invoking the L-BFGS optimizer.
+  All arguments and their default values are described in detail in
+  \refsection{detailed-command-arguments}.}
+\label{l-bfgs-command.figure}
+\end{figure}
 %
 \begin{figure}
 \begin{quote}

src/docs/cmdstan-guide/title.tex

@@ -20,13 +20,13 @@
 \begin{center}
 \begin{minipage}[t]{0.75\textwidth}
 \small
-Stan Development Team. 2014.  
+Stan Development Team. 2015.  
 {\it CmdStan: User's Guide}. Version
 \cmdstanversion
 \vspace*{20pt}
 \mbox{ }
 \\
-Copyright \copyright \ 2011--2014, Stan Development Team.
+Copyright \copyright \ 2011--2015, Stan Development Team.
 \vspace*{28pt}
 \mbox{} \\
 This document is distributed under the Creative Commons Attribute 4.0