
SLBM USER'S MANUAL - Version 2.8, January 13, 2012

==================================================================================================
SYSTEM REQUIREMENTS 

The following subsections describe the compilers required to build SLBM on the three 
platforms that are currently supported.

Linux:

gcc for C/C++ compilation
gfortran for fortran compilation
Java 1.6

Mac OS X:

gcc version 4.2.1 delivered with XCode version 3 or greater for C/C++ compilation
gfortran for fortran compilation
Java 1.6

Solaris:

cc for C compilation
CC for C++ compilation
f95 for Fortran compilation
Java 1.6
GNU make (gmake) (not Sun's version of make)

Configurations on which the code has been tested:

RedHat Linux (2.6.18) with gcc 4.1.2 (includes gfortran) and Java 1.6
Solaris 10 (with SunOS version 5.10) with cc/CC compilers and Java 1.6
Mac OS X (10.6.8) with gcc version 4.2.1 and gfortran 4.2.1 
  (gfortran obtained from http://r.research.att.com/tools/)


==================================================================================================
BUILD INSTRUCTIONS

SLBM_Root can be downloaded with prebuilt binaries for Red Hat Linux, SunOS, or Macs, or it 
can be downloaded without prebuilt binaries.  Source code is included with all downloads, 
so it is possible for users to compile the code regardless of which package was downloaded.

All downloaded packages come with prebuilt jar files for the java interface and the java 
test program.  Those jar files will run on all platforms that support the Java Virtual Machine.  
Users do not have to build those jar files.

SLBM_Root libraries and test programs are compiled using the makefile found in the main 
SLBM_Root directory.  If you downloaded a version of SLBM_Root with precompiled binaries for 
your platform, and the regression test for the interface language you want to use passes 
without error, then you don't need to compile the program.

The following targets in the make file build the indicated components:

Note: On Sun OS, you must use "gmake" instead of "make".

make all          build all C++, C and Fortran libraries and tests, and the Java JNI library.  
                  Does not build Java jar files.

make cc           the main C++ library and the C++ test program
make c            the C interface library and the C test program
make fortran      the fortran interface library and the fortran test program
make javajni      the java native interface (JNI) library (code is in C++)

make javajar      slbmjni.jar file.  Users don't generally need to do this since the java
                  jar files are delivered with SLBM_Root and should run on all platforms.

make slbmcc       only the main C++ library
make slbmcshell   only the C interface library
make slbmfshell   only the fortran interface library
make slbmjni      only the java native interface (JNI) library (C++ code)

make testcc       only the C++ test program
make testc        only the C test program
make testfort     only the fortran test program
make testjava     only the java test program.  Users don't generally need to do this since 
                  the java jar files are delivered with SLBM_Root and should run on all platforms.

make cleanobjs	  clean all previously built object files

Note that nothing will work unless the main C++ library builds successfully.

==================================================================================================
ENVIRONMENT VARIABLES

Add {INSTALL_DIRECTORY}/SLBM_Root/bin to your $PATH

Add {INSTALL_DIRECTORY}/SLBM_Root/lib to your $LD_LIBRARY_PATH 
(on a Mac: $DYLD_LIBRARY_PATH)

where {INSTALL_DIRECTORY} is the location where you installed SLBM_Root. 

$JAVA_HOME must be set properly in order to compile the JNI library

==================================================================================================
REGRESSION TESTS

Regression tests can be run using the make file in SLBM_Root directory:

make slbmtest        run all the regression tests: C++, C, fortran and java

make slbmtestcc      run only the C++ test
make slbmtestc       run only the C test
make slbmtestfort    run only the fortune test
make slbmtestjava    run only the java test

or they can be run directly from the command line (from SLBM_Root directory):

slbmtestfort
slbmtestc models/rstt201404um.geotess models/rstt201404um.regression.dat
slbmtestcc models/rstt201404um.geotess models/rstt201404um.regression.dat
java -jar bin/slbmtest.jar models/rstt201404um.geotess models/rstt201404um.regression.dat

Each test should indicate a "PASSED" result.

==================================================================================================
SINGLE PATH TESTS

There is a Single Path Test for C++, C and Java, but not for Fortran.

In general, each test expects either 2 or 8 command line parameters, described below:

2 parameters - run the regression tests described above:

    1: directory where the slbm velocity model is located

    2: file containing the regression test data

    If running this program from SLBM_Root, try:
    bin/slbmtestcc models/rstt201404um.geotess models/rstt201404um.regression.dat
 
8 parameters - run a single path test:

    1: directory where the slbm velocity model is located

    2: phase (one of Pn, Sn, Pg, Lg)

    3: source latitude in degees

    4: source longitude in degrees

    5: source depth in km below sea level

    6: receiver latitude in degees

    7: receiver longitude in degrees

    8: receiver DEPTH (!!!) in km BELOW sea level

    If running this program from SLBM_Root, try:
    bin/slbmtestcc models/rstt201404um.geotess Pn 10 20 5 15 25 -0.1

==================================================================================================
SLBM_ROOT DIRECTORY STRUCTURE

Within the main "SLBM_Root" directory, you will find the following directories:

bin: contains executables for tests in all 4 interface languages

lib: contains the libraries (.so and .jar files)

doc: contains the documentation files

SLBM: the main C++ library

SLBM/models: the earth model(s)

SLBM_C_shell: the C interface to the SLBM library

SLBM_Fort_shell: the FORTRAN interface to the SLBM library

SLBM_JNI: the Java Native Interface to the SLBM library

SLBM_test_c: code to test the c shell interface

SLBM_test_cc: code to test the c++ code

SLBM_test_fort: code to test the FORTRAN interface

SLBM_test_java: code to test the Java Native Interface

==================================================================================================
SOURCE CODE DOCUMENTATION

Each interface has its own documentation, all of which can be viewed using any HTML browser.

Links to the documentation for all four language interfaces can be found in 
SLBM_Root/doc/source_code_documentation.html

The documentation for individual language interfaces is found in the following directories:

C++: SLBM_Root/SLBM/doc/html/index.html

C: SLBM_Root/SLBM_C_shell/doc/html/index.html

FORTRAN: SLBM_Root/SLBM_Fort_shell/doc/html/index.html

Java: SLBM_Root/SLBM_JNI/java/SlbmInterface/doc/index.html

==================================================================================================
CONTACT INFORMATION

For questions/issues/comments about the software:

Andre Encarnacao, avencar@sandia.gov
Sandy Ballard, sballar@sandia.gov

For questions/issues/comments about the results returned by RSTT:

Steve Myers, smyers@llnl.gov
Mike Begnaud, mbegnaud@lanl.gov


