             How to run the EuroBen shared-memory benchmark.
             =============================================== 

Below you find instructions for installation and running the
shared-memory version of the EuroBen benchmark. 
In the case that you run into trouble please mail to:

             Aad van der Steen; steen@phys.uu.nl 
             -----------------------------------

The benchmark has the following structure:

              |- Makefile
              |
              |- install/
              |- basics/
              |
              |- mod1a/
              |- mod1b/
              |- mod1d/
              |- mod1e/
              |- mod1f/
eurobenV5.0/ -|
              |- mod2a/
              |- mod2as/
              |- mod2b/
              |- mod2ci/
              |- mod2cr/
              |- mod2d/
              |- mod2f/
              |- mod2g/
	      |- mod2h/
              |- mod2i/
              |
              |- mod3a/

The directories modXY/ contain the programs with all their dependent 
routines and a Makefile. See below how to deal with them. 

The Makefile in eurobenV5.0/ can be used for easy installation of the
15 programs in the EuroBen V5.0 benchmark:

mod1a  -- A test for speed of basics operations from cache (if present).
mod1b  -- A test for speed of basics operations from main memory.
mod1d  -- A test for effects of memory bank conflicts.
mod1e  -- A test for the accuracy of intrinsic mathematical functions.
mod1f  -- A test for the speed of intrinsic mathematical functions.
---------
mod2a  -- A test for the speed of the vector update c = c + Ab.
mod2as -- A test for the speed of the vector update c = c + Ab for sparse
          matrix A is CRS format.
mod2b  -- A test for the speed of solving a full linear system Ax = b.
mod2ci -- A test for the speed of solving a sparse linear non-symmetric
          system Ax = b of Finite Element type. Matrix is in CRS format.
mod2cr -- A test for the speed of solving a sparse linear symmetric
          system Ax = b stemming from a 3-D finite difference problem.
mod2d  -- A test for the speed of finding eigenvalues of a full matrix A
          (Real, symmetric).
mod2f  -- A test for the speed of a 1-D Fast Fourier Transform.
mod2g  -- A test for the speed of a 2-D Haar Wavelet Transform.
mod2h  -- A test for the speed of a random number generator.
mod2i  -- A test for the speed of sorting Integers and 64-bit Reals.
---------
mod3a  -- A test for the speed of a very sparse linear system Ax = b using
          I/O.

We assume that, at least, for the first time, you will want to run
the programs with the same compiler options. 

1) cd basics/
   1a - Modify the subroutine 'state.f' such that it reflects the state
        of the system: type of machine, compiler version, compiler
        options, OS version, etc.
   1b - Chances are less than one percent that you have to modify
        the range and precision selected for floating-point numbers.
        In fact, it is expected that the selection made there should
        lead to the 8-byte floating-point numbers as defined in the
        IEEE 754 standard. If this is not the case, modify the code
        accordingly. 
        If you do not know: do nothing, the floating-point
        representation is probably OK anyway.
   1c - OPTIONAL:
        All program directories contain the timing functions 'wclock.f'
        and 'cclock.c'. 'wclock.f' is a Fortran interface routine that
        calls 'cclock.c', which in turn relies on the 'gettimeofday'
        Unix system routine. This timer works almost everywhere (except
        under UNICOS) and delivers the wallclock time with a resolution 
        of a few microseconds. It is generally better than the
        Fortran 90 routine 'System_Clock' (only for the Compaq AlphaServerSC
        it is known to be the other way around). If, for any reason you want
        to use another/better wallclock timer, modify the Real*8
        function wclock.f in basics.
   1d - !!!IMPORTANT!!!: cd mod1a/
        Modify the file 'mod1a.cyc'. This is only one number that represents
        the clock cycle of the CPU in Hz. So, e.g. for a 1 GHz CPU adjust it
        to 1.0d9. THE SAME HOLDS FOR mod1b!!!	
         
