Get Started

Installation

You can obtain the latest version of oneDAL:

Before You Begin

oneDAL is located in <install_dir>/daal directory where <install_dir> is the directory in which Intel® oneAPI Toolkit was installed.

The current version of oneDAL with DPC++ is available for Linux* and Windows* 64-bit operating systems. The prebuilt oneDAL libraries can be found in the <install_dir>/daal/<version>/redist directory.

The dependencies needed to build examples with DPC++ extensions API are:

  • C/C++ Compiler with C++11 support (or C++14 support on Windows*)

  • Intel® oneAPI DPC++ Compiler 2019 August release or later (for DPC++ support)

  • OpenCL™ runtime 1.2 or later (to run the DPC++ runtime)

  • GNU* Make on Linux*, nmake on Windows*

Basic Usage Scenario

Below you can find a typical workflow of using oneDAL algorithm on GPU. The example is provided for Principal Component Analysis algorithm (PCA).

The following steps depict how to:

  • Pass the data

  • Initialize the algorithm

  • Request statistics to be calculated (means, variances, eigenvalues)

  • Compute results

  • Get calculated eigenvalues and eigenvectors

  1. Include the following header file to enable the DPC++ interface for oneDAL:

    #include "daal_sycl.h"
    
  2. Create a DPC++ queue with the desired device selector. In this case, GPU selector is used:

    cl::sycl::queue queue { cl::sycl::gpu_selector() };
    
  3. Create an execution context from the DPC++ queue and set up as the default for all algorithms. The execution context is the oneDAL concept that is intended for delivering queue and device information to the algorithm kernel:

    daal::services::Environment::getInstance()->setDefaultExecutionContext(
          daal::services::SyclExecutionContext(queue) );
  4. Create a DPC++ buffer from the data allocated on host:

    constexpr size_t nRows = 10;
    constexpr size_t nCols = 5;
    const float dataHost[] = {
           0.42, -0.88,  0.46,  0.04, -0.86,
          -0.74, -0.59,  0.42, -1.44, -0.40,
          -1.45,  1.07, -1.00, -0.29,  0.35,
          -0.67,  0.20,  0.47, -1.07,  0.71,
          -1.19,  0.20,  0.84, -0.26,  1.47,
          -1.87, -0.94, -1.16, -0.64, -2.10,
          -0.65, -0.40, -1.88, -0.48,  0.70,
          -0.52, -0.34, -1.48, -0.63, -0.87,
          -0.74, -0.46,  1.07,  0.65, -1.68,
           0.94,  1.88, -0.73, -1.16,  0.10
    };
    auto dataBuffer = cl::sycl::buffer<float, 1>(dataHost, nCols * nRows);
    
  5. Create a DPC++ numeric table from a DPC++ buffer. DPC++ numeric table is a new concept introduced as a part of DPC++ interfaces to work with data stored in DPC++ buffer. It implements an interface of a classical numeric table acting as an adapter between DPC++ and oneDAL APIs for data representation. See SYCL* Numeric Tables for more details.

    auto data = daal::data_management::SyclHomogenNumericTable<float>::create(
          dataBuffer, nCols, nRows);
  6. Create an algorithm object, configure its parameters, set up input data, and run the computations.

    daal::algorithms::pca::Batch<float> pca;
    
    pca.parameter.nComponents = 3;
    pca.parameter.resultsToCompute = daal::algorithms::pca::mean |
    daal::algorithms::pca::variance |
    daal::algorithms::pca::eigenvalue;
    pca.input.set(daal::algorithms::pca::data, data);
    
    pca.compute();
  7. Get the algorithm result:

    auto result = pca.getResult();
    NumericTablePtr eigenvalues = result->get(daal::algorithms::pca::eigenvalues);
    NumericTablePtr eigenvectors = result->get(daal::algorithms::pca::eigenvectors);
  8. Get the raw data as DPC++ buffer from the resulting numeric tables:

    const size_t startRowIndex = 0;
    const size_t numberOfRows = eigenvectors->getNumberOfRows();
    
    BlockDescriptor<float> block;
    eigenvectors->getBlockOfRows(startRowIndex, numberOfRows, readOnly, block);
    
    cl::sycl::buffer<float, 1> buffer = block.getBuffer().toSycl();
    
    eigenvectors->releaseBlockOfRows(block);
    

At the end of the stage, the resulting numeric tables can be used as an input for another algorithm, or the buffer can be passed to the user-defined kernel.

Build and Run Examples

Perform the following steps to build and run examples demonstrating the basic usage scenarios of oneDAL with SYCL*. Go to <install_dir>/daal/<version> and then set up an environment as shown in the example below:

Note

All content below that starts with # is considered a comment and should not be run with the code.

  1. Set up the required environment for oneDAL (variables such as CPATH, LIBRARY_PATH, and LD_LIBRARY_PATH):

On Linux, there are two possible ways to set up the required environment: via vars.sh script or via modulefiles.

  • Setting up oneDAL environment via vars.sh script

    Run the following command:

    source ./env/vars.sh
    
  • Setting up oneDAL environment via modulefiles

    1. Initialize modules:

    source $MODULESHOME/init/bash
    

    Note

    Refer to Environment Modules documentation for details.

    1. Provide modules with a path to the modulefiles directory:

    module use ./modulefiles
    
    1. Run the module:

    module load dal
    

Run the following command:

/env/vars.bat
  1. Copy ./examples/cpp_sycl to a writable directory if necessary:

# If necessary, copy ./examples/cpp_sycl to a writable directory (since it creates temporary files)
cp –r ./examples/cpp_sycl ${WRITABLE_DIR}
  1. Set up the compiler environment for Intel® oneAPI DPC++ Compiler. See Get Started with Intel® oneAPI DPC++ Compiler for details.

  2. Build and run DPC++ examples:

Note

You need to have write permissions to the examples folder to build examples, and execute permissions to run them. Otherwise, you need to copy cpp_sycl and data folders to the directory with right permissions. These two folders must be retained in the same directory level relative to each other.

# Navigate to DPC++ examples directory and build examples
cd /examples/cpp_sycl
make sointel64 example=cor_dense_batch # This will compile and run Correlation example using Intel(R) oneAPI DPC++ Compiler
make sointel64 mode=build                          # This will compile all DPC++ examples
# Navigate to DPC++ examples directory and build examples
cd /examples/cpp_sycl
nmake libintel64 example=cor_dense_batch+ # This will compile and run Correlation example using Intel(R) oneAPI DPC++ compiler
nmake libintel64 mode=build                          # This will compile all DPC++ examples

To see all avaliable parameters of the build procedure, type make on Linux* or nmake on Windows*.

  1. The resulting example binaries and log files are written into the _results directory.

Note

You should run DPC++ examples from cpp_sycl folder, not from _results folder. Most examples require data to be stored in examples\data folder and to have a relative link to it started from cpp_sycl folder.

You can build traditional C++ examples located in examples/cpp folder in a similar way.