API reference

The package exports the full functional and module APIs at the top level (import torchwavelets as tw). The compat submodule mirrors the pytorch_wavelets API.

Precision contract

Every transform preserves the input dtype (fp16/bf16/fp32/fp64). The DTCWT family is the documented exception: half and bfloat16 inputs are computed in float32 (no complex16 kernels) and returned as float32/complex64; it also runs in an autocast-disabled scope.

Discrete wavelet transform

1-D

transform1d

1-D discrete wavelet transform (functional and module API).

The module API resolves its filters into registered buffers at construction time (eager) and only performs torch ops (.to(dtype, device) + convs) in forward, so it is fully traceable by torch.compile.

Classes

DWT1D

Bases: Module

1-D DWT module.

Parameters:

Name	Type	Description	Default
J	int	number of decomposition levels.	1
wave	str or Wavelet or tuple	as in :func:dwt1d.	'db1'
mode	str	as in :func:dwt1d.	'symmetric'

The precision follows the input tensor: feed a float16 tensor and the output is float16, regardless of the dtype used at construction time. The module is torch.compile-compatible (filters are resolved eagerly at construction; only torch ops run in forward).

IDWT1D

Bases: Module

1-D inverse DWT module (see :func:idwt1d).

Functions:

dwt1d

dwt1d(x, wave='db1', mode='symmetric', level=1)

Forward 1-D DWT.

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, L) input.	required
wave	str or Wavelet or tuple	wavelet name, pywt.Wavelet or custom filter bank.	'db1'
mode	str	boundary mode.	'symmetric'
level	int	number of decomposition levels (0 returns (x, [])).	1

Returns:

Type	Description
Tensor	tuple[torch.Tensor, list[torch.Tensor]]: (yl, yh) where yl is
list[Tensor]	the final lowpass of shape (N, C, L') and yh is a list of
tuple[Tensor, list[Tensor]]	level highpass tensors, finest first. The output dtype matches the
tuple[Tensor, list[Tensor]]	input dtype.

idwt1d

idwt1d(coeffs, wave='db1', mode='symmetric')

Inverse 1-D DWT.

Parameters:

Name	Type	Description	Default
coeffs	tuple	(yl, yh) as returned by :func:dwt1d (any highpass entry may be None, in which case it is treated as zeros).	required
wave	str or Wavelet or tuple	as in :func:dwt1d.	'db1'
mode	str	as in :func:dwt1d.	'symmetric'

Returns:

Type	Description
Tensor	torch.Tensor: reconstructed (N, C, L') tensor (dtype matches the
Tensor	coefficients).

This is a pywt.waverec-style inverse: the coefficient pyramid from :func:dwt1d is inverted level by level, and (like pywt.waverec) an odd-length previous level's extra sample is dropped inside the reconstruction. Unlike pywt.idwt (single-level), the lowpass/detail pair of a level does not need to match in length.

2-D

transform2d

2-D discrete wavelet transform (functional and module API).

The module API resolves its filters into registered buffers at construction time (eager) and only performs torch ops (.to(dtype, device) + convs) in forward, so it is fully traceable by torch.compile.

Classes

DWT2D

Bases: Module

2-D DWT module.

Parameters:

Name	Type	Description	Default
J	int	number of decomposition levels.	1
wave	str or Wavelet or tuple	as in :func:dwt2d.	'db1'
mode	str	as in :func:dwt2d.	'symmetric'

The precision follows the input tensor: feed a float16 tensor and the output is float16, regardless of the dtype used at construction time. The module is torch.compile-compatible (filters are resolved eagerly at construction; only torch ops run in forward).

IDWT2D

Bases: Module

2-D inverse DWT module (see :func:idwt2d).

Functions:

dwt2d

dwt2d(x, wave='db1', mode='symmetric', level=1)

Forward 2-D DWT (separable, row then column filtering).

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, H, W) input.	required
wave	str or Wavelet or tuple	wavelet name, pywt.Wavelet or custom filter bank.	'db1'
mode	str	boundary mode.	'symmetric'
level	int	number of decomposition levels (0 returns (x, [])).	1

