
=============================================================================
README file for:

Samples for the OpenCL(TM) Development Kit for Linux on Power,
version 0.3

=============================================================================
Contents:

   Copyright statement
   Overview
   Prerequisite
   Tested platforms
   Installation
   Compilation
   Notices and trademarks

=============================================================================
Copyright statement

   Licensed Materials - Property of IBM
   Copyright IBM Corporation 2011 All Rights Reserved

   US Government Users Restricted Rights - Use, duplication or
   disclosure restricted by GSA ADP Schedule Contract with IBM Corp.

==============================================================================
Overview

This OpenCL sample package includes the following OpenCL sample programs
(alphabetically ordered):

    (1) Black-Scholes Option Pricing: This sample demonstrates the
        computation of European put and call options on non-dividend-paying
        stocks. The sample is intended to showcase many different styles of
        parallel programming in OpenCL. The sample is accompanied by a perl 
        script that runs through all the different command line parameter 
        options that the Black-Scholes sample offers and determines which 
        of these option combinations would produce the best performance run
        on a particular OpenCL platform and device. 

    (2) Fluid: This sample implements a fluid solver based on the
        semi-Lagrangian method first introduced by Jos Stam in Stable Fluids.
        This work is inspired by the Physical based fluid simulation teaching 
        demo from Caltech 
        (http://www.multires.caltech.edu/teaching/demos/java/stablefluids.htm).
        
    (3) Open MPI/OpenCL 2D Jacobian Solver: This sample solves the standard 2D
        Laplace equation, an elliptical second order partial differential 
        equation with two variables. This sample demonstrates how to use 
        OpenCL together with Open MPI and the accompanying tutorial explains
        the details. The code is written for readability.  

    (4) Julia: This sample implements a 4d quaternion Julia Set ray-tracer. 
        This sample is inspired by Keenan Crane's work
        (http://www.cs.caltech.edu/~keenan/project_qjulia.html). The program
        illustrates how to port a vectorized workload to OpenCL.  It allows
        for the display of the resulting images using the OpenGL or the 
        remote viewer.

    (5) Perlin Noise: This sample is a Perlin Noise generator, which is used
        to compute a sequence of gradient noise images using a time step 
        parameter. It is based on Ken Perlin's Improved Noise implementation 
        found at (http://mrl.nyu.edu/~perlin/noise).
        This sample demonstrates a simple data-parallel algorithm that uses an
        NDRange kernel to compute each iteration of the noise function. 

    (6) Print Info: This sample program the prints all queriable platform info for 
        each platform and all queriable device info for each of the platform's 
        devices. This sample is useful in quickly discovering the attributes 
        of the platforms and their supported devices.

    (7) Sparse Matrix Vector Multiply (SpMV): This sample multiplies an input
        vector by a sparse matrix, and produces an output vector.  The format
        of the sparse matrix is designed to enable high performance 
        processing on all supported hardware platforms.  Several command line
        options allow the user to explicitly measure performance, using the
        one sample matrix provided, or any other matrix (in "Matrix Market
        format") which the user chooses to provide.  Both single and double
        precision data formats and computations are supported.

These samples exemplify some of the best practices discussed in the Best 
Practices section of the OpenCL Installation and User's Guide, and demonstrate 
various techniques of using the OpenCL framework to leverage multiple compute 
units. 

In addition to the sample programs, this package also includes the IBM developed 
OpenCL Utility Library called CLU.  CLU consists of a set of utility functions that
simplify the task of developing simple OpenCL applications. For more
information on CLU, please refer to the CLU API Reference and User's Guide
documentation in the clu directory of this sample package. 

===============================================================================
Prerequisites

The samples in this package require the following software:
   * OpenCL Development Kit for Linux on Power version 0.3
   * Open MPI 1.3.2 or greater
   * libglut and libGL (optionally for image display)

==============================================================================
Tested platforms

These samples have been tested in conjunction with the OpenCL Development Kit 
for Linux on Power version 0.3. As such, the test configurations are the same
as the Development Kit. See the OpenCL Development Kit for Linux on Power,
Installation and User's Guide for a list of tested configurations. 

===============================================================================
Installation

To install these samples, simply unzip the OpenCL-samples-0.3-0.zip package into 
a directory of your own choosing.

Ensure that the OpenCL Development Kit for Linux on Power version 0.3 was 
properly installed by following the direction in the OpenCL Installation and 
User's Guide document.

===============================================================================
Compilation

A Makefile for this package is provided that will compile all the samples. 
Simply type 'make all' at the command prompt to compile all the samples for
both 32-bit and 64-bit addressing.

The individual samples can also be compiled as a 32bit or 64bit application by
cd'ing into the <sample_name>/ppc (32 bit) or the <sample_name>/ppc64 (64 bit)
directory and typing 'make'.

===============================================================================

Notices and trademarks
     1. NOTICES

     IBM may have patents or pending patent applications covering
     subject matter described in this document. The furnishing of this
     document does not grant you any license to these patents. You can
     send license inquiries, in writing, to:

          IBM Director of Licensing
          IBM Corporation
          North Castle Drive
          Armonk, NY 10504-1785
          U.S.A.

     INTERNATIONAL BUSINESS MACHINES CORPORATION PROVIDES THIS
     PUBLICATION "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR
     IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
     NON-INFRINGEMENT, MERCHANTABILITY OR FITNESS FOR A PARTICULAR
     PURPOSE. Some states do not allow disclaimer of express or implied
     warranties in certain transactions, therefore, this statement may
     not apply to you.

     This information could include technical inaccuracies or
     typographical errors. Changes are periodically made to the
     information herein; these changes will be incorporated in new
     editions of the publication. IBM may make improvements and/ or
     changes in the product(s) and/or the program(s) described in this
     publication at any time without notice.

     Any references in this information to non-IBM Web sites are
     provided for convenience only and do not in any manner serve as an
     endorsement of those Web sites. The materials at those Web sites
     are not part of the materials for this IBM product and use of those
     Web sites is at your own risk.

     IBM may use or distribute any of the information you supply in any
     way it believes appropriate without incurring any obligation to
     you. Licensees of this program who wish to have information about
     it for the purpose of enabling: (i) the exchange of information
     between independently created programs and other programs
     (including this one) and (ii) the mutual use of the information
     which has been exchanged, should contact:

          IBM Corporation
          Software Interoperability Coordinator, Department 49XA
          3605 Highway 52 N
          Rochester, MN 55901
          U.S.A.

     Such information may be available, subject to appropriate terms and
     conditions, including in some cases, payment of a fee.

     The licensed program described in this information and all licensed
     material available for it are provided by IBM under terms of the
     IBM Customer Agreement, IBM International Program License
     Agreement, or any equivalent agreement between us.

     All statements regarding IBM's future direction or intent are
     subject to change or withdrawal without notice, and represent goals
     and objectives only. All IBM prices shown are IBM's suggested
     retail prices, are current and are subject to change without
     notice. Dealer prices may vary.

     This information is for planning purposes only. The information
     herein is subject to change before the products described become
     available. This information contains examples of data and reports
     used in daily business operations. To illustrate them as completely
     as possible, the examples include the names of individuals,
     companies, brands, and products. All of these names are fictitious
     and any similarity to the names and addresses used by an actual
     business enterprise is entirely coincidental.

    2. TRADEMARKS

     IBM and Power are trademarks or registered trademarks of International
     Business Machines Corp., registered in many jurisdictions worldwide.
     Other product and service names might be trademarks of IBM or other
     companies. A current list of IBM trademarks is available on the Web at
     "Copyright and trademark information" at www.ibm.com/legal/copytrade.shtml.

     Cell Broadband Engine is a trademark of Sony Computer
     Entertainment, Inc. in the United States, other countries, or both and
     is used under license therefrom.

     Linux is a registered trademark of Linus Torvalds in the United States,
     other countries, or both.

     SUSE is a registered trademark of Novell, Inc. in the United States and 
     other countries.

     OpenCL and the OpenCL logo are a trademarks of Apple Inc. used by permission by Khronos

     Other company, product or service names may be trademarks or
     service marks of others.

===============================================================================



