[4c0f6f]: doc / manual / jags_developer_manual.tex  Maximize  Restore  History

Download this file

257 lines (222 with data), 10.1 kB

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
\documentclass[11pt, a4paper, titlepage]{report}
\usepackage{a4wide}
\usepackage{url}
\usepackage{multirow}
\usepackage{amsfonts}
%\usepackage{amssym}
\newcommand{\JAGS}{\textsf{JAGS}}
\newcommand{\BUGS}{\textsf{BUGS}}
\newcommand{\WinBUGS}{\textsf{WinBUGS}}
\newcommand{\R}{\textsf{R}}
\newcommand{\CODA}{\textsf{coda}}
\begin{document}
\title{JAGS Developers Manual}
\author{Martyn Plummer}
\date{6 July 2011}
\maketitle
\tableofcontents
\chapter{Introduction}
This is currently a collection of notes on working with the JAGS
source. It will eventually grow into an explanation of how to extend
the capabilities of JAGS by writing new modules.
\chapter{Working with the CVS repository}
The \JAGS\ source code is held in a CVS repository. Clear
instructions on how to access the CVS source are given at the project
web site \url{http://sourceforge.net/projects/mcmc-jags}. To access
the instructions, click the link marked ``develop'' then the ``Code''
tab and select ``CVS'' from the pull-down menu.
You need a complete installation of GNU autotools (autoconf, automake,
and libtool) to work with the CVS source, since all non-essential
files have been stripped out of the repository. You must build local
versions of these files by changing directory into the top-level
source directory and typing
\begin{verbatim}
autoreconf -fi
\end{verbatim}
Your source tree is then ready to work with. Note that JAGS is not
currently compatible with automake-1.12. You must use automake-1.11
or earlier.
The CVS repository also excludes some \texttt{C++} source files that
are included in the source tarball. These files are re-created in the
build tree by the GNU tools \verb+flex+ and \verb+bison+. You must
also have these tools installed if you are using the CVS
repository. Note that the standard unix versions of these tools --
\verb+lex+ and \verb+yacc+ -- are not sufficient, and you must have an
up-to-date version of \verb+flex+. \footnote{On Solaris, the OpenCSW
package \texttt{flex} contains version 2.5.4, which is not compatible
with JAGS. Use the \texttt{flexnew} package}
Once you have checked out a CVS tree, you can keep it up to date with
\begin{verbatim}
cvs update -Pd
\end{verbatim}
You may occasionally need to rerun the autoreconf function when files
are added, removed, or moved within the repository.
I recommend keeping one or more build directories that are separate
from the source directory. I have several build directories for JAGS
configured in different ways: one standard one for testing the BUGS
examples, one with no optimization for debugging, another statically
linked one for profiling, and so on.
\chapter{Testing the Installation}
The classic bugs are available in the CVS module ``examples''. They
can also be downloaded in a tarball from the JAGS home page. There are
two sub-directories: ``vol1'' and ``vol2''. Within each sub-directory
you can test the installation with
\begin{verbatim}
make check
\end{verbatim}
To test a subset of examples, set the environment variable \verb+EXAMPLES+:
\begin{verbatim}
make check EXAMPLES="blocker bones"
\end{verbatim}
If you are not using a GNU system, you may need to use GNU make
(\verb+gmake+).
You need to have R installed in order to check the output of JAGS
against the benchmarks. If you have the \texttt{rjags} package
installed, then you may also test the rjags package with
\begin{verbatim}
make Rcheck
\end{verbatim}
\chapter{Directory structure}
The \JAGS\ source is divided into three main directories:
\texttt{lib}, \texttt{modules}, and \texttt{terminal}. The
\texttt{lib} directory contains the \JAGS\ library, which contains all
the facilities for defining a Bayesian graphical model in the \BUGS\
language, running the Gibbs sampler and monitoring the sampled
values. The \JAGS\ library is divided into several convenience
libraries
\begin{description}
\item[sarray] which defines the basic SArray class, modelled on an
\textsf{S} language array, and its associated classes.
\item[function] which defines the interface for functions and
the \texttt{FuncTab} class that allows you to reference them by name.
\item[distribution] which defines the interface for distribution and
the \texttt{DistTab} class that allows you to reference them by name.
\item[graph] which defines the various Node classes used by \JAGS\
when constructing a Bayesian graphical model, as well as the \texttt{Graph}
class which is a container for nodes.
\item[sampler] which defines the interface for Samplers, which update
stochastic nodes in the graph.
\item[model] which defines all the classes needed to create a model,
including monitor classes.
\item[compiler] which contains the Compiler class and a number of
supporting classes designed for an efficient translation of a BUGS-language
description the model into a \texttt{Graph}.
\item[rng] which defines the interface for random number generators (RNGs)
and the factories that create them.
\item[util] which contains some utility functions used in the rest of
the \JAGS\ library.
\end{description}
The \texttt{Console} class provides a clean interface to the \JAGS\
library. The member functions of the \texttt{Console} class conduct
all of the operations one may wish to do on a Bayesian graphical
model. They are designed to catch any exceptions thrown by the
library and print an informative message to either an output stream or
an error stream, depending on the result.
The \texttt{modules} directory contains the source code for JAGS
modules, which contain concrete classes corresponding to the abstract
classes defined in the \JAGS\ library.
The \texttt{terminal} directory contains the source code for a
reference front end for the \JAGS\ library, which uses the
\textsf{Stata}-like syntax described in the user manual
\chapter{Debugging and Profiling}
\label{chapter:debugging}
Debugging and profiling tools are essential for finding bugs and
bottlenecks in the code. The most important tools are \texttt{gdb},
\texttt{valgrind}, \texttt{gprof} and \texttt{oprofile}.
\section{Debugging with gdb}
\JAGS\ can be run from within the GNU debugger \texttt{gdb} by typing
\begin{verbatim}
jags -d gdb
\end{verbatim}
To run a script, type
\begin{verbatim}
r <scriptname>
\end{verbatim}
at the gdb prompt.
Debugging of optimized C++ code is not easy, especially when using
code from the Standard Template Library (STL). Unless you speak
fluent STL, you will need to work with a non-optimized build of
\JAGS. Using \verb+gcc+ this is done with the following build flags.
\begin{verbatim}
CXXFLAGS="-g -O0"
CFLAGS="-g -O0"
\end{verbatim}
It is helpful to keep a separate non-optimized build directory for
occasions when you need to use a debugger.
It is not possible to set a break point in a module before it has
been dynamically loaded. To do so, run JAGS by typing ``r'' at the
\verb+gdb+ prompt, then control-C to return to the gdb prompt after
the modules have been loaded.
\section{Debugging with valgrind}
Valgrind (\url{www.valgrind.org}) is a memory profiler and
debugger. To run \JAGS\ through valgrind, type
\begin{verbatim}
jags -d valgrind <script-file>
\end{verbatim}
If you need to pass options to valgrind, enclose these in quotes
\begin{verbatim}
jags -d 'valgrind --leak-check=full' <scriptfile>
\end{verbatim}
\JAGS\ will run very slowly inside valgrind, and will use more memory,
so its use should be limited to small test programs.
\section{Profiling with gprof}
The GNU profiler \texttt{gprof} does not debug dynamic libraries. It
is therefore not very useful for a standard installation of \JAGS,
since almost all of the functionality is contained in the jags
library, the jrmath library, and the modules. However, you can build
a statically linked version in which the libraries and modules are
folded into the executable \texttt{jags-terminal}. To build this
version of \JAGS, with profiling information for \texttt{gprof}, use
the following configure options:
\begin{verbatim}
CXXFLAGS="-g -O2 -pg" \
CFLAGS="-g -O2 -pg" \
/path/to/JAGS/configure --disable-shared
\end{verbatim}
Whenever \JAGS\ is run, it will create a file \texttt{gmon.out} in
the working directory that can be used for profiling with \texttt{gprof}.
\section{Profiling with oprofile}
Oprofile (\url{oprofile.sourceforge.net}) is a linux-based profiler
that runs as a daemon. Unlike \texttt{gprof} it does not require any
special configuration options, and can be used to debug dynamic libraries.
You must be root to start the profiler
\begin{verbatim}
opcontrol --no-vmlinux
opcontrol --start
\end{verbatim}
Then, as a normal user, you may run a model and dump the profiling
information to file with
\begin{verbatim}
opcontrol --dump
\end{verbatim}
To see how much time \JAGS\ is spending in the functions in a module
type
\begin{verbatim}
opreport -l /usr/local/lib/JAGS/modules/bugs.so | less
\end{verbatim}
The opreport command gives copious information, so you will need to
redirect the output to a file or, as in this example, a pager.
The same command works for the main \JAGS\ library
\begin{verbatim}
opreport -l /usr/local/lib/libjags.so
\end{verbatim}
More detailed profiling information can be obtained with the
\verb+opannotate+ command, provided that \JAGS\ has been compiled
with debugging symbols. The command
\begin{verbatim}
opannotate --source /usr/local/lib/JAGS/modules/bugs.so | less
\end{verbatim}
reconstructs the source code and gives annotations in a column in
the left hand side counting the number of samples in each function,
block or line. This can be useful for finding bottlenecks in the code.
Oprofile will continue to accumulate samples from multiple runs of JAGS,
although the output of the \verb+opreport+ and \verb+opannotate+ commands
will not change until you dump the data again with \verb+opcontrol --dump+.
If you do not wish to see the cumulative samples from multiple runs --
for instance if you have modified the \JAGS\ code and want to check that
a previous bottleneck has been removed -- then you can clear the existing
data collection by typing, as root
\begin{verbatim}
opcontrol --reset
\end{verbatim}
\end{document}