Returns:

Type	Description
Tensor	(yl, yh) where yl is the final lowpass (N, C, H', W') and
list[Tensor]	yh is a list of level tensors of shape
tuple[Tensor, list[Tensor]]	(N, C, 3, H'', W'') holding the (LH, HL, HH) subbands
tuple[Tensor, list[Tensor]]	(finest first). LH/HL/HH match PyWavelets'
tuple[Tensor, list[Tensor]]	cH/cV/cD. The output dtype matches the input dtype.

idwt2d

idwt2d(coeffs, wave='db1', mode='symmetric')

Inverse 2-D DWT.

Parameters:

Name	Type	Description	Default
coeffs	tuple	(yl, yh) as returned by :func:dwt2d (any highpass entry may be None, in which case it is treated as zeros).	required
wave	str or Wavelet or tuple	as in :func:dwt2d.	'db1'
mode	str	as in :func:dwt2d.	'symmetric'

Returns:

Type	Description
Tensor	torch.Tensor: reconstructed (N, C, H', W') tensor (dtype matches
Tensor	the coefficients).

Dual-tree complex wavelet transform

1-D

transform1d

1-D dual-tree complex wavelet transform (functional and module API).

The 1-D DTCWT produces complex bandpass coefficients from the two decimation phases of the highpass filtering (real = even phase, imaginary = odd phase), so a single 1-D DTCWT level yields a complex band that is approximately shift-invariant and analytic. Levels 2+ use the quarter-sample-shift filters, exactly as in the 2-D transform.

Precision follows the input (float32 -> complex64, float64 -> complex128); half inputs are computed in float32 (no usable complex16 kernels). Boundary handling is Kingsbury's symmetric extension.

Classes

DTCWT1D

Bases: Module

1-D DTCWT module (see :func:dtcwt1d).

IDTCWT1D

Bases: Module

1-D inverse DTCWT module (see :func:idtcwt1d).

Functions:

dtcwt1d

dtcwt1d(x, biort='near_sym_a', qshift='qshift_a', J=3, include_scale=False)

Forward 1-D dual-tree complex wavelet transform.

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, L) input.	required
biort	str	filter bank name.	'near_sym_a'
qshift	str	filter bank name.	'qshift_a'
J	int	number of levels (0 returns (x, None)).	3
include_scale	bool	also return the intermediate lowpasses.	False

Odd-length inputs are padded by one sample (the last sample is repeated) and the inverse returns the padded length L + 1, matching the 2-D transform's convention.

Returns:

Type	Description
Tensor | list[Tensor]	tuple[torch.Tensor, list[torch.Tensor]]: (yl, yh): lowpass
list[Tensor] | None	(N, C, L') and a list of J complex bandpasses (N, C, L'')
tuple[Tensor | list[Tensor], list[Tensor] | None]	(finest first).

idtcwt1d

idtcwt1d(coeffs, biort='near_sym_a', qshift='qshift_a')

Inverse 1-D DTCWT (exact inverse of :func:dtcwt1d).

2-D

transform2d

2-D dual-tree complex wavelet transform (functional and module API).

The bandpass coefficients are native complex tensors (torch.complex64 / torch.complex128): yh[j] has shape (N, C, 6, H, W) with the 6 orientations (15, 45, 75, 105, 135, 165 degrees) along dim 2.

Precision follows the input: float32 -> complex64, float64 -> complex128. Half inputs (float16/bfloat16) are computed in float32 and return complex64 (torch has no usable complex16 kernels). Boundary handling follows Kingsbury's symmetric extension (the DTCWT is designed for it); other modes are not supported.

Classes

DTCWT2D

Bases: Module

2-D DTCWT module (see :func:dtcwt2d).

Filters are resolved eagerly at construction; the forward pass is pure torch ops, so the module is torch.compile-compatible.

IDTCWT2D

Bases: Module

2-D inverse DTCWT module (see :func:idtcwt2d).

Functions:

dtcwt2d

dtcwt2d(x, biort='near_sym_a', qshift='qshift_a', J=3, skip_hps=False, include_scale=False, o_dim=2)

Forward 2-D dual-tree complex wavelet transform.

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, H, W) input.	required
biort	str	filter bank name (see :mod:torchwavelets.dtcwt.coeffs).	'near_sym_a'
qshift	str	filter bank name.	'qshift_a'
J	int	number of levels (0 returns (x, None)).	3
skip_hps	bool or list[bool]	one per level, to skip bandpasses.	False
include_scale	bool or list[bool]	one per level, to also return the intermediate lowpasses.	False
o_dim	int	dimension for the 6 orientations (default 2).	2

