insightsoftwareconsortium / itkvkfftbackend

VkFFT backends for ITK FFT classes.

ITKVkFFTBackend

Overview

VkFFT backends for ITK FFT classes.

ITK is an open-source, cross-platform library that provides developers with an extensive suite of software tools for image analysis. Developed through extreme programming methodologies, ITK employs leading-edge algorithms for registering and segmenting multidimensional scientific images.

VkFFT is an efficient GPU-accelerated multidimensional Fast Fourier Transform library for Vulkan/CUDA/HIP/OpenCL projects. VkFFT aims to provide the community with an open-source alternative to Nvidia's cuFFT library while achieving better performance. VkFFT is written in C language and supports Vulkan, CUDA, HIP and OpenCL as backends.

ITKVkFFTBackend enables ITK objects to perform accelerated FFT via the VkFFT library.

VkFFT source code is available at https://github.com/DTolm/VkFFT

itkvkfftbackend's Issues

Add Python factory initialization test

ENH: Add tests to verify 1D FFT functionality in dimensions 1 and 2

1D FFT filters are currently tested only along axis 0 but should also be supported in other directions.

Consume VkFFT as a header-only library

At the time of writing ITKVkFFTBackend retrieves the VkFFT source tree at config time with FetchContent_MakeAvailable and adds its targets to the ITKVkFFTBackend build. This adds unnecessary benchmark build steps for consuming the header-only library.

ITKVkFFTBackend should be updated to comply with Section 2.1 of the VkFFT API guide for consuming VkFFT via VkFFT.h and setting appropriate compiler definitions.

Build / test in CI on Windows

BUG: PyPi package publish fails due to auth error

From publish-python-packages-to-pypi

Warning: It looks like you are trying to use an API token to authenticate in the package index and your token value does not start with "pypi-" as it typically should. This may cause an authentication error. Please verify that you have copied your token properly if such an error occurs.

BUG: PrintSelf member functions should print all member variables

Update CI for `Ubuntu 20.04`

Replace ubuntu-18.04 runners with ubuntu-20.04

See actions/runner-images#6002

`itk.VkHalfHermitianToRealInverseFFTImageFilter` interface differs from base class

Seeing different behavior between itk.VkHalfHermitianToRealInverseFFTImageFilter and itk.VnlHalfHermitianToRealInverseFFTImageFilter due to the VkFFT filter defining a mandatory output size parameter.

Steps to Reproduce

Define image with first dimension of size (2 ** n) - 1

>>> import itk
>>> image.SetRegions([129,256])     # Taken from ITK FFT tests. First dimension must be size (2 ** n) - 1
>>> image.Allocate()

Expected (Vnl)

>>> fft_filter = itk.VnlHalfHermitianToRealInverseFFTImageFilter[itk.Image[itk.complex[itk.F],2],itk.Image[itk.F,2]].New()
>>> fft_filter.SetInput(image)
>>> fft_filter.Update()
>>> itk.size(fft_filter.GetOutput())
itkSize2 ([256, 256])

Observed (VkFFT)

>>> fft_filter = itk.VkHalfHermitianToRealInverseFFTImageFilter[itk.Image[itk.complex[itk.F],2]].New()
>>> fft_filter.SetInput(image)
>>> fft_filter.Update()
Traceback (most recent call last):
  File "<stdin>", line 1, in <module>
RuntimeError: C:\repos\ITKVkFFTBackend\include\itkVkHalfHermitianToRealInverseFFTImageFilter.hxx:68:
ITK ERROR: Input image's first dimension must equal floor((output image's first dimension)/2) + 1

From tracing through itkVkHalfHermitianToRealInverseFFTImageFilter.hxx the issue is that the VkFFT filter expects the output region size to be explicitly set by the user in its interface. As this is not done in ITK classes consuming FFT filters internally, attempting to override the base FFT class with its VkFFT accelerated implementation results in failures.

Next Steps

I am inclined to simply remove the output region parameter from the VkFFT class and rely on the underlying output size defined in https://github.com/InsightSoftwareConsortium/ITK/blob/master/Modules/Filtering/FFT/include/itkHalfHermitianToRealInverseFFTImageFilter.hxx#L65.

@Leengit Could you please provide feedback on this proposal? Am I missing context for why we are requesting an explicit output size definition for the accelerated FFT class?

Platform cannot be selected in factory-instantiated classes

When directly using a class such as itk.VkForwardFFTImageFilter it is easy to set the OpenCL platform to run on (such as CPU vs GPU) with fft_filter.SetDeviceID(<val>). However, when the class is consumed via factory override, the answer is less clear. This gets at a more fundamental question: how do we set properties unique to the derived class when instantiated through the object factory?

