User’s Guide

User’s Guide

用户指导

Aparapi is: An API used to express data parallel workloads in Java and  a runtime system capable of running compatible workloads on a compatible GPU.

Where your workload runs depends on

Aparapi：是一个在Java中被API用于表达数据并行工作量和一个运行时间系统在一个兼容GPU上运行兼容工作量的能力。

• Whether you have a compatible GPU and OpenCL capable device driver
• Whether your Java parallel code can be converted to OpenCL by Aparapi
• 你是否有一个兼容GPU和能够操作OpenCL的程序员。
• 你的Java并行代码是否能够通过Aparapi被转换为OpenCL。 

For information about restrictions on the code that Aparapi can convert to OpenCL, see  JavaKernelGuidelines.

信息关于在Aparaop上能够被转换为OpenCL的代码权限，查看 JavaKernelGuidelines.

Aparapi depends on AMD’s OpenCL™ driver to execute on the GPU and therefore shares the same device, driver, and platform compatibility requirements as AMD APP SDK V2.5®.

Aparapi依赖于AMD的OpenCL™程序员在GPU上执行和因此共享这个相同设备，和能够兼容AMD APP SDK V2.5®的设备。

• 32-bit Microsoft® Windows® 7
• 32-bit Microsoft® Windows Vista® SP2
• 64-bit Microsoft® Windows® 7
• 64-bit Microsoft® Windows Vista® SP2
• 32-bit Linux® OpenSUSE™ 11.2,   Ubuntu® 10.04/9.10, or Red Hat® Enterprise Linux® 5.5/5.4
• 64-bit Linux® OpenSUSE™ 11.2,   Ubuntu® 10.04/9.10, or Red Hat® Enterprise Linux® 5.5/5.4
• An OpenCL GPU and suitable OpenCL enabled device driver
• An installed AMD APP SDK v2.5 or later

If you prefer to test Aparapi in JTP mode (Java Thread Pool) then you will only need Aparapi.jar and Oracle Java 6 or later JRE or JDK.

如果你更喜欢在JTP模型（Java Thread Pool）中测试Aparapi，然后你将会仅仅需要Aparai.jar和Oracle Java 6或最新的JRE或JDK。

The following fragment of Java code takes an input float array and populates an output array with the square of each element.  

下面Java代码片段把输入float(浮点型)阵列和增加一个输出带有每个元素的平方的阵列。

final float in[8192]; // initialization of in[0..8191] omitted
final float out[in.length];

for(int i=0; i<in.length; i++){
   out[i]=in[i]*in[i];
}

This code segment illustrates an ideal data parallel candidate, each pass through the loop is independent of the others.  Traversing the loop in any order should provide the same result.

这个代码段阐明一个典型数据并行候选，每次通过这个循环是其他的独立。循环的终止条件是当任何命令提供了相同的结果。

To convert the above code to Aparapi we use an anonymous inner-class (a common Java idiom) to express the data parallel nature of the above sequential loop. 

转换上面代码为Aparapi我们使用一个匿名inner-class（一个常见的Java语句）来表达上面时序循环的数据平行本质。

Kernel kernel = new Kernel(){
   @Override public void run(){
      int i = getGlobalId();
      out[i]=in[i]*in[i];
   }
};
kernel.execute(in.length);

Java developers should recognize the general pattern as similar to that used to launch a newThread. 

Java developers应该识别一般模式作为同类被用于发起一个新的Thread。

Thread thread = new Thread(new Runnable(){
   @Override public void run(){
       System.out.println(“In another thread!”);
   }
});
thread.start();
thread.join();

The Aparapi developer extends the com.amd.aparapi.Kernel and overrides the public voidKernel.run() method. It is this Kernel.run() method that is executed in parallel.

Aparapi developer 扩展了com。amd.aparapi.Kernel和覆盖了public void Kernel.run()方法。它是这个Kernel.run()方法，其在平行中被执行。

The base class also exposes the Kernel.execute(range) method which is used to initiate the execution ofKernel.run() over the range 0...n.

Kernel.execute(range) will block until execution has completed. Any code within the overridden ‘void run()’ method of Kernel (and indeed any method or methods reachable from that method) is assumed to be data-parallel and it is the developer’s responsibility to ensure that it is. Aparapi can neither detect nor enforce this.

Within the executing kernel (on the GPU device or from the thread pool) the Kernel.getGlobalId() method is used  to identify which (of the range 0..n) a particular execution represents.

基础库也暴露了Kernel.execute(range)方法，其被用于开始Kernel.run()前面范围0...n的执行。

Kernel.execute(range)将块直到已经执行完全为止。任何代码里面被用于覆盖Kernel的'void run()'方法（并且的确任何规律或者方法的获取力来自规律）是假设为data-parallel(并行数据)和它是发展者的责任来确定。Aparapi能够不是检查也不是强迫这个。

内部执行Kernel（在GPU设备上或来自thread pool）Kernel.getGlobalId()方法被用于识别其（范围为0...n）一个细节执行代表。

Compiling an Aparapi application

编辑一个Aparapi应用程序

Aparapi has only two compilation requirements:  

Aparapi有仅仅两个编辑条件：

• Aparapi.jar must be in the class path at compile time.
• The generated class files must contain debug information (javac –g)
• Aparapi.jar 必须是在库的路径中在编写时间中。
• 产生的库文件必须含有调试信息（javac -g）

A typical compilation might be:

一个典型编辑能力是：

$ javac –g –cp ${APARAPI_DIR}/aparapi.jar Squares.java

Aparapi requires this classfile debug information so that can extract the name and scope of local variables for the generated OpenCL.