Returns:

Type	Description
Tensor	tuple[torch.Tensor, list[torch.Tensor]]: (yl, yh): lowpass
list[Tensor]	(N, C, H', W') and a list of J complex bandpasses
tuple[Tensor, list[Tensor]]	(N, C, 6, H'', W'') (finest first).

idtcwt2d

idtcwt2d(coeffs, biort='near_sym_a', qshift='qshift_a', o_dim=2)

Inverse 2-D DTCWT.

Parameters:

Name	Type	Description	Default
coeffs	tuple	(yl, yh) as returned by :func:dtcwt2d (any bandpass may be None, treated as zeros).	required
biort	str	as in :func:dtcwt2d.	'near_sym_a'
qshift	str	as in :func:dtcwt2d.	'qshift_a'
o_dim	int	as in :func:dtcwt2d.	2

Returns:

Type	Description
Tensor	torch.Tensor: reconstructed (N, C, H, W) tensor.

3-D

transform3d

3-D dual-tree complex wavelet transform (functional and module API).

The 3-D DTCWT (Kingsbury's design, as in the dtcwt numpy package) runs four separable trees with the level-1 biorthogonal and level-2+ quarter-sample-shift filters on a doubled work grid and combines the octant outputs into 28 complex orientation subbands per level (7 (H/L) face combinations x 4 subbands each).

Precision follows the input (float32 -> complex64, float64 -> complex128); half inputs are computed in float32. Boundary handling is Kingsbury's symmetric extension (ext_mode=4: each input dimension must be even; higher levels are edge-padded to a multiple of 4).

Classes

DTCWT3D

Bases: Module

3-D DTCWT module (see :func:dtcwt3d).

IDTCWT3D

Bases: Module

3-D inverse DTCWT module (see :func:idtcwt3d).

Functions:

dtcwt3d

dtcwt3d(x, biort='near_sym_a', qshift='qshift_a', J=3)

Forward 3-D DTCWT.

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, D, H, W) input with even spatial dims.	required
biort	str	filter bank name.	'near_sym_a'
qshift	str	filter bank name.	'qshift_a'
J	int	number of levels.	3

Returns:

