DIST:  Markov chain sampling for a specified distribution.

The 'dist' programs allow you to specify a distribution by giving an
"energy" function (minus the log of the density, plus an arbitrary
constant), and to then generate a sample from this distribution using
the various Markov chain methods.  Alternatively, a distribution can
be specified by giving expressions for minus the log of the prior
density for a Bayesian model and minus the log of the likelihood.

These programs are primarily intended for use in demonstrating the
Markov chain methods.  Although some interesting Bayesian models can
easily be specified, using these programs to sample from many of the
distributions encountered in real Bayesian inference problems would be
tedious or impossible.  However, the C source for the 'dist' programs,
as well that for the demo for a bivariate Gaussian (see bvg.doc), does
illustrate how to interface to the generic Markov chain routines, in
order to write a suite of programs for some new application.  The code
for this in the 'dist' and 'bvg' programs is perhaps more easily
understood than the more complex code in the 'net', 'gp', and 'mix'
programs.

The distribution is specified using the dist-spec program (see
dist-spec.doc).  An initial state for the Markov chain can then be
specified (see dist-initial.doc).  The Markov chain operations to use
should then be specified (see mc-spec.doc), after which the Markov
chain is run using dist-mc (see dist-mc.doc).  The resulting states
can be printed (see dist-display.doc), or the values of selected state
variables can be plotted (see xxx-plt.doc and dist-quantities.doc).

Note that values for the energy function, and its gradient if
required, are calculated by an interpreter written in C, which is
considerably slower than compiled C code.  The compute time required
to sample from a distribution using the 'dist' programs will therefore
be greater than would be required using a specially-written module.

            Copyright (c) 1995-2004 by Radford M. Neal