API Reference

Public API

transforms — NumPy/SciPy-backed transform utilities.

All public symbols are re-exported from transforms.core so callers can simply write:

from transforms import fast_dft, fft_real_forward

This package is a self-contained set of transform utilities inspired by IMSL Fortran Numerical Library Transforms chapter, backed by numpy.fft, scipy.fft, and scipy.signal.

transforms.fast_dft(x, inverse=False)

Compute the Discrete Fourier Transform of a complex 1-D array (IMSL FAST_DFT).

Delegates to numpy.fft.fft() for the forward transform and numpy.fft.ifft() for the inverse.

Parameters:

  • x (np.ndarray) – Complex 1-D input array of length N.

  • inverse (bool) – If True compute the inverse DFT. Defaults to False.

Returns:

Complex 1-D array of the same length as x containing

the (I)DFT coefficients.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fast_2dft(x, inverse=False)

Compute the 2-D Discrete Fourier Transform (IMSL FAST_2DFT).

Delegates to numpy.fft.fft2() / numpy.fft.ifft2().

Parameters:

  • x (np.ndarray) – Complex 2-D input array of shape (M, N).

  • inverse (bool) – If True compute the inverse 2-D DFT. Defaults to False.

Returns:

Complex 2-D array of the same shape as x.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 2-D or has zero size.

transforms.fast_3dft(x, inverse=False)

Compute the 3-D Discrete Fourier Transform (IMSL FAST_3DFT).

Delegates to numpy.fft.fftn() / numpy.fft.ifftn().

Parameters:

  • x (np.ndarray) – Complex 3-D input array of shape (L, M, N).

  • inverse (bool) – If True compute the inverse 3-D DFT. Defaults to False.

Returns:

Complex 3-D array of the same shape as x.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 3-D or has zero size.

transforms.fft_real_forward(x)

Compute the forward FFT of a real-valued 1-D array (IMSL FFTRF).

Returns the n//2 + 1 complex spectral coefficients (the one-sided spectrum). Delegates to numpy.fft.rfft().

Parameters:

x (np.ndarray) – Real-valued 1-D input array of length N.

Returns:

Complex 1-D array of length N//2 + 1 containing the

non-redundant half of the spectrum.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_real_backward(x, n=None)

Compute the inverse FFT of a one-sided complex spectrum back to real data (IMSL FFTRB).

Delegates to numpy.fft.irfft().

Parameters:

  • x (np.ndarray) – Complex 1-D input array of length N//2 + 1 (one-sided spectrum produced by fft_real_forward()).

  • n (int | None) – Length of the output real array. If None, defaults to 2*(len(x) - 1).

Returns:

Real-valued 1-D array of length n.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_real_init(n)

Initialise FFT pre-computation metadata for real data of length n (IMSL FFTRI).

In NumPy the twiddle factors are computed automatically, so this function acts as a documentation/compatibility stub. The returned dict can be passed to downstream routines that expect a params keyword, though the current implementations ignore it.

Parameters:

n (int) – The transform length for which metadata should be computed. Must be a positive integer.

Returns:

Pre-computation metadata with keys n (int), type

("real"), and twiddle (numpy.ndarray of the n-point twiddle factors).

Return type:

dict

Raises:

ValueError – If n is not a positive integer.

transforms.fft_complex_forward(x)

Compute the forward complex FFT (IMSL FFTCF).

Delegates to numpy.fft.fft().

Parameters:

x (np.ndarray) – Complex 1-D input array of length N.

Returns:

Complex 1-D array of length N containing the DFT

coefficients.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_complex_backward(x)

Compute the inverse complex FFT (IMSL FFTCB).

Delegates to numpy.fft.ifft().

Parameters:

x (np.ndarray) – Complex 1-D input array of length N (DFT spectrum).

Returns:

Complex 1-D array of length N — the inverse transform.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_complex_init(n)

Initialise complex FFT pre-computation metadata for length n (IMSL FFTCI).

Acts as a documentation/compatibility stub analogous to fft_real_init().

Parameters:

n (int) – The transform length. Must be a positive integer.

Returns:

Pre-computation metadata with keys n (int), type

("complex"), and twiddle (numpy.ndarray).

Return type:

dict

Raises:

ValueError – If n is not a positive integer.

transforms.fft_sine(x, inverse=False)

Compute the Discrete Sine Transform (IMSL FSINT).

Delegates to scipy.fft.dst() (type-2, norm='backward') for the forward transform and scipy.fft.idst() for the inverse.

Parameters:

  • x (np.ndarray) – Real-valued 1-D input array of length N.

  • inverse (bool) – If True compute the inverse DST. Defaults to False.

Returns:

Real-valued 1-D array of length N — the DST coefficients

or the reconstructed signal.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_sine_init(n)

