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)

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