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 documentation for the Intel® oneAPI DPC++/C++ Compiler.
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. |
|
Explore the complete list of oneAPI code samples in the oneAPI Samples Catalog (GitHub*). These samples were designed to help you develop, offload, and optimize multiarchitecture applications targeting CPUs, GPUs, and FPGAs. |