 GAUSSIAN PROCESS REGRESSION AND CLASSIFICATION Toolbox version 3.1
    for GNU Octave 3.2.x and Matlab 7.x

Copyright (c) by Carl Edward Rasmussen and Hannes Nickisch, 2010-09-27.



0) HOW TO READ
==============

If you want to get started without further delay, then read section 1) below
and jump right to the examples in doc/index.html.



1) ABOUT THESE PROGRAMS
=======================

This collection of matlab programs implements and demonstrates some of the
algorithms described in 
a) the book by Rasmussen and Williams: "Gaussian Processes for Machine Learning", 
the MIT Press 2006, in
b) the article by Nickisch and Rasmussen: "Approximations for Binary Gaussian
Process Classification", JMLR 2008 and in
c) the article by Candela and Rasmussen: "A Unifying View of Sparse Approximate
Gaussian Process Regression", JMLR 2005.

There are 6 code subdirectories: cov, doc, inf, lik, mean and util.

cov/      contains covariance functions cov*.m
          => see covFunctions.m

doc/      contains an index.html file providing documentation. This information
          is also available from http://www.GaussianProcess.org/gpml/code.
          Usage of mean, cov, classification and regression is demonstrated
          in usage*.m. Further details can be found in the developer
          documentation manual.pdf.

inf/      contains the inference algorithms inf*.m
          => see infMethods.m

lik/      contains the likelihood functions lik*.m
          => see likFunctions.m

mean/     contains the mean functions mean*.m
          => see meanFunctions.m

util/     contains optimisation routines, backward compatibility programs and
          small auxiliary scripts

Before running the demos or any other part of the code, you should execute 
startup.m to add all necessary directories to your path. In Octave, you can also
use the .octaverc file.



2) ABOUT MEX FILES
==================

Some of the programs make use of the MEX facility in matlab for more efficient
implementation. However, if you don't know about how to compile MEX files, you
do not need to worry about this -- the code runs anyway. If you do compile the
MEX files, this is automatically detected, and the program will run more 
efficiently. If you do not have a compiler installed on your system, you might
want to consult [2].

Two components of the toolbox can be accelerated by MEX. 

First, there is an auxiliary functions solve_chol.m having a MEX equivalent. 
This can be compiled by either executing util/make.m from the Matlab/Octave 
command line. In addition to that, we provide a Makefile
for Matlab in util/ that you can run by simply typing make in your shell after
having supplied your Matlab path and your operating system. 
We recommend the make.m script because it works both under Matlab and Octave.

Second, in order to use the L-BFGS minimiser for hyperparameter optimisation as
an equivalent to minimize.m, you have to compile Peter Carbonetto's 
"Matlab interface for L-BFGS-B" [1]. The challenge here is the Fortran 77 code.
We provide a Makefile suitable for Linux 32/64 bit and Mac whenever you have 
1) g77 
or 
2) gfortran
properly set up.
Under Ubuntu, you can achieve this by installing the packages fort77 and 
gfortran, respectively.

Compilation is done by editing util/lbfgsb/Makefile. In any case, you need to 
provide $MATLAB_HOME which can be found by the commands 'locate matlab' or 
'find / -name "matlab"'. You can choose between two compilation modes:
a) using the mex utility by Matlab                                     [default]
  provide $MEX, then type 'make mex'

b) without mex utility by Matlab
  provide $MEX_SUFFIX and $MATLAB_LIB, then type 'make nomex'

In Ubuntu 10.04 LTS, the libg2c library needed for both 1)+a) and 1)+b) is not 
included per default. If 'ls /usr/lib/libg2c.*' does not list anything 
this is the case on your machine. You then whant to install the packages 
gcc-3.4-base and libg2c0 e.g. from
http://packages.ubuntu.com/hardy/gcc-3.4-base and
http://packages.ubuntu.com/hardy/libg2c0.
After installation, you have to create a symbolic link by 'cd /usr/lib' and 
'ln -s libg2c.so.0 libg2c.so'.

[1] http://www.cs.ubc.ca/~pcarbo/lbfgsb-for-matlab.html
[2] http://www.mathworks.com/support/compilers/R2010a



3) CURRENT VERSION
==================

The current version of the programs is 3.0. Previous versions of the code are
available at http://www.gaussianprocess.org/gpml/code/oldcode.html.



4) DIFFERENCES TO PREVIOUS VERSIONS
===================================

