Making the GRASP binaries and libraries

To make the GRASP libraries and executables described in this manual, please follow these directions. It should only take a few minutes to do this.

1. Within the main GRASP directory is a file called SiteSpecific. Make a copy of SiteSpecific called SiteSpecific.save. This way, if you mess up the installation, you can start over easily. (Alternatively, copy SiteSpecific to a file called SiteSpecific.mysite and, everywhere below, when we refer to editing the SiteSpecific file, edit SiteSpecific.mysite instead.) Note: you can find a number of example SiteSpecific files in the directory Examples_SiteSpecific/ . These are for different installation sites and machine types (Sun, DEC, Intel Paragon, IBM SP2, Linux) - you may find them helpful if you are stuck or the instructions below are ambiguous or unclear. Once you have customized the SiteSpecific file for your own installation, if you wish you can email it to us and we will include it in future releases of GRASP.
2. Now edit SiteSpecific so that GRASP_HOME has the correct path, for example
   GRASP_HOME=/usr/local/GRASP.
   This must be the name of the directory on your system in which GRASP resides. If you are not the superuser and are installing GRASP only for your own use, you can set this path to point somewhere in your own home directory, and install GRASP there.
3. Find out where Numerical Recipes in C is installed on your system. Within SiteSpecific set RECIPES_LIB to point to the directory containing these libraries. For example
   RECIPES_LIB=/usr/local/numerical_recipes/lib.
   If Numerical Recipes in C is not installed on your system, you will have to obtain a copy, and install it, following the directions to create the library file librecipes_c.a. Note that as described above, you might also want to create debugging libraries librecipes_cg.a and profiling libraries librecipes_cp.a.
4. Within SiteSpecific set LRECIPES to the name of the Numerical Recipes in C library you wish to use, for example
   LRECIPES=recipes_c.
5. If you intend to use the MPI code, set BUILD_MPI= true, otherwise set it to false. In this latter case, any MPI-specific defines are ignored, and no code that makes use of MPI/MPE function calls is compiled. (This is a shame - these are some of the nicest programs in the GRASP package. We urge you to reconsider building the mpich package on your system!)
6. Within SiteSpecific set MPI_LIBS to point to the directory containing the MPI/MPE libraries, and to specify the names of the link archives, for example
   MPI_LIB=-L/usr/local/mpi/lib -lmpi -lmpe.
   Note that if you use the version of mpicc which is distributed with mpich you may not need to have any of the MPI libraries referenced here; the compiler may find them automatically.
7. Within SiteSpecific set MPI_INCLUDES to point to the directory which contains the MPI and MPE header (*.h) files, for example
   MPI_INCLUDES = -I/usr/local/mpi/include.
8. Within SiteSpecific set MPICC to the name of your local MPI C compiler, for example:
   MPICC = /usr/local/bin/mpicc.
   You can include any compilation flags (say, -g) on this line also.
9. If you have the MESA or GL library installed set HAVE_GL= true, otherwise set it to false. In this latter case, the routines making GL/MESA calls will not be compiled.
10. Within SiteSpecific set GL_LIBS to point to the directory containing the GL/MESA libraries, and to specify the names of the link archives, for example
    GL_LIBS= -L/usr/local/lib -lMesaGLU -lMesaGL $(XLIBS).
    Note that the functions in the MESA/GL library make calls to the X library and you will have to specify the location of the X libraries for example
    XLIBS = -L/usr/X11/lib -L/usr/X11R6/lib -lX11 -lXext -lXmu -lXt -lXi -lSM -lICE .
11. Within SiteSpecific set GL_I to point to the directory which contains the GL/MESA header (*.h) files, for example
    GL_I = -I/usr/local/include/GL.
