Kymatio: wavelet scattering transforms in Python with GPU acceleration

What Kymatio solves, and who it is for

Kymatio is an implementation of the wavelet scattering transform in Python, described by the README as "suitable for large-scale numerical experiments in signal processing and machine learning." The transform is a translation-invariant signal representation built as a convolutional network whose filters are fixed wavelet filters rather than learned weights. That single design decision defines the audience: researchers and engineers who want a deterministic, analyzable representation of a signal before any training happens, and who want to feed that representation into a downstream model.

The README frames the library around three needs: support for 1-D, 2-D and 3-D wavelets; integration of wavelet scattering into a deep learning architecture; and execution on CPU and GPU across major deep learning APIs. The Kymatio organization, per the README, associates the developers of several pre-existing scattering packages, including ScatNet, scattering.m, PyScatWave, WaveletScattering.jl and PyScatHarm. So the project is partly a consolidation effort: one Python API over algorithms that previously lived in separate MATLAB, Julia and Python codebases.

It is not a general signal processing toolkit. It computes scattering coefficients. If you want learned convolutions, you already have a framework for that, and Kymatio is not competing with it.

Frontend and backend: how the scattering transform is actually organized

The architecture is split into two parts. The frontend handles the user interface; the backend defines the functions needed to compute the scattering transform. The README states there are eight available frontend-backend pairs: NumPy (CPU), scikit-learn (CPU), pure PyTorch (CPU and GPU), PyTorch>=1.10 (CPU and GPU), PyTorch+scikit-cuda (GPU), PyTorch>=1.10+scikit-cuda (GPU), TensorFlow (CPU and GPU), Keras (CPU and GPU), and Jax (CPU and GPU).

That list is worth reading carefully, because it is not eight independent implementations. The algorithms are written in a high-level imperative paradigm, which the README says makes them portable to any Python array library that provides complex-valued linear algebra and a fast Fourier transform. The scattering computation itself runs in the Fourier domain. What changes between backends is where the arrays live and how the FFT is dispatched, not the mathematics of the filter banks.

The practical consequence: the NumPy and scikit-learn frontends are CPU-only and, in the README's words, slower. The torch, tensorflow, keras and jax frontends support GPU processing. The torch backend additionally offers an optimized skcuda path, which the README calls the fastest option for computing scattering transforms. The README also reports speedups relative to CPU-based MATLAB code of roughly 10x in 1D and 3D and roughly 100x in 2D, and points to the official benchmarks on kymat.io for detail. Those are the project's own figures from its own benchmark page, not an independent measurement.

Because the filters are fixed, the gradient story is unusual. The README notes that interfacing Kymatio into deep learning frameworks lets the programmer backpropagate the gradient of the wavelet scattering coefficients, integrating them into an end-to-end trainable pipeline such as a deep neural network. The scattering layer itself has no learnable parameters to update, but gradients still flow through it to whatever sits upstream or downstream.

Installing Kymatio and running a first Scattering2D transform

The README recommends running Kymatio in an Anaconda environment to simplify dependency installation, and gives pip as the package manager. The published requirements are Python >= 3.7 and SciPy >= 0.13, and the README's badge lists Python 3.8 through 3.11. Note the discrepancy with requirements.txt in the repository, which pins scipy<1.15. If you install from source rather than from PyPI, that pin is what you get.

pip install kymatio

After that, the smallest useful thing to do is instantiate a 2D scattering object and inspect its output shape. The README's NumPy example is the shortest path to a working object:

from kymatio.numpy import Scattering2D
scattering = Scattering2D(J=2, shape=(32, 32))

J=2 sets the number of scattering scales, and shape declares the input size the object expects. The same two arguments appear in every frontend example in the README, which is the point of the common API. To run the same transform inside a model, switch the import:

from kymatio.torch import Scattering2D
scattering = Scattering2D(J=2, shape=(32, 32))

Under PyTorch this object is a torch.nn.Module, so it can be placed in a Sequential alongside other layers. For Keras, the README shows the functional form, where Scattering2D is applied to an Input tensor:

from tensorflow.keras.layers import Input
from kymatio.keras import Scattering2D

inputs = Input(shape=(32, 32))
scattering = Scattering2D(J=2)(inputs)

If you want the skcuda path, the README requires two extra dependencies first and then a backend argument:

pip install scikit-cuda cupy

from kymatio.torch import Scattering2D

scattering = Scattering2D(J=2, shape=(32, 32), backend='torch_skcuda')

