From af91f3de614b59e91a1b4ba98680a5d1a7964308 Mon Sep 17 00:00:00 2001 From: Bob Carpenter Date: Thu, 30 Aug 2012 18:35:14 -0400 Subject: [PATCH] finished adding quick install instructions to manual --- src/docs/stan-reference/appendices.tex | 312 ++++++++++++++++++++++- src/docs/stan-reference/language.tex | 33 ++- src/docs/stan-reference/stan-manuals.sty | 2 +- web/mc-stan.org/mac-install.html | 2 +- 4 files changed, 338 insertions(+), 11 deletions(-) diff --git a/src/docs/stan-reference/appendices.tex b/src/docs/stan-reference/appendices.tex index fedab67219b..9744a2f090c 100644 --- a/src/docs/stan-reference/appendices.tex +++ b/src/docs/stan-reference/appendices.tex @@ -76,7 +76,7 @@ \section{Operating System} % \begin{itemize} \item Linux (Debian, Ubuntu, Red Hat), -\item Mac OS X (Snow Leopard, Lion), and +\item Mac OS X (Snow Leopard, Lion, Mountain Lion), and \item Windows (XP, 7). \end{itemize} % @@ -86,7 +86,315 @@ \section{Operating System} testing on older versions. -\section{Requirements} + +\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] +> 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-src-1.m.p.tgz} +(\code{m} is the minor version and \code{p} the patch level) from +the Stan downloads list, +% +\begin{quote} +\url{http://code.google.com/p/stan/downloads/list} +\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{.tgz} +file into file \code{stan-src-1.m.p.tar}, +double-click the \code{.tgz} file to unpack. + +Double click on the \code{.tar} file to unarchive +directory \code{stan-src-1.m.p}. + +Move the resulting directory to a location where it will not be +deleted, henceforth called \code{}. + + +\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] +> g++ --version +\end{Verbatim} +\end{quote} +% +and +% +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> 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] +> sudo apt-get install g++ +\end{Verbatim} +\end{quote} +% +and +% +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> 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-src-1.m.p.tgz}, where \code{m} is the minor version and +\code{p} the patch level), from the Stan downloads page, +% +\begin{quote} +\url{http://code.google.com/p/stan/downloads/list} +\end{quote} +% +to the directory where Stan will reside. + +In a command shell, change directories to where the +tarball was downloaded, say \code{}, with +% +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> cd +\end{Verbatim} +\end{quote} +% +where \code{} is replaced with the actual path to the diretory. + +Then, unpack the distribution into the subdirectory +\begin{quote} +\nolinkurl{/stan-src-1.m.p} +\end{quote} +% +with +% +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> tar -xzf stan-src-1.m.p.tgz +\end{Verbatim} +\end{quote} + + + +\section{Step-by-Step Windows Install Instructions} + +Stan has been tested on Windows XP and Windows 7. + +\subsection{Note for Cygwin Users} + +Stan can be run under Cygwin, the Linux 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 Linux. + +The remaining instructions in this section are for users wishing to +run Stan under Windows in a command (i.e., DOS) shell. + +\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-src-1.m.p.tgz}, 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{http://code.google.com/p/stan/downloads/list} +\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{} with +a Windows user name. +% +\begin{itemize} +\item \emph{Windows XP}: \ From the default starting directory, use +the followith commands (quotes and all): +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> cd "My Documents" +\end{Verbatim} +\end{quote} +% +The full path (including quotes) will work from anywhere, +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> cd cd "c:\Documents and Settings\\My Documents" +\end{Verbatim} +\end{quote} +\item \emph{Windows 7}: \ From the default starting directory, use +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> cd Documents +\end{Verbatim} +\end{quote} +or use the full path, including quotes, from anywhere, +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> cd "c:\Users\\Documents" +\end{Verbatim} +\end{quote} +\end{itemize} +% +To verify that the downloaded Stan \code{.tgz} file is there, +list the directory contents using: +% +\begin{quote} +\begin{Verbatim}[fontshape=sl] +> 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] +> tar -xzf --no-same-owner stan-src.1.m.p.tgz +\end{Verbatim} +\end{quote} +% +The \code{--no-same-owner} flag is not strictly necessary, +but it removes a bunch of irrelevant warnings. + + + +\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. diff --git a/src/docs/stan-reference/language.tex b/src/docs/stan-reference/language.tex index 9ea66ee28d4..f5260064516 100644 --- a/src/docs/stan-reference/language.tex +++ b/src/docs/stan-reference/language.tex @@ -527,8 +527,8 @@ \subsection{Unit Simplexes} \subsection{Ordered Vectors} An ordered vector type in \Stan represents a vector whose entries are -sorted in ascending order. For instance, $(1.0,2.7,2.71)^{\top}$ is -an ordered vector. Ordered vectors are most often employed as cut +sorted in ascending order. For instance, $(-1.3,2.7,2.71)^{\top}$ is +an ordered 3-vector. Ordered vectors are most often employed as cut points in ordered logistic regression models (see \refsection{ordered-logistic}). @@ -540,11 +540,30 @@ \subsection{Ordered Vectors} \end{Verbatim} \end{quote} % -After their declaration, ordered vectors, like unit simplexes, may be -assigned to other vectors and other vectors may be assigned to them. -Constraints will be checked after executing the block in which the -variables were declared. There is also a \code{positive\_ordered} vector type -which operates similarly but all entries are constrained to be positive. +After their declaration, ordered vectors, like unit simplexes, may be +assigned to other vectors and other vectors may be assigned to them. +Constraints will be checked after executing the block in which the +variables were declared. + + +\subsection{Positive, Ordered Vectors} + +There is also a positive, ordered vector type which operates similarly +to ordered vectors, but all entries are constrained to be positive. +For instance, $(2,3.7,4,12.9)$ is a positive, ordered 4-vector. + +The variable \code{d} is declared as a positive, ordered 5-vector by +% +\begin{quote} +\begin{Verbatim} +positive_ordered[5] d; +\end{Verbatim} +\end{quote} +% +Like ordered vectors, after their declaration positive ordered vectors +assigned to other vectors and other vectors may be assigned to them. +Constraints will be checked after executing the block in which the +variables were declared. \subsection{Unconstrained Row Vectors} diff --git a/src/docs/stan-reference/stan-manuals.sty b/src/docs/stan-reference/stan-manuals.sty index 123069ee263..cac437011a6 100644 --- a/src/docs/stan-reference/stan-manuals.sty +++ b/src/docs/stan-reference/stan-manuals.sty @@ -44,7 +44,7 @@ %\titlespacing{\subsection}{-1em}{12pt}{6pt} \usepackage{color} -\definecolor{linkcolor}{RGB}{16,16,128} +\definecolor{linkcolor}{RGB}{0,0,128} \usepackage[colorlinks=true,linkcolor=linkcolor,anchorcolor=linkcolor,citecolor=linkcolor,filecolor=linkcolor,menucolor=linkcolor,runcolor=linkcolor,urlcolor=linkcolor,pdfborder={0 0 0}]{hyperref} diff --git a/web/mc-stan.org/mac-install.html b/web/mc-stan.org/mac-install.html index 71a2c14de40..f409370238d 100644 --- a/web/mc-stan.org/mac-install.html +++ b/web/mc-stan.org/mac-install.html @@ -100,7 +100,7 @@

Stan Source

directory stan-src-1.m.p.

Move the resulting directory to a location where it will not be -deleted, henceforth called <path-to-stan>.

+deleted, henceforth called <stan-home>.

Complete the Installation