NEW in version 3.1, 2010-10-10
------------------------------
- following a suggestion by Ed Snelson we now support FITC regression
- cov/covFITC.m and inf/infFITC.m have been added with Ed Snelson's help
- the covariance interface was slightly changed to make that possible

NEW in version 3.0, 2010-07-23
------------------------------
A major code reorganisation effort did take place in the current release. First,
classification and regression are now done by a single file gp.m which is 
completely generic in the likelihood. The previous regression program gpr.m 
corresponds to gp.m with Gaussian likelihood. Several other likelihoods for
robust regresssion were added.
Further, the code now supports mean functions with a similar specification
mechanism as already used by the covariance functions. Previous implementations
correspond to using meanZero.m.
We merged the covariance functions covMatern3iso.m and covMatern5.iso into a
single covMaterniso.m and added a covariance function for additive functions as
well as the possibility to use only certain components of the data. Finally, we
included covPPiso.m a piecewise polynomial covariance function with compact 
support.

New likelihood functions in lik/:
likGauss.m, likLaplace.m, likLogistic.m and likT.m

New mean functions in mean/:
meanConst.m, meanLinear.m, meanPow.m, meanProd.m, meanSum.m and meanZero.m

New covariance functions in cov/:
covADD.m, covMask.m, covPPiso.m

The gprSRPP.m function which previously provided "Subset of Regressors" and the
"Projected Process" approximation has now been removed.


NEW in version 2.1, 2007-07-25
------------------------------
covConst.m: fixed a bug which caused an error in the derivative of the log marginal
    likelihood for certain combinations of covariance functions and approximation
    methods. (Thanks to Antonio Eleuteri for reporting the problem)

gauher.m: added the function "gauher.m" which was mistakenly missing from the 
    previous release. This caused an error for certain combinations of
    approximation method and likelihood function.

logistic.m: modified the approximation of moments calculation to use a mixture
    of cumulative Gaussian, rather than Gauss-Hermite quadrature, as the former
    turns out to be more accurate.


NEW in version 2.0, 2007-06-25
------------------------------
Some code restructuring has taken place for the classification code to make it
more modular, to facilitate addition of new likelihood functions and
approximations methods. Now, all classification is done using the binaryGP
function, which (among other things) takes an approximation method and a
likelihood function as an arguments. Thus, binaryGP replaces both binaryEPGP
and binaryLapaceGP, although wrapper functions are still provided for backward
compatibility. This gives added flexibility: now EP can also be used wth the
logistic likelihood function (implemented using Gauss-Hermite quadrature).

approxEP.m: New file, containing the Expectation Propagation approximation
    method, which was previously contained in binaryEPGP.m

approxLA.m: New file, containing Laplaces approximation method, which was 
    previously contained in binaryLaplace.m 

approximations.m: New file, help for the approximation methods.

binaryEPGP.m: This file has been replaced by a wrapper (for backward
    compatibility) which calls the more general binaryGP function.

binaryGP.m: New general function to do binary classification.

binaryLaplaceGP.m: This file has been replaced by a wrapper (for backward
    compatibility) which calls the more general binaryGP function.

covMatern3iso.m, covMatern5iso.m, covNNone.m, covRQard.m, covRQiso.m,
cosSEard, covSEiso: now check more carefully, that persistent variables have
    the correct sizes, and some variable names have been modified.

cumGauss.m: New file, containing code for the cumulative Gaussian
    likelihood function

likelihoods.m: New file, help for likelihood functions

logistic.m: New file, logistic likelihood


NEW in version 1.3, 2006-09-08
------------------------------
covRQard.m: bugfix: replaced x with x' and z with z' in line 36

covRQiso.m: bugfix: replaced x with x' and z with z' in line 28

minimize.m: correction: replaced "error()" with "error('')", and
            made a few cosmetic changes

binaryEPGP.m: added the line "lml = -n*log(2);" in line 77. This change
         should be largely inconsequential, but occationally may save things
         when the covariance matrix is exceptionally badly conditioned.


NEW in version 1.2, 2006-05-10
------------------------------
added the "erfint" function to "binaryLaplaceGP.m". The erfint function
was missing by mistake, preventing the use of the "logistic" likelihood.


NEW in version 1.1, 2006-04-12
------------------------------
added files: "covProd.m" and "covPeriodic.m"

changes: "covSEiso.m" was changed slightly to avoid the use of persistent
         variables


NEW in version 1.0, 2006-03-29
------------------------------
initial version shipped with the book
