AOCL Data Analytics Library

The AOCL Data Analytics Library (AOCL-DA) provides optimized building blocks for data analysis and machine learning. It is written with a C-compatible interface to make it as seamless as possible to integrate with the library from whichever programming language you are using. For further details on the library contents, please refer to the online help or PDF user guide. Note that prebuilt binaries for AOCL-DA are available from https://www.amd.com/en/developer/aocl.html.

The intended workflow for using the library is as follows:

• load data from memory by reading CSV files or using the in-built da_datastore object

• pre-process the data by removing missing values, standardizing, and selecting certain subsets of the data, before extracting contiguous arrays of data from the da_datastore objects

• data processing (e.g. principal component analysis, linear model fitting, etc.)

C++ example programs can be found in the examples folder of your installation.

Full API documentation is available at https://docs.amd.com/r/en-US/68552-AOCL-api-guide/AOCL-Data-Analytics

AOCL-DA is developed and maintained by AMD. For support or queries, you can email us on toolchainsupport@amd.com.

Building the Library

AOCL-DA is built with CMake, with supported compilers GNU and AOCC on Linux and MSVC on MS Windows.

AOCL-DA is dependent on AOCL-BLAS, AOCL-LAPACK, AOCL-Sparse and AOCL-Utils.

AOCL-DA is also dependent on the Boost.Sort C++ Library. Instructions for installing Boost on Linux can be found here. Instructions for installing Boost on Windows can be found here. Documentation for Boost CMake support infrastructure can be found here and here.

For example, one way of including a Boost download in your CMake build of AOCL-DA would be to add the following arguments to the CMake configure step: -DBoost_ROOT=${BASE_DIR}/DA-projects/aocl-da/external/boost-1.86.0 -DBoost_NO_BOOST_CMAKE=ON. However, if you have Boost installed on your system path, CMake should be able to locate it automatically.

Building on Linux

1. You will need to have BLAS, LAPACK, AOCL-Sparse and AOCL-Utils installed.

2. Make sure you have set the environment variable $AOCL_ROOT to where the AOCL libraries are installed e.g. /home/username/amd/aocl/4.0.

3. Configure cmake with -T ClangCL -DOpenMP_libomp_LIBRARY=\Path\to\libomp.lib and any of the following options:

   • -DMEMSAN=On for memory sanitization

   • -DASAN=On for address sanitization

   • -DVALGRIND=On for valgrind use

   • -DBUILD_ILP64=On for 64-bit integer build

   • -DCMAKE_BUILD_TYPE=Debug or Release

   • -DCOVERAGE=On to build code coverage report. Use cmake --build . --target coverage to compile the coverage report itself

   • -DBUILD_EXAMPLES=On and –DBUILD_GTEST=On both of which are On by default

   • -DBUILD_SHARED_LIBS=On for a shared library build (Off by default)

   • -DARCH=<arch> to set the -march=<arch> flag, where <arch> specifies the architecture to build for, e.g. znver4. must be a single word from "znver1", "znver2", "znver3", "znver4", ..., "native" or "dynamic". Setting -DARCH=dynamic will build the library using dynamic dispatch. Leaving it blank will create a native build.

   • -DBUILD_DOC=On to build the documentation. Use cmake --build . --target doc to build all documentation formats (or doc_pdf, doc_html to build only PDF or only HTML formats)

   • -DINTERNAL_DOC=On to build the internal documentation alongside the main one

   • -DBUILD_SMP=On to build using OpenMP and threaded BLAS (On by default)

   • -DVECTORIZATION_REPORTS=On to build with vectorization reports enabled

   • -DDA_LOGGING=On to enable debug printing

   • -DBUILD_PYTHON=On to build the Python interfaces

   • -DCMAKE_AOCL_ROOT=<path to AOCL> to specify a location for AOCL libraries. This has precedence over the environment variable $AOCL_ROOT

   • -DCMAKE_INSTALL_PREFIX=<install path> to specify the install path for the library

   • -DBUILD_FORTRAN=On to build those parts of the library that require Fortran code (On by default, but you can set it to Off if you do not have a Fortran compiler, in which case the LBFGSB linear model solver, and the nonlinear least squares solver will not be available)

   • -DKT_PATH=<path> to explicitly set the path that contains the Reusable Kernel Templates Library (KT). This path is expected to contain the subdirectory kernel-templates/. By default it will point to the AOCL-Sparse library include path.

   • Any combination of -DLAPACK_LIB, -DBLAS_LIB, -DSPARSE_LIB, -DUTILS_LIB, -DUTILS_CPUID_LIB, -DLAPACK_INCLUDE_DIR and -DBLAS_INCLUDE_DIR if you wish to override the use of AOCL_ROOT with specific choices of BLAS/LAPACK/Sparse libraries and include directories. Care should be taken if you do this as there will be no checks for the correctness of the linked libraries.

   Note that not all the options available in Release build mode.

4. Type cmake --build . --target all (or --target doc, to build the documentation).

5. Run the tests or examples using ctest e.g. ctest -V –R followed by a string to find a particular set of tests.

Building on MS Windows

1. You will need either:

   • a Visual Studio installation and compatible Fortran compiler (this will allow you to build with the MSVC compatibility layer for clang (clang-cl)).
   • GCC and gfortran compilers, which are available via MinGW and MSYS2.

2. Make sure you have set the AOCL_ROOT environment variable to your AOCL installation directory (e.g. C:\Users\username\AOCL-5.0), and update your PATH to take in the relevant BLAS and LAPACK libraries e.g. set PATH=C:\path\to\AOCL\amd-blis\lib\LP64;C:\path\to\AOCL\amd-libflame\lib\LP64;C:\path\to\AOCL\amd-sparse\lib\LP64\shared;%PATH%.

