INSTALLING THE SOFTWARE

This section describes how to unpack and compile the software for a
Unix/Linux/macOS machine.  Note that getting the software to work in a
different environment may be difficult or impossible.


Unpacking the files.

The software is distributed as a Unix tar archive.  You should
download the tar archive for the desired version from my web page at
www.cs.utoronto.ca/~radford/fbm.software.html via your Web browser, or
using 'wget'.  Or alternatively, you can get it from the gitlab
repository at gitlab.com/radfordneal/fbm.  It should be saved in a
file with a name of the form 'fbm.YYYY-MM-DD.tar'.  You should then
unpack it with the command

    tar xf fbm.YYYY-MM-DD.tar

The following instructions cover what to do next for the current
version; you should read the old documentation if for some reason you
are installing an older version.

The tar command should create a directory called 'fbm.YYYY-MM-DD',
where YYYY-MM-DD is the release date.  It should place numerous files
and sub-directories in this directory.  If this seems to have worked,
you can remove the file 'fbm.YYYY-MM-DD.tar'.  You should now change
into the 'fbm.YYYY-MM-DD' directory, as the following instructions
assumed that you are there.

If you prefer that this directory be called something other than
'fbm.YYYY-MM-DD', change the name now, BEFORE compiling the programs,
since the programs look for a file of random numbers in the directory
under the name it had when they were compiled.


Compiling the programs.

Compling the programs requires a C development environment.  On an
Ubuntu Linux system, you may need to use

    sudo apt-get install build-essential

On a macOS system, you may need

    xcode-select --install

Installing further things may also be necessary; the details will vary
with your exact system.

Once the build tools are installed, you will probably be able to
compile the programs as described below without having to change
anything.  However, you may well want to use a different C compiler
than the default gcc, or set certain compilation options that could
increase performance.  You can set the required options by modifying
the 'make.include' file in the main directory, which gets included in
all Makefiles used, though for some problems you might have to modify
the 'Makefile' and 'xxx.make' files in the various sub-directories, or
modify the source files. 

Here are some reasons that you might need to customize things:

  1) The programs are written in C as defined by the C99 standard.  If
     you compiler defaults to some other idea of what C is, you should
     try to persuade it otherwise (eg, with a --std=c99 option).

  2) The programs were written with IEEE floating-point in mind, and
     therefore may occasionally perform operations that result in
     overflow or underflow.  If this causes program termination on
     your machine (eg, with a "floating point exception"), you will
     need to figure out how to disable these errors. 

  3) You might want to change the settings of the options for use of
     vector instructions on some machines, as described in comments
     in make.include.

  4) If compiling versions of (some of) the programs to use a GPU, 
     you may want to modify the --gpu-architecture option for nvcc,
     as explained in make.include. 

  5) You might want to change the default for whether floating-point
     arithmetic (in some neural network modules) is performed in
     32-bit (float) or 64-bit (double) precision, by modifying the
     default in make-all (initially set to float).

  6) The 'util' directory contains a file of 100,000 natural random
     bytes, which are used in combination with pseudo-random numbers
     This file is accessed by many of the programs, using a path 
     name that by default points into this 'util' directory.  If you 
     plan on moving this file elsewhere, you will need to change the 
     compilation command for rand.c at the end of 'util/util.make'.

  7) If you are rather short of memory, you might want to reduce the
     size of the Max_optional_memory constant defined in gp/gp-mc.c.
     This will save memory at the cost of some time.

Once you have made any required changes, you can compile the programs
by going to the main directory where you installed the software and
issuing the command

    make-all

This will compile programs in the various sub-directories.  Note that
some modules will be compiled over again in each directory where they
are used; this is intentional.

It is possible that these compilation commands will fail for some
reason, in which case you'll have to figure out what's wrong and fix
it.  You might want to start by looking at the make-all shell script.

You can pass one or two arguments to make-all.  A first argument of
"dbl" or "flt" specifies the precision used for arithmetic (in some
modules, currently only neural networks) for the version of the
programs compiled.  The default with no arguments is "flt" (if you
haven't changed the default).  A second argument of "gpu" causes
versions of some programs that make use of a GPU to be compiled (in
addition to the versions that use only the CPU).  This requires that a
suitable GPU be present, and that suitable software be installed.


Using the programs.

Once you have successfully compiled the programs, you should put the
'bin-fbm' directory (within the main directory for this software) in
your search path (the PATH environment variable).  How this is done
depends on the shell program you are using.  This directory contains
symbolic links to all the programs making up this software.

See Using.doc for more information on how to use the programs once you
have installed them, including on how to switch between versions that
use a GPU or not, or that use 32-bit or 64-bit floating-point
arithmetic.


Multiple architectures.

If you want to use the programs on more than one type of machine,
which share the file system you are using (which is nowadays an
uncommon thing to do), you will need to compile them several times,
once for each machine architecture (do a 'make-clean', as described
below, before re-compiling for a new architecture).  You will also
need to set your search path to a directory that contains the versions
of the programs compiled for the machine you are currently using.  By
convention, these directories should be called "bin.ARCH", where ARCH
is the name of the machine architecture.  The shell file install-arch
creates such a directory (if necessary) and copies the programs from
the "bin" directory to the "bin.ARCH" directory for the current
architecture.  It is assumed that a program called 'arch' exists that
returns the name of the architecture.


Cleaning things up.

Once the compilations have finished, you can save some disk space by
issuing the command

    rm */*.o

when you are in the main directory.  You can get rid of the compiled
programs (and the .o files) by using the command

    make-clean

when in the main directory.  Of course, you then won't be able to use
the programs until you do another make-all to recompile them, unless
you made then with an explicitly-specified precision (and you run them
as such), or you had copied them to a "bin.ARCH" directory.

You can get rid of the copies of programs for a particular precision
using "rm bin-dbl/*" or "rm bin-flt/*".  Do not remove things from
bin-dbl-gpu or bin-flt-gpu, which contain only links.