In this case the OpenCL platform to use is unique to the user, but will not change very much across VkFFT filters.

Possible solutions:

• Have VkFFT classes consume a global variable defining the platform ID to use: not pretty, but quick and functional
• Update the ITK object factory mechanism to include user-settable constructor arguments with class overrides: helps avoid this problem in the long run, but would take a while to architect and implement, and might get messy
• Define class overrides for individual ITK classes known to consume FFT filters, then expose the platform arg in derived classes: operates within existing architecture constraints, but also partially defeats the point of object factory overrides in that we now have to cover every class using FFTs.

In the interest of maximizing effort spent I think the first bullet is the most effective path for now.

Vulkan_FFT Benchmark Targets Always ON

I noticed that the Vulkan_FFT target with VkFFT benchmarks always builds alongside ITKVkFFTBackend. While there are scenarios where it is useful to have the benchmarks on hand, the typical ITK user will at best want this to be optional. Should revisit how we are setting and building targets, possibly contributing back to VkFFT upstream to make the target configurable.

ENH: Investigate alternate VkFFT backends

1. Vulkan
2. CUDA

How to enable VkFFTBackend when building itk 5.3.0 on windows

hello, im trying to build itk 5.3.0 with ITK_USE_CUFFTW ON on windows, but get some problems with that.
is the VkFFTBackend a substitude for cufft, if yes, how to enable VkFFTBackend in itk? will the itk montage benefit from VkFFTBackend set ON

my environment: windows 10 cmake 3.26.1 cuda v12.1

PERF: Avoid recompiling GPU code for FFT in subsequent computations.

There are some parts of the code that are not executed on subsequent uses of these classes, but this should be expanded to more cases.

BUG: VkFFTConfiguration::bufferSize, inputBufferSize, and outputBufferSize should be in bytes

They currently have the number of entries in the image, but need to be further multiplied by the size of the pixel types in bytes.

ENH: Use object factory to instantiate FFT classes with VkFFT backend

Rather than specifically instantiating itk::VkForwardFFTImageFilter, etc, it would be useful for ITK to be able to pick up the VkFFT backend if it is available when instantiating itk::ForwardFFTImageFilter. The object factory can be used to make different backends available.

Steps:

• Add object factory support to ITK FFT filters (in progress)
• Add object factory support to ITK VkFFT filters

Split from #14 .

VkFFT error code handling

Exceptions thrown by ITK VkFFT classes are disruptive to pipeline flow and difficult to read. For example, from Python benchmarking on BIL workshop2 node:

Experiment   Image Len (px)     Volume (px)     CPU FFT Time (s)        GPU FFT Time(s) Speedup
         0                 10   1.00e+03                0.000204        0.320318        -156668.8%
         1                 30   2.70e+04                0.001416        0.159839        -11186.4%
         2                100   1.00e+06                0.042245        0.153889        -264.3%
         3                200   8.00e+06                0.450544        0.824002        -82.9%
         4                300   2.70e+07                1.304689        0.294664        77.4%
         5                600   2.16e+08                12.178864       1.481467        87.8%
         6                800   5.12e+08                44.749890       3.230387        92.8%
         7               1000   1.00e+09                59.368654       6.215513        89.5%
         8               1200   1.73e+09                123.027794      10.488541       91.5%
Traceback (most recent call last):
  File "/bil/users/tbirdso/vkfft/benchmark.py", line 42, in <module>
    vk_interval = run_fft(vk_type, image_size)
  File "/bil/users/tbirdso/vkfft/benchmark.py", line 28, in run_fft
    return benchmark_fft(fft_filter)
  File "/bil/users/tbirdso/vkfft/benchmark.py", line 20, in benchmark_fft
    itk_fft_filter.Update()
RuntimeError: ../../../include/itkVkForwardFFTImageFilter.hxx:100:
ITK ERROR: VkFFT third-party library failed with error code 4039.

Proposals:

1. Investigate whether there is a better way to handle ITK filter failures. (The answer may be just using try/catch blocks in the C++ or Python calling script, but would be good to research).
2. Translate VkFFT error codes into human-readable errors inline rather than require consulting the user manual. May involve contributions back to VkFFT.

ENH: Add acceleration for 1DFFT image filters

See ITKUltrasound classes.

ENH: Add Python demo

1. pip install itk-vkfftbackend
2. Demo script (notebook)

CUDA Linux build + package issues

Discussed in #35:

• Failure to find Threads library on Linux
• Failure to link with -lcuda when building Python wheels on Linux (tested with Python 3.8.5)