Get Started with the Intel® oneAPI DPC++ Library

ID 768911
Date 3/22/2024
Public

Get Started with the Intel® oneAPI DPC++ Library

Intel® 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

Intel® oneAPI DPC++ Library Guide

Refer to the oneDPL guide for more in depth information.

System Requirements

Check system requirements before you install oneDPL.

Intel® oneAPI DPC++ Library Release Notes

Check the release notes to learn about updates in the latest release.

oneDPL Samples

Learn how to use oneDPL with samples.

Layers for Yocto* Project

Add oneAPI components to a Yocto project build using the meta-intel layers.

oneAPI Samples Catalog

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.