2) Go back to eurobenV5.0/
   2a - Do a 'make state': The 'state.f' routine that you have modified is
        copied to all the program directories.
   2b - If needed (very unlikely), do a 'make numerics':The 'numerics.f' file
        containing the module that defines the range and precision for
        floating-point constants and variables is copied to all the program
        directories.
   2c - OPTIONAL:
        If you have modified 'wclock.f' in basics/, do a 'make clock':
        The 'wclock.f' routine is copied to all the program directories.

3) cd install/
   3a - In install/ you will find a header file with definitions for
        the 'make' utility.
        Modify the 'Make.Incl' such that is contains the correct name
        for the Fortran 90 compiler, Loader (usually the same as the
        compiler), and the options for the Fortran 90 compiler and the
        C compiler. For completeness' sake there are empty definitions
        for libraries (LIBS) and include files (INCS) you might want to
        use but in normal situations they are not needed.

4) Go back to eurobenV5.0/
   4a - Do a 'make make': This will cause the Makefiles in all program
        directories to be completed according to the specifications you
        made in 'install/Make.Incl'.

5) Do a 'make makeall':
   In all the program directories the programs will be compiled and the         
   executables will be made. That is to say:
   With 'make makeall' the serial version of the executables is made.
   The executable names are x.<prog> for any program <prog>.

6) Do a 'make runall': This will run all programs in turn. The results
   are placed in a directory called Log.`hostname`, where 'hostname' is
   the local name of your system. This will take again a few minutes.
   The results have names '<prog>.log' where <prog> is any of the
   programs listed above.

========================================================================
                         Timing considerations
========================================================================

Your system might be so fast that the timing resolution of the timing
routine (possibly 'wclock.f'/'cclock.c') is not sufficient for one or
some of the programs. This is indicated by an execution time in the
result file that is <= 1.0E-9 seconds or even negative, and a highly
unlikely speed of > 10E+10 M(fl)op/s. In this case do the following for
any of the programs <prog>:

7) cd <prog>/
   7a - You find in the directory '<prog>/' an input file '<prog>.in'.
        This file describes the problem sizes and the repeat count
        for the problems to be run. The last column is the repeat
        count. Increase the repeat counts to values you think
        appropriate.
   7b - Do an 'x.all': this runs the program and writes the result to
        '<prog>.log'.
   7c1 - mv <prog>.log ../Log.hostname/ or,
   7c2 - ATERNATIVELY, when you have run several programs with
         altered repeat counts:
         a. cd ..
         b. Do a 'make collect': this causes any result file 
            '<prog>.log' to be moved from the '<prog>/' directories
            to 'Log.hostname/'.

========================================================================
                   Customising the runs: (OPTIONAL)
========================================================================
You might want to run some of the programs with other than the
standard compiler options as specified in the procedure above.
In that case do the following for any of the programs <prog>:

8) cd <prog>/
   8a - Modify the definition of 'FFLAGS' in the Makefile.
   8b - Modify the compiler options line in subroutine 'state.f'.
   8c - Do a 'make veryclean': this will remove all old objects and
        the excutable.
   8d - Do a 'make'  to generate the new executable.

9) Run the resulting program x.<prog>:
   9a - Do an 'x.all': this runs the program and writes the result to
        '<prog>.log'. When several runs are done before the '<prog>.log'
        file is moved to the '/Log.hostname/' directory (see below)
        later results are appended to the '<prog>.log' file.
   9b1 - mv <prog>.log ../Log.hostname/ or,
   9b2 - ATERNATIVELY, when you have run several programs with
         customised compiler options:
         a. cd ..
         b. Do a 'make collect': this causes any result file 
            '<prog>.log' to be moved from the '<prog>/' directories
            to 'Log.hostname/'.
	    
10) If you want to use other problem sizes than initially defined in the
    <prog> directories you will find a file '<prog>.in' in each directory
    (except in 'mod1e' and 'mod1f', where this does not make much sense). In
    the '<prog>.in' files are the size parameters and often repeat counts for
    making the timing more reliable. Change the '<prog>.in' file(s) according
    to your wishes and rerun the program(s) as described under 9).    

                         =====================
                         | Best of success!! |
                         =====================

