SAF
Performance Libraries Supported by SAF

The Spatial_Audio_Framework (SAF) requires any library (or combination of libraries) which supports the CBLAS and LAPACK standards

Currently, SAF supports Intel MKL, OpenBLAS, Apple Accelerate, and ATLAS. You may select which option you wish to use by adding one of the following pre-processor definitions:

SAF_USE_INTEL_MKL_LP64 # great option, but only for x86 architectures (using the LP64 config [int32])
SAF_USE_INTEL_MKL_ILP64 # great option, but only for x86 architectures (using the ILP64 config [int64])
SAF_USE_OPEN_BLAS_AND_LAPACKE # good option, works on everything
SAF_USE_APPLE_ACCELERATE # good option (x86 and ARM), faster than OpenBLAS, but MacOSX only & slower than MKL
SAF_USE_ATLAS # bad option (x86 and ARM), many LAPACK functions are missing
SAF_USE... # please get in touch if you use something else! :-)

SAF_USE_INTEL_MKL_LP64 or SAF_USE_INTEL_MKL_ILP64

Intel MKL is perhaps the fastest library for x86 platforms. It also includes an optimised FFT implementation and a number of additional vectorised utility functions which SAF is also able to make use of.

Intel MKL can be downloaded (royalty-free) from here.

Unfortunately, while you can indeed link directly to the Intel MKL static/shared libraries... these files are rather large. Therefore, you may prefer to use the MKL builder to build a custom MKL library, which contains only the routines that SAF actually needs.

Instructions regarding how to build a custom MKL library for Windows, MacOSX, and Linux users, can be found below.

Linux/MacOSX users

Run the following bash script (sudo privileges required):

cd scripts
sudo ./install-safmkl.sh [threaded|sequential] [lp64|ilp64] [path/to/mkl/tools/builder]

Add the following header search path to your project:

[/opt|~]/intel/oneapi/mkl/latest/include/ # The new oneapi path
[/opt|~]/intel/compilers_and_libraries/linux/mkl/include # Old path for Linux users
[/opt|~]/intel/compilers_and_libraries/mac/mkl/include # Old path for MacOSX users

Then add the following linker flag to your project:

-L/usr/local/lib -lsaf_mkl_custom_lp64 # if you built the lp64 (32-bit integer) version
-L/usr/local/lib -lsaf_mkl_custom_ilp64 # if you built the ilp64 (64-bit integer) version

Finally, add the appropriate global definition:

SAF_USE_INTEL_MKL_LP64 # if you are linking with the lp64 (32-bit integer) version
SAF_USE_INTEL_MKL_ILP64 # if you are linking with the ilp64 (64-bit integer) version

Windows users

Run the following batch script using x64 Developer Command Prompt for VS.exe (open as administrator):

cd scripts
install-safmkl.bat

Add the following header search path to your project:

C:/Program Files (x86)/IntelSWTools/compilers_and_libraries/windows/mkl/include

Add the following library search path to your project:

C:/YOUR/WORKING/DIRECTORY/Spatial_Audio_Framework/dependencies/Win64/lib

Link your project against the following library:

saf_mkl_custom_lp64.lib # if you built the lp64 (32-bit integer) version
saf_mkl_custom_ilp64.lib # if you built the ilp64 (64-bit integer) version

Finally, add the appropriate global definition:

SAF_USE_INTEL_MKL_LP64 # if you are linking with the lp64 (32-bit integer) version
SAF_USE_INTEL_MKL_ILP64 # if you are linking with the ilp64 (64-bit integer) version

Other options

This custom MKL library (lp64) is also installed alongside the SPARTA VST plug-in suite. Athough, it will be noted that this may not be the most up-to-date version of the library.

You may of course also elect to not build this custom library and link directly, e.g. with:

/opt/intel/oneapi/mkl/latest/lib/libmkl_rt.[dylib|so]

This will select the interface and threading at runtime, based on environment variables. You can check the options for your system with intel's link-line-advisor. The options can be passed directly to CMake, e.g. with

-DSAF_PERFORMANCE_LIB=SAF_USE_INTEL_MKL_ILP64 -DINTEL_MKL_HEADER_PATH="/opt/intel/oneapi/mkl/latest/include" -DINTEL_MKL_LIB="/opt/intel/oneapi/mkl/latest/lib/libmkl_intel_ilp64.dylib;/opt/intel/oneapi/mkl/latest/lib/libmkl_sequential.dylib;/opt/intel/oneapi/mkl/latest/lib/libmkl_core.dylib"

Intel MKL also ships with recent Anaconda distributions. The easiest way to install with conda is:

conda install mkl mkl-include

Please refer to the documentation to find out where conda installs packages on your platform.

SAF_USE_OPEN_BLAS_AND_LAPACKE

For those who would like to use the framework with OpenBLAS, note that for Debian/Ubuntu based Linux distributions, the libraries may be installed via:

sudo apt-get install liblapack3 liblapack-dev libopenblas-base libopenblas-dev liblapacke-dev

However, if you are not on Linux, or would prefer to have more control over things, then the required libraries may also be built via CMake:

git clone https://github.com/xianyi/OpenBLAS.git
# install a fortran compiler if you haven't already (for lapack support)
sudo apt-get install gfortran
# build static libs
mkdir build
cd build
cmake .. -DCMAKE_BUILD_TYPE=Release -DBUILD_SHARED_LIBS=0 -DBUILD_WITHOUT_LAPACK=0
make

The static openblas library can then be found in:

OpenBLAS/build/lib/libopenblas.a

The required include files are then found in:

OpenBLAS/lapack-netlib/CBLAS/include
OpenBLAS/lapack-netlib/LAPACKE/include

SAF_USE_APPLE_ACCELERATE

Only for MacOSX users. Simply add the Accelerate framework to your XCode project, and you're good to go.

Note that Accelerate also includes an optimised FFT implementation and a number of additional vectorised utility functions which SAF is also able to make use of.

SAF_USE_ATLAS

Using ATLAS is not recommended, since some LAPACK functions are missing. However, if you don't mind losing some SAF functionality, then this may still be a good choice for your particular project.