Type	Description
Tensor	tuple[torch.Tensor, list[torch.Tensor]]: (yl, yh): real lowpass
list[Tensor] | None	(N, C, D', H', W') and a list of J complex bandpasses
tuple[Tensor, list[Tensor] | None]	(N, C, D'', H'', W'', 28) (finest first).

idtcwt3d

idtcwt3d(coeffs, biort='near_sym_a', qshift='qshift_a')

Inverse 3-D DTCWT (exact inverse of :func:dtcwt3d).

DTCWT scattering

lowlevel

Dual-tree complex wavelet scattering layers.

A scattering layer applies one (or two) DTCWT scale(s) with the smooth modulus sqrt(|Wx|^2 + magbias^2) - magbias and stacks the results along the channel dimension. With the DTCWT's near shift-invariance this gives locally shift-invariant feature maps for a single, cheap layer — the classic DTCWT scattering front-end.

The implementation is built directly on the complex-native DTCWT, so no custom autograd.Function is needed: gradients flow through the complex ops, autocast works, and the module is torch.compile-compatible.

Classes

ScatLayer

Bases: Module

One order of scattering at a single scale (level-1 DTCWT).

Parameters:

Name	Type	Description	Default
biort	str	level-1 biorthogonal filter bank name.	'near_sym_a'
mode	str	boundary handling (only 'symmetric' is supported).	'symmetric'
magbias	float	smoothing bias of the modulus.	0.01
combine_colour	bool	for 3-channel input, combine colour channels into a single set of 6 orientation magnitudes (output has 3+6 channels instead of 1+6*C).	False

Returns a feature map (N, 1 + 6*C, H/2, W/2) (or (N, 9, H/2, W/2) with combine_colour), the lowpass followed by the invariant terms.

ScatLayerj2

Bases: Module

Two scales of scattering with second-order terms.

Applies the level-1 biorthogonal and level-2 qshift DTCWT filters (the correct two-scale filter set, unlike stacking two :class:ScatLayer).

Returns (N, 49*C, H/4, W/4): C lowpass + 12*C first-order invariants (scales 1 and 2) + 36*C second-order invariants (or (N, 3 + 12 + 36, ...) with combine_colour).

network

General (arbitrary-order) DTCWT scattering network.

A scattering network computes locally shift-invariant feature maps by iterating wavelet bandpasses with the smooth modulus sqrt(|Wx|^2 + b^2) - b and smoothing the intermediate invariants with the wavelet lowpass. With the DTCWT's near shift-invariance this gives a small, cheap, highly invariant front-end for classification and segmentation.

Paths are sequences of increasing scales (j1 < j2 < ... < jm) with m <= max_order. For each path the network returns one invariant: avg_pool2d(lowpass, 2) when the path can still be extended (the smoothed modulus feeding the next order) and the raw |bandpass| at the terminal paths. With (J=2, max_order=2) the output matches :class:~torchwavelets.scatter.lowlevel.ScatLayerj2 exactly.

Shift invariance: the raw level-1 modulus |W_1 x| is only weakly shift invariant (the single-tree level-1 design), so individual raw bandpass invariants drift with sub-scale shifts; the smoothed invariants (pooled lowpasses) and the order-0 lowpass are exactly invariant at dyadic integer shifts, and the invariance improves with scale.

Classes

DTCWTScattering

Bases: Module

DTCWT scattering network module (see :func:dtcwt_scattering).

Functions:

dtcwt_scattering

dtcwt_scattering(x, J=3, max_order=2, biort='near_sym_a', qshift='qshift_a', magbias=0.01)

Forward DTCWT scattering network.

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, H, W) input.	required
J	int	number of wavelet scales.	3
max_order	int	maximum scattering order.	2
biort	str	filter bank name.	'near_sym_a'
qshift	str	filter bank name.	'qshift_a'
magbias	float	smoothing bias of the modulus.	0.01

Returns:

Type	Description
Tensor	tuple[torch.Tensor, list[tuple[tuple[int, ...], torch.Tensor]]]:
list[tuple[tuple[int, ...], Tensor]]	(s0, invariants): the smoothed order-0 lowpass
tuple[Tensor, list[tuple[tuple[int, ...], Tensor]]]	(N, C, H/2^J, W/2^J) and a list of (path, tensor) pairs, one
tuple[Tensor, list[tuple[tuple[int, ...], Tensor]]]	per path (orders 1..max_order, ordered by order then scale). The
tuple[Tensor, list[tuple[tuple[int, ...], Tensor]]]	invariant size depends only on the path's final scale jm:
tuple[Tensor, list[tuple[tuple[int, ...], Tensor]]]	H/2^jm.

Stationary (undecimated) wavelet transform

