ATS-GPU-NUFFT Programmer's guide ============================== .. note:: This is the documentation for AlazarTech's ATS-GPU version |version|. Please visit our `documentation homepage `_ to find documentation for other versions or products. .. highlight:: c License Agreement ----------------- .. include:: ../../LICENSE Introduction ------------ ATS-GPU-NUFFT provides a framework to allow real-time, non-uniform Fourier transform processing from AlazarTech PCIe digitizers on a CUDA-compatible GPU. ATS-GPU-NUFFT internally calls ATS-CUDA-NUFFT, which is a low-level library that performs all the necessary operations to perform the non-uniform Fourier Transform. ATS-CUDA-NUFFT is described later in this guide in the section `ATS-CUDA-NUFFT`_. This document assumes that the reader is familiar with ATS-SDK, the standard interface for programming AlazarTech digitizers. Having a copy of the ATS-SDK manual available can be helpful, since many references to ATSApi functions are done here. The latest version of the ATS-SDK manual can be downloaded free of charge from `AlazarTech's website `_. Prerequisites ------------- System requirements ~~~~~~~~~~~~~~~~~~~ This software requires a PC with a CUDA-enabled GPU, and sufficient CPU resources to supply data to the GPU at the desired data acquisition rate. It also requires a working installation of the same version of ATS-GPU-BASE and ATS-GPU-OCT. It was tested with a GeForce RTX 2080 Ti and a Quadro P5000. DDR4 memory and a modern chipset (X99, X299) will greatly improve transfer speed and overall performance. Supported operating systems Windows and Linux operating systems are supported. Please verify that your Linux distribution is `supported by NVIDIA `_ which supplies the CUDA toolkit required to use ATS-GPU. Compiler support CMake is required to build C/C++ code. CMake files are provided. On Linux, a C++11 compiler is required to build the library. On older Red Hat distributions, a devtoolset can be obtained to use a more recent version of gcc that supports C++11. NVCC is required to compile the example code, this compiler is included with CUDA toolkit. CUDA driver requirements In order to use ATS-GPU, you must install the appropriate driver for your CUDA-enabled GPU. Drivers can be downloaded at https://www.nvidia.com/Download/index.aspx. .. note:: Under Windows operating systems, dynamic link libraries releated to ATS-GPU-NUFFT are installed by default in %WINDIR%\System32. For applications to link approripately to them, %WINDIR%\System32 must be added to the Windows PATH Environment Variable. ATS-GPU-NUFFT ----------- ATS-GPU-NUFFT leverages ATS-GPU-BASE to transfer data from an ATS PCIe digitizer to a GPU in a highly efficient manner. It then takes care of doing NUFFT processing on the data before sending it back to the host computer's RAM. ATS-GPU-NUFFT also relies on ATS-GPU-OCT for standard FFT processing stages. Usage ~~~~~ ATS-GPU-NUFFT acquisitions are very similar to standard ATSApi acquisitions. Only the differences are listed here for brevity. The central function of the ATS-GPU-NUFFT interface is :cpp:func:`ATS_GPU_NUFFT_Setup()`. This function calls its ATS-GPU-BASE counterpart ``ATS_GPU_Setup()`` internally, which in turns calls ``AlazarBeforeAsyncRead()``. It takes a few extra parameters: - ``OCTFlags``: Used to define which data type, such as amplitude and phase, to obtain from the acquisition. - ``FFTLength``: This is used to select the length of the Fourier transform done on the GPU. This value should be a power of two for efficiency, and it also must be equal to or larger than the record length. - ``NUFFTFlags``: Used to define the source of the linearization function. Linearization can either be user defined by selecting ``ATS_GPU_NUFFT_PRESET_LINEARIZATION`` or be determined from a K-clock signal when ``ATS_GPU_NUFFT_KCLOCK_LINEARIZATION`` is used. .. code-block:: c++ rc = ATS_GPU_NUFFT_Setup( boardHandle, channelMask, -(int) preTriggerSamples, samplesPerRecordPerChannel, recordsPerBuffer, buffersPerAcquisition * recordsPerBuffer, autoDMAFlags, OCTOptions, FFTLength, NUFFTFlags, NULL, &fftBytesPerBuffer); // Error handling If ``NUFFTFlags`` is setup with ``ATS_GPU_NUFFT_KCLOCK_LINEARIZATION``, the channelMask must contain ``CHANNEL_A`` and at least one other active channel. With this flag, ATS-GPU-NUFFT will determine the linearization function for each record from the k-clock signal acquired on ``CHANNEL_A`` and use it to perform non-uniform FFT on every other active channel. If ``NUFFTFlags`` was setup with ``ATS_GPU_NUFFT_PRESET_LINEARIZATION``, the user is required to specify a precalibrated linearization function. This linearization function will be used to perform non-uniform FFT on every record of every active channel. .. code-block:: c++ int precalibratedFunctionLength = 1000; std::vector precalibratedFunction(precalibratedFunctionLength); for (int i = 0; i < precalibratedFunction.size(); i++) { precalibratedFunction[i] = i; } rc = ATS_GPU_NUFFT_SetLinearizationFunction( boardhandle, precalibratedFunction, &precalibratedFunction[0]); // Error handling Here, we generated a linear linearization function. Setting a linear precalibrated function represents a signal that is sampled linearly in k-space, thus equivalent to applying regular FFT. The precalibrated linearization function can have any length as ATS-GPU-NUFFT will internally take care of re-sampling the function to a length equal to ``samplesPerRecordPerChannel``. ATS-GPU-NUFFT will also normalize the function. The precalibrated linearization can therefore have any start and end values. The values of the precalibrated linearization function must always be increasing such as ``x[i]