Installation of  BMElib

BMElib  is a set of programs for spatiotemporal geostatistics in Temporal GIS written in MatLab (version 5.3 and later) and Fortran accompanying the following textbook:

Christakos, G., P. Bogaert, and M.L. Serre, Temporal GIS, Springer-Verlag, New York, NY, CD-ROM included, 2002.

The website http://www.unc.edu/depts/case/BMELIB/ also contains relevant information about the installation of BMElib.  It is recommended to consult this website in case of updated information about the installation procedure.
 

1) Installing the BMElib source code to your machine

The BMElib source code are files written in MatLab (version 5 .3 or higher) that are organized in a directory structure.  The top directory is called BMELIB (and referred to as the "BMELIB directory" hereafter).  From the BMELIB directory there are several sub directories which contain files for the different stages of temporal geostatistics analysis.  These sub directories are as follow

BMELIB:  Top directory containing the following sub directories:
BMELIB\iolib       -  BMELIB file input/output
BMELIB\graphlib    -  BMELIB graphical functions
BMELIB\modelslib   -  BMELIB variogram and covariance models
BMELIB\statlib     -  BMELIB statistics and estimation of variograms
BMELIB\bmeprobalib -  BMELIB spatiotemporal estimation with hard and probabilistic data
BMELIB\bmeintlib   -  BMELIB spatiotemporal estimation with hard and interval data
BMELIB\bmehrlib    -  BMELIB spatiotemporal estimation with hard data only
BMELIB\simulib     -  BMELIB simulation of S/TRF realizations
BMELIB\genlib      -  BMELIB miscellaneous, general functions
BMELIB\mvnlib      -  BMELIB miscellaneous, FORTRAN routines
BMELIB\tutorlib    -  BMELIB tutorials
BMELIB\exlib       -  BMELIB examples
BMELIB\testslib    -  BMELIB test functions

Each of the above sub directories contains several source code files written in MatLab which generally have an extension of *.m.  In order to install the above directory structure to your machine, just copy the /package/BMELIB directory from the CD ROM to a directory in your computer (for example in Windows in a directory that you name C:\package\BMELIB, or in linux/unix in a directory that you name /myname/package/BMELIB/).

Alternatively instead of copying the directory structure from the CD ROM to your computer, you may use a compressed file which contains all the files in a compacted format.  Depending on your operating system, you may either use the BMELIB.zip file (for Windows users) or the BMELIB.tar.gz (for linux/unix users).  In this case follow one of the following instructions depending on your operating system:
(a) For Windows users:
Download the zipped file named BMELIB.zip .  This file was created using WinZip version 7.0 and it works well for Windows users.  Download this file or copy it from the CD ROM to a directory on your windows machine (for example in a directory that you name C:\package\BMELIB), and unzip it with WinZip 7.0 (In most cases double clicking on the file should do it). This will create the sub directories (bmeintlib, bmeprobalib, etc.) in the BMELIB directory. Note the name of your BMELIB directory (for example C:\package\BMELIB) which contains the sub directories (bmeintlib, bmeprobalib, etc.), as you will need that information to set the MatLab path to the BMElib package (see next step).
(b) For linux/unix users:
Download the tarred/zipped file named BMELIB.tar.gz .  This file was created using tar and gzip and it works well for linux/unix users.  Download this file or copy it from the CD ROM to a directory on your linux machine (for example in a directory that you name /myname/package/ ), and untar/unzip it.  In most cases typing the following two commands at the linux/unix prompt should perform the required untar/unzip:
% gunzip BMELIB.tar.gz
% tar xvf BMELIB.tar
This will create the BMELIB directory with several sub directories (bmeintlib, bmeprobalib, etc.). Note the name of this directory (for example /myname/package/BMELIB), as you will need that information to set the MatLab path to the BMElib package (see next step).


2) Setting the MatLab path for BMElib

The user is required to have MatLab (version 5.3 or higher) in order to run the BMElib package.  MatLab is is a flexible and powerful software especially designed for numerical calculus and matrix computations, and it has advanced graphics capabilities.  For general installation instructions and a detailed description of the MatLab features, the reader is referred to:

http://www.mathworks.com

