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.