Copyright (c) 2013, Intel Corporation

Redistribution and use in source and binary forms, with or without 
modification, are permitted provided that the following conditions 
are met:

    * Redistributions of source code must retain the above copyright 
      notice, this list of conditions and the following disclaimer.
    * Redistributions in binary form must reproduce the above 
      copyright notice, this list of conditions and the following 
      disclaimer in the documentation and/or other materials provided 
      with the distribution.
    * Neither the name of Intel Corporation nor the names of its 
      contributors may be used to endorse or promote products 
      derived from this software without specific prior written 
      permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS 
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT 
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS 
FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE 
COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, 
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, 
BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 
POSSIBILITY OF SUCH DAMAGE.

******************************************************************

This suite contains a number of kernel operations, called Parallel
Research Kernels, plus a simple build environment intended for Linux. 

These programs must not be used as benchmarks.  They are operations to 
explore features of a hardware platform, but they do not define  
fixed problems that can be used to rank systems.  Furthermore
they have not been optimimzed for the features of any particular system.

Note that while our "nstream" operations are based on the well
known STREAM benchmark by John D. McCalpin, we modified the source 
code and do not follow the run-rules associated with this benchmark.
Hence, according to the rules defined in the STREAM license (see 
clause 3b), you must never report the results of our nstream 
operations as official "STREAM Benchmark" results. The results must 
be clearly labled whenever they are published.  Examples of proper 
labelling include: 

      "tuned STREAM benchmark results" 
      "based on a variant of the STREAM benchmark code" 

Other comparable, clear, and reasonable labelling is acceptable.

To build the codes the user needs to make certain changes by editing text
files. Assuming the source tree is untarred in directory HOME, the
following file needs to be edited:

HOME/common/make.defs -- This file specifies the names of the C
compiler (CC), and of the MPI (Message Passing Interface) compiler MPICC
or compile script. If MPI is not going to be used, the user can ignore
the value of MPICC. The compilers should already be in your path. That
is, if you define "CC=icc," then typing "which icc" should show a
valid path where the compiler is installed.

The suite of kernels currently has parallel implementations in OpenMP,
and MPI. There is also a serial reference implementation

Global make
-----------

Type "make all" in the root directory to build all kernels.
Type "make allopenmp" in the root directory to build all OpenMP kernels.
Type "make allmpi" in the root directory to build all MPI kernels.
Type "make allserial" in the root directory to build all serial kernels.

The global make process uses a single set of optimization flags for all
kernels. For more control, the user should consider individual makes
(see below), carefully choosing the right parameters in each Makefile.
If a a single set of optimization flags different from the default is
desired, the command line can be adjusted:
"make all/allopenmp/allmpi/allserial default_opt_flags=<list of optimization flags>" 

The global make process uses some defaults for the Branch kernel
(see Makefile in that directory). These can be overridden by adjusting
the command line: 
"make all/allopenmp/allmpi/allserial matrix_rank=<n> number_of_functions=<m>"
Note that no new values for "matrix_rank" or "number_of_functions" will
be used unless a "make veryclean" has been issued.

Individual make
---------------
Descend into the desired sub-tree and cd to the kernel(s) of interest. 
Each kernel has its own Makefile. There are a number of parameters 
that determine the behavior of the kernel that need to be known at 
compile time. These are explained succinctly in the Makefile itself. Edit 
the Makefile to activate certain parameters, and/or to set their values.

Typing "make" without parameters in each leaf directory will prompt
the user for the correct parameter syntax. Once the code has been
built, typing the name of the executable without any parameters will 
prompt the user for the correct parameter syntax.

Running test suite
------------------
After the desired kernels have been built, they can be tested by
executing scripts in the Run subdirectory from the root of the
kernels package. Only very small examples are provided that should
complete in just a few seconds. Only a few parameters can be changed
globally; for rigorous testing, the user should run each kernel 
individually, carefully choosing the right parameters. This may involve 
editing the individual Makefile and rerunning  the code.

Example build and run
---------------------
make all default_opt_flags="-xP -restrict" matrix_rank=7 number_of_functions=200
./Run/smallOPENMP
./Run/smallMPI
./Run/smallserial