After starting MatLab the user has to set the correct path in MatLab in order to be able to use the BMElib library.  This is done by using the addpath command in MatLab to add each of the BMElib sub directories to the MatLab directory search path.  This procedure is automated using a file called startup.m.  However the startup.m file provided with BMElib needs to be edited so it reflects the proper directory name where BMElib is installed.  In order to modify the startup.m file do the following steps :

i) Start MatLab:

If you are using Window, you can just double click on the MatLab icon if you have one.  If you are using linux/unix just type the following at the linux/unix prompt

% matlab

ii) Change to the BMElib directory:

Now you are in MatLab and you have the >> prompt. Using the cd command, move your current directory to the directory in which BMElib is installed. For example for Windows users, if BMElib is in C:\package\BMELIB, you might be able to just type the following at the MatLab prompt

>> cd C:
>> cd \package\BMELIB

Similarly, for linux/unix users, if BMElib is in /myname/package/BMELIB, you might be able to just type the following at the MatLab prompt

>> cd /myname/package/BMELIB/

iii) Edit the startup.m file:

In the BMElib directory, edit the file called startup.m so that it reflects the proper path to the BMElib directory on your machine.  For example, for Windows users,  if you installed BMElib in a directory called 'D:\myname\BMELIB', then replace every instances of 'C:\package\BMELIB' with 'D:\myname\BMELIB'. Similarly for linux/unix users, if you installed BMElib in the directory /myname/package/BMELIB, then replace every instances of instances of C:\package\BMELIB with /myname/package/BMELIB/.  To edit the startup.m file, you may use any text editor (such as emacs for linux/unix users), or, on most MatLab systems, you may type the following command at the MatLab prompt to use the native MatLab editor:

>> edit startup.m

iv) run the command startup.m

To run the startup command, just type startup on the MatLab prompt, as follow

>> startup

This will add the BMElib sub directories in the MatLab search path, and you should get the following message after the MatLab prompt

BMELIB search path has been set

If you get any warning or error messages, this probably means that you did not correctly do step (iv) above,  so make sure you do so before you go to the next step.

v) Exit MatLab, the BMElib path is now operational!

Once you are ready to exit MatLab just type 'exit' at the MatLab prompt, as follow

>> exit

vi) And now you can start MatLab as follow...

The next time you start MatLab, all you need to do is to change to the BMELIB directory and type startup. So go ahead and start MatLab again for the next steps of the installation.  For example in the setup described here for Windows users, you should just double click on the MatLab icon to start MatLab, and at the MatLab prompt type the following

>> cd C:
>> cd \package\BMELIB
>> startup

Similarly for linux/unix users using the setup described here, from the linux/unix prompt type the following

% matlab
>> cd /myname/package/BMELIB/
>> startup
 

3) Obtaining executable files for the BMElib Fortran routines

The mvnlib directory of the BMElib package contains some Fortran77 routines that are required by the bmeintlib and bmeprobalib mapping functions.  It is necessary to obtain executable files for these Fortran routines in order to use the mapping functions of the bmeintlib and bmeprobalib directories. There are two ways to obtain these executable files: (a) If the executables files for the mvnlib directory are available on the CD ROM (or the BMElib website) you can copy these files to the BMELIB/mvnlib directory on your machine, or (b) in all other cases, you can create the executable files by compiling the source code for the Fortran routine using a properly configured Fortran compiler for the MatLab software you are using (version 5.3 or higher).  Following are explanations for each of these cases:

(a) Using available executables files for the mvnlib directory:
Locate the directory executablesForMvnlib/ (either on the CD ROM or the BMElib website) and see if a directory is listed corresponding to the version of the MatLab and operating system you are using.  For example, the CR-ROM contains the directory /executablesForMvnlib/Matlab5.3-windows_dll which has the executables files corresponding to MatLab 5.3 and Windows. Once you have located the proper directory with the executables files for mvnlib, copy all these files from that directory to the BMELIB/mvnlib directory on your computer.

(b) In all other cases
If you cannot locate executable files for your system on the CD ROM, you need to produce the executable files by compiling the BMElib Fortran routines located in the mvnlib directory.

