Get Started with the Intel® oneAPI DPC++ Library

ID 768911
Date 3/30/2023
Public

A newer version of this document is available. Customers should click here to go to the newest version.

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.

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:

dpcpp test.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:

dpcpp test.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.