Initialise sine transform metadata for length n (IMSL FSINI).

Parameters:

n (int) – The transform length. Must be a positive integer.

Returns:

Metadata dict with keys n (int) and type

("sine").

Return type:

dict

Raises:

ValueError – If n is not a positive integer.

transforms.fft_cosine(x, inverse=False)

Compute the Discrete Cosine Transform (IMSL FCOST).

Delegates to scipy.fft.dct() (type-2) for the forward transform and scipy.fft.idct() for the inverse.

Parameters:

  • x (np.ndarray) – Real-valued 1-D input array of length N.

  • inverse (bool) – If True compute the inverse DCT. Defaults to False.

Returns:

Real-valued 1-D array of length N — the DCT coefficients

or the reconstructed signal.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_cosine_init(n)

Initialise cosine transform metadata for length n (IMSL FCOSI).

Parameters:

n (int) – The transform length. Must be a positive integer.

Returns:

Metadata dict with keys n (int) and type

("cosine").

Return type:

dict

Raises:

ValueError – If n is not a positive integer.

transforms.fft_quarter_sine_forward(x)

Compute the quarter-wave sine transform forward pass (IMSL QSINF).

Uses the type-1 DST: scipy.fft.dst(x, type=1).

Parameters:

x (np.ndarray) – Real-valued 1-D input array of length N.

Returns:

Real-valued 1-D array of length N — the type-1 DST

coefficients.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_quarter_sine_backward(x)

Compute the quarter-wave sine transform backward pass (IMSL QSINB).

Uses scipy.fft.idst() with type=1.

Parameters:

x (np.ndarray) – Real-valued 1-D array of type-1 DST coefficients of length N.

Returns:

Real-valued 1-D array of length N — the reconstructed

signal.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_quarter_sine_init(n)

Initialise quarter sine transform metadata for length n (IMSL QSINI).

Parameters:

n (int) – The transform length. Must be a positive integer.

Returns:

Metadata dict with keys n (int) and type

("quarter_sine").

Return type:

dict

Raises:

ValueError – If n is not a positive integer.

transforms.fft_quarter_cosine_forward(x)

Compute the quarter-wave cosine transform forward pass (IMSL QCOSF).

Uses the type-2 DCT: scipy.fft.dct(x, type=2).

Parameters:

x (np.ndarray) – Real-valued 1-D input array of length N.

Returns:

Real-valued 1-D array of length N — the type-2 DCT

coefficients.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_quarter_cosine_backward(x)

Compute the quarter-wave cosine transform backward pass (IMSL QCOSB).

Uses scipy.fft.idct() with type=2.

Parameters:

x (np.ndarray) – Real-valued 1-D array of type-2 DCT coefficients of length N.

Returns:

Real-valued 1-D array of length N — the reconstructed

signal.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 1-D or has zero length.

transforms.fft_quarter_cosine_init(n)

Initialise quarter cosine transform metadata for length n (IMSL QCOSI).

Parameters:

n (int) – The transform length. Must be a positive integer.

Returns:

Metadata dict with keys n (int) and type

("quarter_cosine").

Return type:

dict

Raises:

ValueError – If n is not a positive integer.

transforms.fft_2d_forward(x)

Compute the 2-D forward FFT (IMSL FFT2D).

Delegates to numpy.fft.fft2().

Parameters:

x (np.ndarray) – Complex or real 2-D input array of shape (M, N).

Returns:

Complex 2-D array of shape (M, N) — the 2-D DFT

coefficients.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 2-D or has zero size.

transforms.fft_2d_backward(x)

Compute the 2-D backward (inverse) FFT (IMSL FFT2B).

Delegates to numpy.fft.ifft2().

Parameters:

x (np.ndarray) – Complex 2-D input array of shape (M, N) (DFT spectrum produced by fft_2d_forward()).

Returns:

Complex 2-D array of shape (M, N) — the inverse

transform.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 2-D or has zero size.

transforms.fft_3d_forward(x)

Compute the 3-D forward FFT (IMSL FFT3F).

Delegates to numpy.fft.fftn().

Parameters:

x (np.ndarray) – Complex or real 3-D input array of shape (L, M, N).

Returns:

Complex 3-D array of shape (L, M, N) — the 3-D DFT

coefficients.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 3-D or has zero size.

transforms.fft_3d_backward(x)

Compute the 3-D backward (inverse) FFT (IMSL FFT3B).

Delegates to numpy.fft.ifftn().

Parameters:

x (np.ndarray) – Complex 3-D input array of shape (L, M, N).

Returns:

Complex 3-D array of shape (L, M, N) — the inverse

transform.

Return type:

np.ndarray

Raises:

  • TypeError – If x is not a numpy.ndarray.

  • ValueError – If x is not 3-D or has zero size.

transforms.convolve_real(x, h, method='fft')