transform

Stationary (undecimated) wavelet transform: functional and module API.

The SWT (algorithm a trous) keeps every subband at the input resolution by dilating the analysis filters by 2**(level-1) and skipping decimation. Coefficients follow the PyWavelets conventions exactly (coarsest first), and iswt / iswt2 are exact inverses (verified bit-for-bit against pywt by the parity tests).

Inputs must be divisible by 2**level along every transformed axis, as required by the stationary transform (PyWavelets raises the same error).

Classes

SWT1D

Bases: Module

1-D stationary wavelet transform module (see :func:swt1d).

ISWT1D

Bases: Module

1-D inverse stationary wavelet transform module (see :func:iswt1d).

SWT2D

Bases: Module

2-D stationary wavelet transform module (see :func:swt2d).

ISWT2D

Bases: Module

2-D inverse stationary wavelet transform module (see :func:iswt2d).

Functions:

swt1d

swt1d(x, wave, level, norm=False)

1-D stationary wavelet transform.

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, L) input.	required
wave	str or Wavelet or tuple	wavelet name / bank (see :func:torchwavelets.core.filters.filter_bank).	required
level	int	number of scales.	required
norm	bool	normalize so the coefficient energy equals the input energy (orthogonal wavelets only, like PyWavelets).	False

Returns:

Type	Description
list[tuple[Tensor, Tensor]]	list[tuple[torch.Tensor, torch.Tensor]]: ``[(cA_n, cD_n), ...,
list[tuple[Tensor, Tensor]]	(cA_1, cD_1)](coarsest first), every subband of shape(N, C, L)``.

iswt1d

iswt1d(coeffs, wave, norm=False)

Inverse 1-D stationary wavelet transform (exact inverse of :func:swt1d).

swt2d

swt2d(x, wave, level, norm=False)

2-D stationary wavelet transform.

Parameters:

Name	Type	Description	Default
x	Tensor	(N, C, H, W) input.	required
wave	str or Wavelet or tuple	as in :func:swt1d.	required
level	int	as in :func:swt1d.	required
norm	bool	as in :func:swt1d.	False

Returns:

Type	Description
list[tuple[Tensor, tuple[Tensor, Tensor, Tensor]]]	list[tuple[torch.Tensor, tuple[torch.Tensor, torch.Tensor, torch.Tensor]]]:
list[tuple[Tensor, tuple[Tensor, Tensor, Tensor]]]	[(cA_j, (cH_j, cV_j, cD_j)), ...] (coarsest first), all subbands
list[tuple[Tensor, tuple[Tensor, Tensor, Tensor]]]	of shape (N, C, H, W).

iswt2d

iswt2d(coeffs, wave, norm=False)

Inverse 2-D stationary wavelet transform (exact inverse of :func:swt2d).

Wavelet packets

packets

Wavelet packets (full binary decomposition tree) for 1D and 2D.

A wavelet packet decomposes both the approximation AND the detail bands at every level, producing a full binary (1D) or quaternary (2D) tree. The API mirrors pywt.WaveletPacket / pywt.WaveletPacket2D: nodes are accessed by path ("aad", "av", ...), the tree is built with decompose(), reconstructed with reconstruct(), and coefficients match PyWavelets bit-for-bit (verified by the parity tests).

All node data are torch tensors of shape (N, C, L) (1D) or (N, C, H, W) (2D); the precision follows the input dtype.

Classes

WaveletPacket

Bases: BaseNode

1-D wavelet packet decomposition tree.

Parameters:

Name	Type	Description	Default
data	Tensor	(N, C, L) input (a 1-D tensor is promoted to (1, 1, L)).	required
wavelet	str or Wavelet or tuple	as in :func:torchwavelets.dwt1d.	required
mode	str	as in :func:torchwavelets.dwt1d.	'symmetric'
maxlevel	int	maximum decomposition depth (default: pywt's rule).	None
axis	int	the signal axis (default -1, any of the three dims).	-1

Children are named 'a' (approximation) and 'd' (detail).

WaveletPacket2D

Bases: BaseNode

2-D wavelet packet decomposition tree.

Parameters:

Name	Type	Description	Default
data	Tensor	(N, C, H, W) input (a 2-D tensor is promoted to (1, 1, H, W)).	required
wavelet	str or Wavelet or tuple	as in :func:torchwavelets.dwt2d.	required
mode	str	as in :func:torchwavelets.dwt2d.	'smooth'
maxlevel	int	maximum decomposition depth (default: pywt's rule).	None
axes	tuple[int, int]	the transformed axes ((-2, -1) only).	(-2, -1)

Children are named 'a' (LL), 'h' (LH), 'v' (HL), 'd' (HH), following PyWavelets' convention ('h'/'v' match cH/cV).

pytorch_wavelets compatibility

compat

Drop-in compatibility with the pytorch_wavelets API.

The upstream class names are plain aliases: the constructor signatures and call semantics are identical, only the semantics are fixed (precision follows the input dtype, autocast works, and boundary handling matches PyWavelets exactly). For the DTCWT, the bandpass coefficients are converted from the native complex format to the upstream (..., 2) real/imag layout.

Classes

DWTForward

Bases: DWT2D

pytorch_wavelets-compatible 2-D DWT forward (upstream defaults).

DWTInverse

Bases: IDWT2D

pytorch_wavelets-compatible 2-D DWT inverse (upstream defaults).

DWT1DForward

Bases: DWT1D

pytorch_wavelets-compatible 1-D DWT forward (upstream defaults).

DWT1DInverse

Bases: IDWT1D

pytorch_wavelets-compatible 1-D DWT inverse (upstream defaults).

DTCWTForward

Bases: DTCWT2D

pytorch_wavelets-compatible DTCWT forward.

Returns bandpasses in the upstream layout (N, C, 6, H, W, 2) (real and imaginary parts along the last dimension). ri_dim must be the default -1 (the native complex layout is fixed).

DTCWTInverse

Bases: IDTCWT2D

pytorch_wavelets-compatible DTCWT inverse (accepts the upstream (..., 2) real/imag layout or the native complex format).

Boundary modes and filter banks

modes

Boundary modes: PyWavelets-exact padding for all supported modes.

Attributes

SUPPORTED_MODES module-attribute

SUPPORTED_MODES = ('zero', 'symmetric', 'reflect', 'periodization', 'periodic', 'constant', 'replicate', 'smooth')

Functions:

validate_mode

validate_mode(mode)

Normalize mode (accepts pywt aliases like per/wrap/edge).

filters

Filter-bank handling: PyWavelets-compatible wavelets and custom banks.

Custom banks are validated for perfect reconstruction at creation time, so a biorthogonal bank passed as a 2-tuple (which assumes orthogonality) raises immediately instead of silently producing a wrong inverse.

Classes

FilterBank dataclass

A 1-D two-channel filter bank in PyWavelets' natural (non-reversed) order.

Attributes:

Name	Type	Description
h0	ndarray	analysis lowpass (pywt.Wavelet.dec_lo).
h1	ndarray	analysis highpass (pywt.Wavelet.dec_hi).
g0	ndarray	synthesis lowpass (pywt.Wavelet.rec_lo).
g1	ndarray	synthesis highpass (pywt.Wavelet.rec_hi).

Attributes

length property

length

Filter length (number of taps).

Functions:

filter_bank

filter_bank(wave)

Resolve wave to a :class:FilterBank.

wave may be a PyWavelets wavelet name ("db4"), a :class:pywt.Wavelet, a 2-tuple (h0, h1) (orthogonal custom bank), or a 4-tuple (h0, h1, g0, g1) (general bank). Custom banks are validated for perfect reconstruction and raise ValueError otherwise.