For source installs, the README gives the following sequence, with develop substituted for install for developer workflows:

pip install -r requirements.txt
python setup.py install

The repository layout has examples/1d/, examples/2d/ and examples/3d/ directories plus examples/datasets.py, so worked scripts exist beyond the README snippets. The README itself does not walk through running them.

Where Kymatio is the wrong tool

The fixed-filter design is the limitation as much as the feature. Because the wavelets are not learned, the representation cannot adapt to a task the way a trained convolutional front end can. If your problem is one where learned low-level filters measurably outperform fixed ones, Kymatio adds a preprocessing stage and a dependency without giving you anything the framework does not already provide. The README states the filters are fixed, not learned, which is a description of the method rather than a defect, but it does bound the set of problems where the library earns its place.

Platform support is narrower than the API surface suggests. The README says Linux and macOS are the two officially supported operating systems. Windows is not listed. The README does not document a Windows installation path, so anyone on Windows is outside what the project claims to support.

The dependency pin is another concrete constraint. requirements.txt specifies scipy<1.15. Installing from source into an environment that already has a newer SciPy will either conflict or force a downgrade, and the README does not discuss this pin or its consequences. That is a gap between the stated requirement (SciPy >= 0.13) and the repository's actual constraint file.

The README also does not document rollback, version compatibility guarantees between frontends, or what happens when a saved model using a Kymatio layer is loaded under a different backend version. Those are real questions for anyone putting a scattering layer into a production pipeline, and the documentation is silent on them.

Kymatio against a learned convolutional front end

The obvious alternative is to skip the scattering transform and let a convolutional network learn its own filters. The difference in approach is fundamental rather than incremental. A CNN initializes filters randomly and updates them by gradient descent against a loss; Kymatio fixes them as wavelet filters before training and never changes them. That means a scattering layer has no parameters to overfit, produces the same output for the same input regardless of training data, and gives you a representation you can reason about analytically. It also means the representation cannot specialize.

Within the scattering family itself, the README positions Kymatio as a consolidation of earlier packages: ScatNet, scattering.m, PyScatWave, WaveletScattering.jl and PyScatHarm. If you are already working in MATLAB or Julia, those remain the native options for their ecosystems. What Kymatio adds is the Python API, the frontend-backend split, and the ability to place a scattering transform inside a PyTorch, TensorFlow, Keras or Jax graph with gradient flow.

There is also a smaller alternative hiding in the README's own list: use the NumPy frontend and skip the deep learning frameworks entirely. If you only need scattering coefficients as features for a classical classifier, the scikit-learn frontend exposes Scattering2D as a Transformer, which composes with the rest of that library. Pulling in PyTorch or TensorFlow for a CPU-only feature extraction job is unnecessary weight.

Maintenance, licensing and what a version bump costs

The repository is not archived, and the last push was on 2026-06-09. That is roughly three months before the date of writing, so the project is not dormant, but the README does not document a release cadence or release history. The README documents installation from PyPI and from source but says nothing about deprecation policy, backend version support windows, or how breaking changes are announced.

The licence is BSD-3-Clause, stated in setup.py and in the README badge, with the licence file at LICENSE.md. That is a permissive licence, which generally means you can use, modify and redistribute the code with the copyright notice and disclaimer retained. The README also asks that you cite the 2020 Journal of Machine Learning Research paper if you use the package, and links both the paper and a BibTeX entry. Citation is a request, not a licence term, but it is the project's stated expectation for academic use.

Upgrade cost is where the frontend-backend split matters. Because the same Scattering2D signature is shared across eight pairs, changing backends is usually an import change plus a backend argument. Changing framework versions is the riskier move. The README distinguishes pure PyTorch from PyTorch>=1.10 as separate frontends, which implies version-specific code paths exist. It does not say what breaks when you cross that line. This is not legal advice; read LICENSE.md and your own obligations before shipping.

Editorial conclusion

Adopt Kymatio when you need a translation-invariant representation whose filters are fixed rather than learned, and you want it inside a PyTorch, TensorFlow, Keras or Jax pipeline. Do not adopt it if you need a learnable convolutional front end, or if you are limited to Windows, which the README does not list among the officially supported operating systems. Before committing, verify that your installed SciPy satisfies the scipy<1.15 pin in requirements.txt, and check whether the torch_skcuda backend is available for your CUDA setup, since the README calls it the fastest option.

Frequently asked questions

Official sources

1. Issues
2. kymatio/kymatio on GitHub
3. License: BSD-3-Clause
4. Project website
5. README