fft

fft ¶

FFT-based convolution for uniform time grids.

This module provides FFT-based convolution operations that are efficient for large datasets with uniform time sampling. GPU-compatible using the array module pattern.

Includes batch operations optimized for processing many voxels simultaneously (e.g., convolving a single AIF with many IRFs).

References

- scipy.signal.fftconvolve documentation
- Sourbron & Buckley (2013). Tracer kinetic modelling in MRI.
  NMR in Biomedicine, 26(8), 1034-1048.

fft_convolve ¶

fft_convolve(f, h, dt, *, mode='same')

Convolve two signals using FFT.

Efficient convolution for large datasets with uniform time sampling. Uses FFT for O(n log n) complexity instead of O(n^2) direct convolution.

PARAMETER	DESCRIPTION
`f`	First input signal. Shape: (n,). TYPE: `ndarray`
`h`	Second input signal (impulse response). Shape: (m,). TYPE: `ndarray`
`dt`	Time step between samples in seconds. TYPE: `float`
`mode`	Output mode: - "full": Full convolution result. Shape: (n + m - 1,). - "same": Output same size as first input. Shape: (n,). - "valid": Only fully overlapping region. Shape: (max(n, m) - min(n, m) + 1,). TYPE: `('full', 'same', 'valid')` DEFAULT: `"full"`

RETURNS	DESCRIPTION
`ndarray`	Convolution result scaled by dt.

Notes

FFT convolution assumes periodic boundary conditions. For pharmacokinetic modeling, this may introduce artifacts at boundaries. Consider using piecewise-linear convolution (conv()) for more accurate results when: - Time sampling is non-uniform - Boundary behavior is important - Dealing with small datasets where O(n^2) is acceptable

This function is GPU-compatible and will use CuPy FFT when the input arrays are on GPU.

Examples:

>>> import numpy as np
>>> from osipy.common.convolution import fft_convolve
>>> dt = 0.1  # 100 ms time step
>>> n = 1000
>>> t = np.arange(n) * dt
>>> f = np.exp(-t / 5)  # Input signal
>>> h = np.exp(-t / 10)  # Impulse response
>>> result = fft_convolve(f, h, dt, mode="same")

References

.. [1] scipy.signal.fftconvolve documentation

convolve_aif ¶

convolve_aif(aif, impulse_response, dt=1.0)

Convolve AIF with impulse response function(s) using FFT.

Computes the tissue concentration C(t) from the convolution of the arterial input function (AIF) with the impulse response function (IRF):

C(t) = AIF(t) * IRF(t) * dt

Handles both single-voxel and batch cases via broadcasting: a 1-D AIF is automatically broadcast against a 2-D IRF matrix.

PARAMETER	DESCRIPTION
`aif`	Arterial input function, shape `(n_timepoints,)` or `(n_timepoints, 1)` or `(n_timepoints, n_voxels)`. TYPE: `NDArray`
`impulse_response`	Impulse response function, shape `(n_timepoints,)` or `(n_timepoints, n_voxels)`. TYPE: `NDArray`
`dt`	Time step in seconds. Default is 1.0. TYPE: `float` DEFAULT: `1.0`

RETURNS	DESCRIPTION
`NDArray`	Convolution result. Shape matches the broadcast of aif and impulse_response along the time axis.

Notes

Uses FFT-based convolution which is O(n log n) and highly parallelizable on GPU. The result is truncated to the same length as the input (causal convolution).