(b1) Linux x86 Matlab 6.0 (R.12) users
The following only applies if you are using Matlab 6.0 (Release 12). The following issue was successfully resolved in subsequent release Matlab 6.1 (release 12.1).
There is a known issue when executing Fortran code on Linux, as the compiler needs to connect to the correct libraries. This issue was resolved with Matlab upon the responce of the Mathworks technical staff on Sept. 17, 2001 to our indication of it. Please ask your Linux system administrator to perform the following steps:
i) Go to the local directory $MATLAB where Matlab is installed (e.g. /usr/local/matlab), specifically to $MATLAB/bin .
ii) Back-up the existing "mexopts.sh" file by renaming it (e.g. as "mexopts.sh.ORIG").
iii) Download the updated file mexopts.sh and save it with that name in the $MATLAB/bin directory.
According to the Mathworks people, the new option file uses the g77 compiler for linking instead of the f2c linker that causes the problem. The fix was tested successfully using Matlab version 6.0 (Release 12) on RedHat Linux versions 6.2 and 7.1. It should equally well apply to any other Linux distribution.
You may now proceed to the next subsection (b2).

(b2) All users
Change to the BMELIB/mvnlib directory and type mvnlibcompile, as follows

>> cd mvnlib
>> mvnlibcompile

This command uses the MEX utility in MatLab to compile the Fortran routines in the mvnlib directory needed for the BME estimation.  You must compile these Fortran subroutines, else the BME estimation functions will not work (but all other functions will work). If you get an error message saying that MatLab was not able to call the Fortran compiler, that means that MatLab on your system is not correctly configured to access a proper Fortran compiler. Ask your system administrator to fix this problem, by following instructions in the Application Programing Interface (API) guide. (Such as the API guide for MatLab 5.0 or the API guide for MatLab 6.0)  For example in the API guide for MatLab 5.0, page 2.5, it is stated that in order to test if MatLab is properly configured to access an allowable Fortran compiler in UNIX, you should type the following test command:

>> mex yprimef.F yprimefg.F

Follow the instructions on the API guide to verify if this test for MEX works properly. Once you are able to perform this test you should be able to compile the Fortran subroutines used by BMElib.
Various UNIX flavor users that come accross MEX compilation or installation testing problems are encouraged to try the fix suggested for Linux users in (b1) above that involves an updated MEX options file, and attempt to recompile and execute. Please note that dealing with your operating system is performed at your own risk, as the suggested fix has not been tested on all different UNIX-based operating systems.
However, once you have compiled mvnlib once, you do not need to do it again. To check that the compilation was successful you can use the MVNLIBtest function (type 'help MVNLIBtest' for more explanations, or see the testslib directory).
 

4) Testing the installation of BMElib

In order to test whether BMElib was correctly installed, use the functions of the testslib directory. Use help testslib to get a listing of the test functions available.  For example the following command test the modelslib directory.

>> MODELSLIBtest

Additionally use the following commands to test whether the executable files for the mvnlib directory were properly installed:

>> MVNLIBtest
 

5) Reproducing the examples of the book

The purpose of the version of the BMElib library included in the book is to enable the reader to reproduce some of the numerical examples of the book.  These examples are indicated with a mouse icon, and the name of the corresponding BMElib command is given in the book footnotes.  E.g., the figures of Example 3.4 in Chapter VI demonstrating the use of probabilistic data from a secondary field are reproduced using the example01.m command.  Hence to reproduce these figures, start BMElib, and at the prompt just type the following command

>> example01

To obtain a listing of all the examples provided in BMElib, you may use the BMElib help for the exlib directory, as follow

>> help exlib
 

6) Learning more about BMElib

To learn more about BMElib, you can use the tutorlib directory, and run the tutorials.  Following is a list of tutorial available in tutorlib:

Exploratory analysis:
IOLIBtutorial      - file input/output
GRAPHLIBtutorial   - graphics

Variogram models and estimation:
MODELSLIBtutorial  - variogram models
STATLIBtutorial    - statistics and variogram estimation

Spatiotemporal estimation:
BMEPROBALIBtutorial  - mapping using hard and probabilistic data
BMEINTLIBtutorial    - mapping using hard and interval data
BMEHRLIBtutorial     - mapping using hard data only

Simulation of S/TRF realizations:
SIMULIBtutorial      - Cholesky and sequential simulations

Miscellaneous functions:
GENLIBtutorial       - general use functions

To use one of these functions just type the corresponding name at MatLab prompt.  For example to do the tutorial on input/output functions, type the following at the prompt

>> IOLIBtutorial