Quick Start¶

Before You Begin¶

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

The current version of oneDAL with SYCL 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 SYCL extensions:

Intel® oneAPI DPC++/C++ Compiler 2021.1 release or later (for support)
OpenCL™ runtime 1.2 or later (to run the SYCL 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

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>

Create a SYCL* queue with the desired device selector. In this case, GPU selector is used:
```
const auto queue = sycl::queue{ sycl::gpu_selector_v };
```
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;
```

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"});

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);

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;
}

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.

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.
- To set up oneDAL environment via vars.sh script, run source ./env/vars.sh.
- To set up oneDAL environment via setvars.sh script, run source ./setvars.sh.
- To set up oneDAL environment via modulefiles:
  1. Initialize modules:
    
    source $MODULESHOME/init/bash
    
    Note
    
    Refer to Environment Modules documentation for details.
  2. Provide modules with a path to the modulefiles directory:
    
    module use ./modulefiles
  3. Run the module:
    
    module load dal
To set up oneDAL environment, run source /env/vars.bat or source setvars.bat.
Copy ./examples/oneapi/dpc to a writable directory if necessary (since it creates temporary files):
```
cp –r ./examples/oneapi/dpc ${WRITABLE_DIR}
```
Set up the compiler environment for Intel® oneAPI DPC++/C++ Compiler. See Get Started with Intel® oneAPI DPC++/C++ Compiler for details.

Build and run 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 examples directory and build examples
cd /examples/oneapi/dpc
cmake -G "Unix Makefiles⁮" -DEXAMPLES_LIST=svm_two_class_thunder # This would generate makefiles for all svm examples matching passed name
make               # This will compile and run generated svm examples
cmake -G "Unix Makefiles⁮" -DONEDAL_LINK=static # This wouldgenerate make for static version
make               # This will compile and run all the examples

 # Navigate to examples directory and build examples
 cd /examples/oneapi/dpc
cmake  -G "NMake Makefiles" -DEXAMPLES_LIST=svm_two_class_thunder # This would generate makefiles for all svm examples matching passed name
nmake             # This will compile and run generated svm examples
cmake  -G "NMake Makefiles" -DONEDAL_LINK=static # This wouldgenerate make for static version
nmake              # This will compile and run all the examples

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

Note

You should run the 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.

oneDAL documentation

Quick Start¶

Before You Begin¶

End-to-end Example¶

Build and Run Examples¶