12. If you intend to use CLAPACK, set WITH_CLAPACK = true, otherwise set it to false. Within SiteSpecific set CLAPACK_LIB to point to the directory containing the CLAPACK libraries and LCLAPACK and LBLAS to the (platform-specific) names of the clapack and blas libraries respectively excluding the leading `lib'. Further set F2C_LIB to point to the directory containing the f2c libraries and F2C_INC to point to the directory containing the f2c.h include file.
13. If you intend to use the FRAME code, set BUILD_FRAME = true, otherwise set it to false. In this latter case, any FRAME-specific defines are ignored, and no code that makes use of FRAME function calls is compiled.
14. Within SiteSpecific set FRAME_DIR to point to the directory which contains the LIGO/VIRGO format FRAME software, for example
    FRAME_DIR=/usr/local/frame.
    This directory should contain lib/libFrame.a and include/FrameL.h. If you don't need the FRAME libraries, just leave this entry blank.
15. Within SiteSpecific, if you want to use GRASP for real-time analysis in the Caltech 40-meter lab, set EPICS_INCLUDES to point to the directory containing the EPICS *.h include files, and set EPICS_LIBS to point to the directory containig the EPICS libraries. Finally, you need to uncomment the BUILD_REALTIME define statement. If you do not intend to use your GRASP installation for real-time analysis in the 40-meter lab, simply leave these three definitions commented out with a hash sign (#).
16. At the bottom of SiteSpecific are several define statements, which are currently commented out. These are primarily intended for production code; by undefining these lines you replace a cube root function and some trig functions in the code with faster (but less accurate) in-line approximations. We suggest that you leave these commented out. (You might want to consider uncommenting them if you are burning thousands of node hours on a large parallel machine - but you do so at your own risk!)
17. There are also lines that are currently commented out, which allow you to overload functions defined in the libraries and reference libraries of optimized functions. Once again, leave these commented out unless you want to replace standard Numerical Recipes functions with optimized versions. Currently, we support several sets of optimized libraries:
    • The CLASSPACK optimized FFT's for the Intel Paragon.
    • The Sun Performance Library's optimized FFT for the Sun SPARC architecture. Note: believe it or not, this is slower than the public domain equivalent. We recommend that you use the FFTW package instead!
    • The Cray/SGI optimized FFT for the RS10000 and other MIPS architectures. Note: believe it or not, this is slower than the public domain equivalent. We recommend that you use the FFTW package instead!
    • The DEC extended math library (DXML) optimized FFT for the DEC AXP architecture. [This is slightly faster, or slightly slower, than FFTW, depending upon the array size.]
    • The FFTW (Fastest Fourier Transform in the West), which will run on any computer. This is a public domain optimized FFT package, available from the web site:
      http://www.fftw.org/.http://www.fftw.org/ If you don't have an optimized FFT routine for your computer, we highly recommend this - it is a factor of three (or more) faster than Numerical Recipes. We include glue routines for both FFTW version 1 and version 2. The latter is simpler to install and fractionally more efficient.
    • The IBM Extended Scientific Subroutine Library (ESSL) optimized FFT routine. Note: this has only been tested on the IBM SP2 machine.
    Further details may be found in the src/optimization subdirectory of GRASP. If you want to use these optimized library routines, first go into the appropriate subdirectory of src/optimization and build the optimized library routine using the makefiles's that you find there, then uncomment the appropriate lines in SiteSpecific and follow the instructions given here.
18. To install the Gravitational Radiation Toolbox which provides an interface between GRASP and Matlab, comment out the line BUILD_GRTOOLBOX = false and uncomment BUILD_GRTOOLBOX = true. Then edit the variables MEX, MEXFLAGS, and EXT appropriately. You will then have add the directories src/GRtoolbox and src/examples/examples_GRtoolbox to your Matlab path.
19. Now, in the top level GRASP directory, execute the shell script InstallGRASP, by typing the commands:
    chmod +x InstallGRASP
    ./InstallGRASP SiteSpecific (or SiteSpecific.mysite if appropriate)
    From here on, the remainder of the installation should proceed automatically. The InstallGRASP script takes information contained in the SiteSpecific file (or in the file named in the first argument of InstallGRASP such as SiteSpecific.mysite) and uses it to create Makefile's in each src subdirectory, and runs make in each of those directories.
20. If you want to ``uninstall'' GRASP so that you can begin the installation procedure again, cleanly, a script has been provided for this purpose. To execute it, type:
    ./RemoveGRASP
    and wait until the script reports that it has finished. Note: when you have sucessfully completed this process, please email us a copy of your SiteSpecific file and we will put it into the Examples_SiteSpecific/ directory of future GRASP releases.

The Makefile in each directory is constructed by concatenating the file named in the first argument of InstallGRASP (typically SiteSpecific) with a file called Makefile.tail in each individual directory. If you want to try changing the compilation procedure, you can modify the Makefile in a given directory. However this will be created each time that you run InstallGRASP; for changes to become permanent they should either be made in SiteSpecific or in the Makefile.tail's.

Note that this installation procedure and code has been tested on the following types of machines: Sun 4 (Solaris), DEC AXP (OSF), IBM SP2 (AIX), HP 700 (HPUX), Intel (Linux), Intel Paragon. There is a problem on some SGI (IRIX) machines. If you get error messages reading:

   ...
   if: Expression Syntax.
   *** Error code 1 (bu21)
   GRASP did NOT complete installation successfully

this can be fixed by setting the shell to bash before running InstallGRASP:

   SGI> setenv SHELL /usr/local/bin/bash
   SGI> ./InstallGRASP SiteSpecific

If you run into problems with our installation scripts, please let us know so that we can fix them.

If you want to experiment with GRASP or to write code of your own, a good way to start is to copy the Makefile and the example (*.c) programs from the src/examples directory into a directory of your own. You can then edit one of the example programs, and type ``make" within your directory to compile a modified version of the program.

If you wish to modify the code and libraries distributed with GRASP (in other words, modify the functions described in this manual!) the best idea is to use cp -r to recursively copy the entire GRASP directory structure (and all associated files) into a private directory which you own. You can then install your personal copy of GRASP, by following the directions above. This will permit you to modify source code within any of the src subdirectories; typing make within that directory will automatically re-build the GRASP libraries that you are using. By the way, if you are modifying these functions to fix bugs or repair problems, or if you have a ``better way" of doing something, please let us know so that we can consider incorporating those changes in the general GRASP distribution.