MC:  Programs and modules supporting Markov chain Monte Carlo methods.

The 'mc' programs and modules support Monte Carlo methods based on
sampling using Markov Chains.  The state space, desired distribution,
and perhaps some special sampling procedures are defined by an
application module linked with the generic 'mc' modules.  Successive
states are stored in a log file, for use by programs that make Monte
Carlo estimates.  

Users of applications that use the 'mc' modules needn't know the
details of how it works.  The following documentation is for
programmers wishing to use these modules in a new application.

The full state space sampled from consists of up to four components:

    1) A set of "position" components, defined by the application, and
       stored in whatever records it pleases.
 
    2) A set of auxiliary components, also defined by the application,
       and stored in whatever records it pleases.

    3) A set of "momentum" components, in one-to-one correspondence
       with the position components.  These are added by this module,
       and stored in a record of type 'p'.

    4) A current inverse temperature, and associated change direction,
       if simulated tempering is being done.  These are added by this 
       module, and stored in a record of type 'b'.

The auxiliary components are updated only by the application module.
The position, momentum, and inverse temperature components are updated
by operations defined in this module, based on an "energy" function
provided by the application.  The application module can directly
update position coordinates as well.

Sampling is an iterative procedure, each iteration being one transition 
of a Markov chain.  An iteration consists of one or more of the
following operations, each of which has an identifying letter, and
each of which corresponds to a specification documented with mc-spec:

    B  heatbath               b  rand-dir
    N  negate                 n  neg-dir
    M  metropolis             s  sim-temp
    m  met-1                  r  radial-heatbath

    D  dynamic                A  (application-specific operation)
    P  permuted-dynamic       R  repeat
    H  hybrid                 E  end
    T  tempered-hybrid        p  plot

    S  slice-1                t  temp-trans
    O  slice-over             a  ais
    i  slice-inside
    o  slice-outside

The sequence of operations to use is specified by the user, and is
stored in the log file as a record of type 'o'.  Some of the
operations involve computing dynamical trajectories.  The method to be
used to do this is also specified by the user, and is stored in the
log file as a record of type 't'.  Tempering schemes use a temperature
schedule stored in a record of type 'm'.  In all these cases, the last
such record stored in the log file is used.

Records of type 'i' containing information on an iteration are
periodically written to the log file, along with the current state.
The momentum part of the state is written as a record of type 'p'.
The position and auxiliary parts of the state are written as defined
by the application.

The state of the random number generator after each iteration is
stored in records of type 'r', the first of which may be written at
index -1 using the 'rand-seed' program.

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