Developer Guide and Reference

  • 2021.2
  • 03/26/2021
  • Public Content
Contents

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 Base 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:
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
    ):
Linux
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
    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
Windows
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:
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.
Linux
# 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
Windows
# 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 available 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.
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.

See Also

Product and Performance Information

1

Performance varies by use, configuration and other factors. Learn more at www.Intel.com/PerformanceIndex.