Compute the linear convolution of two real-valued 1-D arrays (IMSL RCONV).

Delegates to scipy.signal.fftconvolve() (method='fft') or scipy.signal.convolve() (method='direct').

Parameters:

  • x (np.ndarray) – Real-valued 1-D input signal of length N.

  • h (np.ndarray) – Real-valued 1-D filter / kernel of length M.

  • method (str) – Convolution method — 'fft' (default) or 'direct'.

Returns:

Real-valued 1-D array of length N + M - 1 containing

the full linear convolution.

Return type:

np.ndarray

Raises:

  • TypeError – If x or h is not a numpy.ndarray.

  • ValueError – If x or h is not 1-D, has zero length, or method is unrecognised.

transforms.convolve_complex(x, h)

Compute the linear convolution of two complex 1-D arrays (IMSL CCONV).

Delegates to scipy.signal.fftconvolve().

Parameters:

  • x (np.ndarray) – Complex 1-D input signal of length N.

  • h (np.ndarray) – Complex 1-D filter / kernel of length M.

Returns:

Complex 1-D array of length N + M - 1 containing the

full linear convolution.

Return type:

np.ndarray

Raises:

  • TypeError – If x or h is not a numpy.ndarray.

  • ValueError – If x or h is not 1-D or has zero length.

transforms.correlate_real(x, y)

Compute the cross-correlation of two real-valued 1-D arrays (IMSL RCORL).

Delegates to scipy.signal.correlate() with mode='full'.

Parameters:

  • x (np.ndarray) – Real-valued 1-D reference signal of length N.

  • y (np.ndarray) – Real-valued 1-D comparison signal of length M.

Returns:

Real-valued 1-D array of length N + M - 1 containing

the full cross-correlation sequence.

Return type:

np.ndarray

Raises:

  • TypeError – If x or y is not a numpy.ndarray.

  • ValueError – If x or y is not 1-D or has zero length.

transforms.correlate_complex(x, y)

Compute the cross-correlation of two complex 1-D arrays (IMSL CCORL).

Delegates to scipy.signal.correlate() with mode='full'.

Parameters:

  • x (np.ndarray) – Complex 1-D reference signal of length N.

  • y (np.ndarray) – Complex 1-D comparison signal of length M.

Returns:

Complex 1-D array of length N + M - 1 containing the

full cross-correlation sequence.

Return type:

np.ndarray

Raises:

  • TypeError – If x or y is not a numpy.ndarray.

  • ValueError – If x or y is not 1-D or has zero length.

transforms.inverse_laplace(F, t, method='talbot')

Compute the numerical inverse Laplace transform (IMSL INLAP).

Evaluates the inverse transform f(t) = L^{-1}[F(s)](t) at each time point in t using Talbot’s method (default) — a fixed-contour numerical inversion based on the Bromwich integral.

Parameters:

  • F (Callable[[complex], complex]) – Laplace-domain function. Must accept a single complex argument s and return a complex scalar.

  • t (np.ndarray) – 1-D array of positive time points at which to evaluate the inverse transform. All values must be > 0.

  • method (str) – Inversion method. Currently only 'talbot' is supported. Defaults to 'talbot'.

Returns:

Real-valued 1-D array of the same length as t

containing the approximate inverse Laplace transform values.

Return type:

np.ndarray

Raises:

  • TypeError – If t is not a numpy.ndarray or F is not callable.

  • ValueError – If t is not 1-D, contains non-positive values, or method is unrecognised.

transforms.inverse_laplace_smooth(F, t)

Compute the inverse Laplace transform for smooth functions (IMSL SINLP).

Uses the fixed Talbot contour (Abate & Valko, 2004) with N=32 quadrature points — the same as inverse_laplace(). For smooth F the two functions give effectively identical results; this variant is provided for IMSL API compatibility (SINLP vs INLAP).

Parameters:

  • F (Callable[[complex], complex]) – Laplace-domain function. Must accept a single complex argument s and return a complex scalar.

  • t (np.ndarray) – 1-D array of positive time points at which to evaluate the inverse transform.

Returns:

Real-valued 1-D array of the same length as t

containing the approximate inverse Laplace transform values.

Return type:

np.ndarray

Raises:

  • TypeError – If t is not a numpy.ndarray or F is not callable.

  • ValueError – If t is not 1-D or contains non-positive values.

transforms.launch_documentation(opener=<function open>, package_dir=None)

Launch package documentation in a web browser.

The launcher opens local HTML documentation only.

Parameters:

  • opener (Callable[[str], bool]) – Browser opener function. Defaults to webbrowser.open.

  • package_dir (Path | None) – Optional package directory override used for tests. Defaults to the directory of this module.

Returns:

The file://... URI opened.

Return type:

str

Raises:

FileNotFoundError – If no local documentation index can be located.