Get Started with oneDAL

Before You Begin

oneDAL is located in <install_dir>/dal 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>/dal/<version>/redist directory.

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

  • Intel® oneAPI DPC++/C++ Compiler 2021.1 release or later (for DPC++ support)

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

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

End-to-end Example

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

The following steps depict how to:

  • Read the data from CSV file

  • Run the training and inference operations for PCA

  • Access intermediate results obtained at the training stage

  1. Include the following header that makes all oneDAL declarations available.

    #include "oneapi/dal.hpp"
    
    /* Standard library headers required by this example */
    #include <cassert>
    #include <iostream>
    
  2. Create a SYCL* queue with the desired device selector. In this case, GPU selector is used:

    const auto queue = sycl::queue{ sycl::gpu_selector{} };
    
  3. Since all oneDAL declarations are in the oneapi::dal namespace, import all declarations from the oneapi namespace to use dal instead of oneapi::dal for brevity:

    using namespace oneapi;
    
  4. Use CSV data source to read the data from the CSV file into a table:

    const auto data = dal::read<dal::table>(queue, dal::csv::data_source{"data.csv"});
    
  5. Create a PCA descriptor, configure its parameters, and run the training algorithm on the data loaded from CSV.

    const auto pca_desc = dal::pca::descriptor<float>
       .set_component_count(3)
       .set_deterministic(true);
    
    const dal::pca::train_result train_res = dal::train(queue, pca_desc, data);
    
  6. Print the learned eigenvectors:

    const dal::table eigenvectors = train_res.get_eigenvectors();
    
    const auto acc = dal::row_accessor<const float>{eigenvectors};
    for (std::int64_t i = 0; i < eigenvectors.row_count(); i++) {
    
       /* Get i-th row from the table, the eigenvector stores pointer to USM */
       const dal::array<float> eigenvector = acc.pull(queue, {i, i + 1});
       assert(eigenvector.get_count() == eigenvectors.get_column_count());
    
       std::cout << i << "-th eigenvector: ";
       for (std::int64_t j = 0; j < eigenvector.get_count(); j++) {
          std::cout << eigenvector[j] << " ";
       }
       std::cout << std::endl;
    }
    
  7. Use the trained model for inference to reduce dimensionality of the data:

    const dal::pca::model model = train_res.get_model();
    
    const dal::table data_transformed =
       dal::infer(queue, pca_desc, data).get_transformed_data();
    
    assert(data_transformed.column_count() == 3);
    

Build and Run Examples

Perform the following steps to build and run examples demonstrating the basic usage scenarios of oneDAL with DPCPP. Go to <install_dir>/dal/<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/oneapi/dpc to a writable directory if necessary (since it creates temporary files):

cp –r ./examples/oneapi/dpc ${WRITABLE_DIR}
  1. Set up the compiler environment for Intel® oneAPI DPC++/C++ Compiler. See Get Started with Intel® oneAPI DPC++/C++ 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 examples/oneapi/dpc and examples/oneapi/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/oneapi/dpc
make example=cor_dense_batch # This will compile and run Correlation example using Intel(R) oneAPI DPC++/C++ Compiler
make mode=build                    # This will compile all DPC++ examples
# Navigate to DPC++ examples directory and build examples
cd /examples/oneapi/dpc
nmake libintel64 example=cor_dense_batch+ # This will compile and run Correlation example using Intel(R) oneAPI DPC++/C++ 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 examples/oneapi/dpc folder, not from _results folder. Most examples require data to be stored in examples/oneapi/data folder and to have a relative link to it started from examples/oneapi/dpc folder.

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