Get Started with the oneAPI DPC++ Library
Contents
Get Started with the oneAPI DPC++ Library¶
oneAPI DPC++ Library (oneDPL) works with the Intel® oneAPI DPC++/C++ Compiler to provide high-productivity APIs to developers, which can minimize SYCL* programming efforts across devices for high performance parallel applications.
oneDPL consists of the following components:
Parallel API
API for SYCL Kernels
Macros
For general information about oneDPL, visit the oneDPL GitHub* repository, or visit the Intel® oneAPI DPC++ Library Guide and the Intel® oneAPI DPC++ Library main page.
Quick Start¶
Installation¶
Visit the oneDPL Release Notes page for:
Where to Find the Release
Overview
New Features
Fixed Issues
Known Issues and Limitations
Install the Intel® oneAPI Base Toolkit (Base Kit) to use oneDPL.
To use Parallel API, include the corresponding header files in your source code.
All oneDPL header files are in the oneapi/dpl directory. Use #include <oneapi/dpl/…> to include them.
oneDPL uses the namespace oneapi::dpl for most its classes and functions.
To use tested C++ standard APIs, you need to include the corresponding C++ standard header files
and use the std namespace.
CMake Support¶
CMake generates build scripts which can then be used to build and link your application. oneDPL can be added to your project via CMake.
A simple example for Linux is provided below. For more detailed usage and options including details specific to Windows, please look to the CMake Support Page.
Simple Example CMake File¶
To use oneDPL with CMake, create a CMakeLists.txt file for your project’s base directory and use find_package and target_link_libraries to add oneDPL. For example:
project(Foo)
add_executable(foo foo.cpp)
# Search to find oneDPL
find_package(oneDPL REQUIRED)
# Connect oneDPL to foo
target_link_libraries(foo oneDPL)
Simple Example CMake Invocation¶
The following is an example CMake invocation which generates build scripts for the project in the parent directory:
mkdir build && cd build
cmake -DCMAKE_CXX_COMPILER=icpx -DCMAKE_BUILD_TYPE=release ..
Example Build Command¶
Once build scripts have been generated for your desired configuration following the instruction above, a build command can be issued to build your project:
cmake --build .
pkg-config Support¶
The pkg-config program is used to retrieve information about your installed libraries, and to compile and link against one or more libraries.
Use pkg-config with oneDPL¶
Use pkg-config with the --cflags flag to get the include path to the oneDPL directory:
icpx -fsycl foo.cpp $(pkg-config --cflags dpl)
The --msvc-syntax flag is required when you use a Microsoft Visual C++* compiler.
This flag converts your compiling and linking flags to the appropriate form:
icpx -fsycl foo.cpp $(pkg-config --msvc-syntax --cflags dpl)
Note
Use the pkg-config tool to get rid of large hard-coded paths and make compilation more portable.
Usage Examples¶
oneDPL sample code is available from the oneAPI GitHub samples repository. Each sample includes a readme with build instructions.
<oneapi/dpl/random> Header Usage Example¶
This example illustrates oneDPL random number generator usage. The sample below shows you how to create an random number generator engine object (the source of pseudo-randomness), a distribution object (specifying the desired probability distribution), and how to generate the random numbers themselves. Random number generation is performed in a vectorized manner to improve the speed of your computations.
This example performs its computations on your default SYCL device. You can set the
SYCL_DEVICE_TYPE environment variable to CPU or GPU.
template<int VecSize>
void random_fill(float* usmptr, std::size_t n) {
auto zero = oneapi::dpl::counting_iterator<std::size_t>(0);
std::for_each(oneapi::dpl::execution::dpcpp_default,
zero, zero + n/VecSize,
[usmptr](std::size_t i) {
auto offset = i * VecSize;
oneapi::dpl::minstd_rand_vec<VecSize> engine(seed, offset);
oneapi::dpl::uniform_real_distribution<sycl::vec<float, VecSize>> distr;
auto res = distr(engine);
res.store(i, sycl::global_ptr<float>(usmptr));
});
}
Pi Benchmark Usage Example¶
This example uses a Monte Carlo method to estimate the value of π. The basic idea is to generate random points within a square, and to check what fraction of these random points lie in a quarter-circle inscribed within that square. The expected value is the ratio of the areas of the quarter-circle and the square (π/4). You can take the observed fraction of points in the quarter-circle as an estimate of π/4.
This example shows you how to create an random number generator engine object (the source of pseudo-randomness), a distribution object (specifying the desired probability distribution), generate the random numbers themselves, and then perform a reduction to count quantity of points that fit into the square S. Random number generation is performed in scalar manner to simplify your code.
float estimated_pi;
{
sycl::queue q(sycl::gpu_selector_v);
auto policy = oneapi::dpl::execution::make_device_policy(q);
float sum = std::transform_reduce( policy,
oneapi::dpl::counting_iterator<int>(0),
oneapi::dpl::counting_iterator<int>(N),
0.0f,
std::plus<float>{},
[=](int n){
float local_sum = 0.0f;
oneapi::dpl::minstd_rand engine(SEED, n * ITER * 2);
oneapi::dpl::uniform_real_distribution<float> distr;
for(int i = 0; i < ITER; ++i) {
float x = distr(engine);
float y = distr(engine);
if (x * x + y * y <= 1.0)
local_sum += 1.0;
}
return local_sum / (float)ITER;
}
);
estimated_pi = 4.0f * (float)sum / N;
}
Find More¶
Resource Link |
Description |
|---|---|
Refer to the oneDPL guide for more in depth information. |
|
Check system requirements before you install oneDPL. |
|
Check the release notes to learn about updates in the latest release. |
|
Learn how to use oneDPL with samples. |
|
Add oneAPI components to a Yocto project build using the meta-intel layers. |