Matrix Profile Computation on Xilinx FPGAs

This repository includes multiple Vitis™ HLS implementations of the Matrix Profile Computation Algorithm SCAMP for Xilinx FPGAs, using Xilinx Vitis™ to instantiate memory and PCIe controllers and interface with the host.

The Matrix Profile is a novel data structure with corresponding algorithms (stomp, regimes, motifs, etc.) developed by the Keogh and Mueen research groups at UC-Riverside and the University of New Mexico.

The source files for the different implementation of the compute kernel can be found under kernel/MatrixProfileKernelVanilla.cpp and kernel/MatrixProfileKernelTiled.cpp.

The driver application is in host/MatrixProfileHost.cpp. This repository contains a light-weight OpenCL™ wrapper for the interaction with the FPGA kernel, which is located in include/host/OpenCL.hpp.

Getting Started

Cloning the repository

This project uses Google's open source testing and mocking framework GoogleTest to test the different kernels in software.

Since GoogleTest is included as a submodule, make sure to to clone the repository with --recursive if you plan on running the (software) tests. If the repository was cloned non-recursively previously, use git submodule update --init to clone the required submodule (GoogleTest).

Prerequisites

To build and run the kernels in hardware (simulation) Xilinx Vitis must be installed and the corresponding PATH-variables must be set. In particular, this typically requires setting up the environment to run the Vitis™ software platform:

source /opt/Xilinx/Vitis/2020.2/settings64.sh
source /opt/xilinx/xrt/setup.sh

and setting the correct XCL_EMULATION_MODE in case of software (sw_emu) or hardware (hw_emu) emulation:

export XCL_EMULATION_MODE=hw_emu

Build and Run

Configuration and Building

This project is configured and built using CMake. Most parameters must be set at configuration-time, as they are used to specialize the hardware.

An example of configuring the kernel (starting from the root directory):

mkdir build && cd build
cmake .. -DMP_KERNEL=Tiled -DMP_TARGET=hw -DMP_DATA_TYPE=double -DMP_SIZE_N=1048576 -DMP_SIZE_M=256 -DMP_SIZE_W=4096 -DMP_SIZE_T=128 -DMP_KERNEL_REPL=3
make host
make compile
make link

Build Parameters

CMake Parameter	Description	Values
MP_KERNEL	Kernel-Implementation	Vanilla, Tiled
MP_DATA_TYPE	Data Type for Computation	float, double
MP_TARGET	Compilation Target	sw_emu, hw_emu, hw
DMP_SIZE_N	Length of the Time Series
DMP_SIZE_M	Subsequence Length
DMP_SIZE_W	Tile-Size (Host-Side)
DMP_SIZE_T	Tile-Size (Device-Side)	only applicable for Tiled-Kernel
DMP_KERNEL_REPL	Number of Kernel Replications

For a more comprehensive list of parameters (e.g., targeting EMBEDDED-Platforms) see CMakeLists.txt.

Per default the build targets the Alveo U250 acceleration board, but this can be configured using the MP_PLATFORM CMake parameter.

Executing the Kernel

After having build the host application and linked the Kernel, execute the Kernel on input data/binary/1048576.tsb (run this in the build directory) via:

./MatrixProfileHost -b MatrixProfileKernel.xclbin -i ../data/binary/1048576.tsb --verbose

A list of example datasets as well as instruction on how to use your own dataset can be found here.

Testing

This project uses Google's open source testing and mocking framework GoogleTest to test the different kernels in software.

To build and run the test executables:

mkdir build && cd build
cmake .. -DSKIP_CHECKS=ON -DBUILD_TESTS=ON
make && make test

The corresponding source files can be found under test/TestVanillaKernel.cpp and test/TestTiledKernel.cpp.

Bugs

If you experience bugs, or have suggestions for improvements, please use the issue tracker to report them.