3. Configure cmake using e.g. cmake -T ClangCL -DCMAKE_Fortran_COMPILER=ifort, with any of the following options:

   • -DBUILD_ILP64=On for 64-bit integer build

   • -DBUILD_EXAMPLES=On and –DBUILD_GTEST=On both of which are on by default

   • -DBUILD_SMP=On to build using OpenMP and threaded BLAS (On by default)

   • -DBUILD_SHARED_LIBS=On for a shared library build (Off by default)

   • -DARCH=<arch> to set the -march=<arch> flag, where <arch> specifies the architecture to build for, e.g. znver4. must be a single word from "znver1", "znver2", "znver3", "znver4", ..., "native" or "dynamic". Setting -DARCH=dynamic will build the library using dynamic dispatch.

   • -DCMAKE_AOCL_ROOT=<path to AOCL> if you wish to specify a location for AOCL libraries without using environment variables

   • -DBUILD_FORTRAN=On to build those parts of the library that require Fortran code (On by default, but you can set it to Off if you do not have a Fortran compiler, in which case the LBFGSB linear model solver, and the nonlinear least squares solver will not be available)

   • -DKT_PATH=<path> to explicitly set the path that contains the Reusable Kernel Templates Library (KT). This path is expected to contain the subdirectory kernel-templates/. By default it will point to the AOCL-Sparse library include path.

   • Any combination of -DLAPACK_LIB, -DBLAS_LIB, -DSPARSE_LIB, -DUTILS_LIB, -DUTILS_CPUID_LIB, -DLAPACK_INCLUDE_DIR and -DBLAS_INCLUDE_DIR if you wish to override the use of AOCL_ROOT with specific choices of BLAS/LAPACK/Sparse libraries and include directories. Care should be taken if you do this as there will be no checks for the correctness of the linked libraries.

   Note that not all the options available in Linux are available in Windows

4. Either:

   • Open Visual Studio and load the AOCL-DA.sln file then build Debug or Release builds using the GUI, or

   • In a command prompt type devenv .\AOCL-DA.sln /build "Debug" or cmake --build . --config Debug to build the solution (change to Release as appropriate)

   • If using the GNU toolchain, build using cmake and Ninja.

Building the Python interfaces

To build the Python interfaces, use -DBUILD_PYTHON=On (note that this will only work with shared library builds). You will need to install the required Python packages listed in the requirements.txt file inside of python_interface directory. On Windows you may also need to set the CMAKE_PREFIX_PATH to point to the location of you pybind11 installation, e.g. C:\path\to\your\python-environment\site-packages\pybind11\share\cmake\pybind11 By default, cmake will compile the bindings but will not install them. If you set -DCMAKE_INSTALL_PREFIX=<install path> in your configure step and run cmake --build . --target install, then cmake will also create a Python wheel, aoclda-*.whl, where * depends on your system. This wheel can be installed using pip install aoclda-*.whl. When using the bindings on Windows, the Intel Fortran runtime must be available. This can be done by setting the environment variable INTEL_FCOMPILER.

Building the documentation on Linux

The documentation is based on Doxygen, Sphinx, Breathe and the underlying requirements of Python3 packages (and its dependencies) listed under doc/requirements.txt and a modern LaTeX distribution with at least the packages: amsmath, array, courier, doxygen, etoc, fancyhdr, fixltx2e, fontenc, geometry, graphicx, helvet, hyperref, ifthen, ifxetex, inputenc, natbib, newunicodechar, sectsty, textcomp, tocloft, and wasysym.

To build the documentation, the Python interfaces must be enabled and built (-DBUILD_PYTHON=On) as well as the unit-tests (–DBUILD_GTEST=On). Set the option -DBUILD_DOC=On to build the documentation. Use cmake --build . --target doc to build all documentation formats (or doc_pdf, doc_html to build only PDF or only HTML formats).

Using CMake Presets for building and testing the library

CMake Presets can help with configuring, building and testing AOCL-DA in a simplified manner. CMake Presets are available for common combinations on Linux and on Windows platforms. To see the available presets, from the source directory, you can use:

cmake --list-presets

To configure only, from the source directory, you can use:

cmake --preset linux-gcc-mt-lp64-static-release-dynamic

For example, this will configure CMake for Linux platform so that CMake uses GCC to build a multi-threaded (mt) LP64 Release library with dynamic dispatch. This command will generate a build directory with the corresponding naming convention "build-linux-gcc-mt-lp64-static-dynamic-release". One can simply cd build-linux-gcc-mt-lp64-static-dynamic-release and continue the usual process of building, installing and so on.

Alternatively, to build from the source directory, you can use:

cmake --build --preset linux-gcc-mt-lp64-static-release-dynamic

To build and install from the source directory, you can use:

cmake --build --preset linux-gcc-mt-lp64-static-release-dynamic-install

The library will be installed in a directory with the corresponding naming convention "install-linux-gcc-dynamic-release".

To configure, build, install and validate the library in a single step, you can use:

cmake --workflow --preset linux-gcc-mt-lp64-static-release-dynamic

You can configure the presets and append them with an known CMake option. For example:

cmake --preset linux-gcc-mt-lp64-static-release-dynamic -DCOVERAGE=ON

would configure CMake as before and enable coverage in addition. The build step can continue as before.

There is a mechanism to generate appropriate presets using a python script. To see how to use the generator, from aocl-da directory run:

python ./cmake/presets/preset_generator.py --help

For example, running

python ./cmake/presets/preset_generator.py linux-ninja-gcc-lp64-shared-znver5

will create a JSON file located in ./cmake/presets/ directory with configure, build and workflow commands that uses the Ninja generator, GCC compilers and produces a 32-bit shared library for zen5 architectures. The script will also append the ./cmake/presets/includes.json file so that the new preset can be detected.