Aparapi需要这个库文件调试信息以便能够为产生的OpenCL提取逻辑变量的名称和范围。

Running an Aparapi application

运行一个Aparapi 应用程序

At runtime an Aparapi-enabled application requires aparapi.jar to be in the class path to be able to execute in a Java Thread Pool (no GPU offload).

在运行时间Aparapi-enabled 应用程序需要aparapi.jar 在库路径中能够执行一个Java Thread Pool（不是GPU解除）。

$ java–cp ${APARAPI_DIR}/aparapi.jar;. Squares

To take advantage of the GPU, the directory containing the platform-dependent Aparapi shared library is passed via thejava.library.path property.

把有利于GPU，目录含有platform-dependent(依靠平台)Aparapi共享数据库是通过viajava.library.path特性。

$ java –Djava.library.path=${APARAPI_DIR} –cp ${APARAPI_DIR}/aparapi.jar;. Squares

Aparapi detects whether the JNI shared library is available. If the library cannot be located your code will be executed using a Java Thread Pool. 

Aparapi检测JNI是否共享数据库是现有的。如果数据库不恩能够位于你的代码将会被执行使用一个Java Thread Pool。

An application can detect whether a kernel was executed on the GPU or by a Java Thread Pool (JTP) by querying the execution mode ‘after’Kernel.execute(range) has returned.  This is achieved using the Kernel.getExecutionMode() method.  

一个应用程序能够检测一个kernel是否在GPU上被执行或通过一个Java Thread Pool（JTP）通过咨询执行模型'after'Kernel.execute(range)有返回值。这是获取使用Kernel.getExecutionMode()方法。

Kernel kernel = new Kernel(){
   @Override public void run(){
      int i = getGlobalId();
      out[i]=in[i]*in[i];
   }
};
kernel.execute(in.length);
if (!kernel.getExecutionMode().equals(Kernel.EXECUTION_MODE.GPU)){
   System.out.println(“Kernel nid not execute on the GPU!”);
}

To obtain a runtime report of the execution mode of all kernel executions, set thecom.amd.aparapi.enableExecutionModeReporting property to true when the JVM is launched.

当JVM是发射器时，获取所有kernel执行的一个执行模型的运行时间报道，调整com.amd.aparapi.enableExecutionModeReporting特性来确认。

$ java –Djava.library.path=${APARAPI_DIR} –Dcom.amd.aparapi.enableExecutionModeReporting=true –cp ${APARAPI_DIR}/aparapi.jar;. Squares

Running the sample applications

运行示例应用程序

Aparapi includes two sample applications in the /samples subdirectory of the binary distribution zip file.

Aparapi包括两个示例应用程序在二进制配置的zip文件/samples subdirectory中。

samples/squares 示例/平方	simple example that computes an array of squares of integers 示例其计算一个整数阵列的平方。
samples/mandel 示例/mandel	computes and displays the Mandelbrot set 计算并显示Mandelbrot 设置

The jar file for each sample is included (so you can run a sample without having to build it) as well as both Linux® and Microsoft Windows® script files for launching the samples.

jar文件为每个示例是包括（因此你能够运行一个示例而不用组建它）Linux和Microsoft Windows 两个系统的脚本文件为发射示例一样不错。

You will need an appropriate GPU card, OpenCL® enabled Catalyst® driver and a compatible Oracle Java 6 JRE for your platform. To execute a sample:

你将会需要一个适合GPU卡片，OpenCL确认Catalyst程序猿和一个兼容Oracle Java 6 JRE作为你的平台。去执行一个示例：

• Set the environment variable JAVA_HOME to point to the root of your JRE or JDK.
• Change to the appropriate samples directory (samples/squares or samples/mandel)
• Run either the .bat or .sh script. On Linux® , you might have to initially chmod +x script.sh to add execute permissions.
• 设置环境变量JAVA_HOME，点击你的JRE或JDK的root。
• 改变为适合示例目录（示例/平方或者示例/mandel）
• 在Linux中，运行两者.bat或.sh脚本之一。你应该有最初的chmod +x script.sh来添加执行许可。

The sample scripts pass the first arg (%1 or $1) to -Dcom.amd.aparapi.executionMode when the JVM is launched.  This allows the sample to be tested in either GPU or JTP execution modes by passing the requested mode. 

示例脚本通过第一个arg(%1或$1)为 -Dcom.amd.aparapi.executionMode当JVM是开始。这个许可示例在GPU或JTP两者之一中进行测试执行方法通过需求模型。

$ cd samples/mandel
$ bash ./mandel.sh GPU
<executes in GPU mode here>
$ bash ./mandel.sh JTP
<executes in JTP mode here>

Building the sample applications

组建示例应用程序

To build a sample, install Oracle® JDK 6 and Apache Ant (at least 1.7.1).  

组建一个示例，安装上Oracle JDK 6和Apache Ant(流氓蚂蚁)（至少是版本1.7.1）。

• Set the environment variable ANT_HOME to point to the root of your ant install.
• Ensure that the %ANT_HOME%/bin or ${ANT_HOME}/bin is in your path.
• Set the environment variable JAVA_HOME to point to the root of your JDK.
• Change to the appropriate samples directory (sample/squares or sample/mandel).
• Initiate a build using ant.
• 设置环境变量ANT_HOME，点击你的蚂蚁安装的root。
• 确定%ANT_HOME%bin或者${ANT_HOME}/bin是在你的路径中的。
• 设置环境变量JAVA_HOME，点击你的JDK的root。‘
• 改变适合的示例目录（示例/平方或示例/mandel）。
• 开始一个组建使用ant。

  $ cd samples/mandel
  $ ant 
  $ bash ./mandel.sh GPU

Attribution