Kymatio: Fixed-Wavelet Scattering Transforms Across NumPy, PyTorch, TensorFlow and Jax

The representation Kymatio ships, and the audience it assumes

Kymatio implements the wavelet scattering transform: a translation-invariant signal representation built as a convolutional network whose filters are fixed wavelet filters rather than learned weights. The README states this directly, describing scattering transforms as "implemented as convolutional networks whose filters are not learned, but fixed (as wavelet filters)." That single design decision defines the audience. If your problem is classification or regression where the useful features are unknown and you have enough labelled data to learn them, a fixed filter bank is a constraint, not a feature. Kymatio is for the opposite situation: you have a signal or image prior that wavelets describe well, you want a representation that does not need training to become meaningful, and you want it inside a Python numerical or deep learning stack. The README frames the target as "large-scale numerical experiments in signal processing and machine learning," which is a fair description of who ends up using it. The library also carries a citation request: the JMLR paper by Andreux, Angles, Exarchakis and co-authors, listed in the README with a bibtex link. If you publish work built on it, that citation is part of the cost of use.

Frontend and backend: the split that explains every import path

The architecture is two-layered and the README is explicit about it. Each algorithm is packaged with a frontend and a backend. The frontend handles the user interface; the backend defines the functions needed to compute the transform. The README enumerates eight frontend-backend pairs: NumPy on CPU, scikit-learn on CPU, pure PyTorch on CPU and GPU, PyTorch>=1.10 on CPU and GPU, PyTorch plus scikit-cuda on GPU, PyTorch>=1.10 plus scikit-cuda on GPU, TensorFlow on CPU and GPU, Keras on CPU and GPU, and Jax on CPU and GPU. That list is longer than eight if you count the PyTorch variants separately, and the README itself says "eight available frontend-backend pairs" while listing more entries, so treat the count as approximate and read the list. The practical consequence is that the import path, not a configuration flag, selects your compute stack. `from kymatio.numpy import Scattering2D` gives you a CPU object with no framework dependency. `from kymatio.torch import Scattering2D` gives you a `torch.nn.Module`. `from kymatio.tensorflow import Scattering2D` gives you a `tf.Module`. `from kymatio.jax import Scattering2D` gives you a Jax object. The README also notes the algorithms are written in a high-level imperative paradigm, which is what makes them portable to any Python array library that provides complex-valued linear algebra and an FFT. That is the real portability claim: the transform needs complex arithmetic and a fast Fourier transform, and nothing more exotic.

Getting it running: pip, source installs, and the skcuda path

The standard install is one command: `pip install kymatio`. Dependencies are listed as Python >= 3.7 and SciPy >= 0.13, and the README recommends running inside an Anaconda environment because it simplifies installing the other dependencies. Linux and macOS are the two officially supported operating systems, and the badge at the top of the README advertises Python 3.8 through 3.11. From source, the sequence is `pip install -r requirements.txt` followed by `python setup.py install`, with `python setup.py develop` for developers who want an editable install. Instantiation is uniform across frontends: `Scattering2D(J=2, shape=(32, 32))` appears in the NumPy, PyTorch, TensorFlow and Jax examples, and the scikit-learn example uses the positional form `Scattering2D(2, (32, 32))`. The Keras example is the odd one out because it composes as a layer: you build `inputs = Input(shape=(32, 32))` and then `scattering = Scattering2D(J=2)(inputs)`. For GPU work beyond the default torch backend, the README gives a specific recipe: install `scikit-cuda` and `cupy` with pip, then pass `backend='torch_skcuda'` to the constructor. It states that this backend "currently provides the fastest performance in computing scattering transforms." Note what that sentence does not say: it gives no number, and the only figures in the README are comparisons against CPU-based MATLAB code, of order 10 in 1D and 3D and order 100 in 2D, with a pointer to the official benchmarks page for detail. Those are the project's own claims, not measurements I can reproduce here.

The J parameter and the shape you must declare up front

Every example in the README passes two arguments, `J` and `shape`, and that is not incidental. The scattering object is constructed for a fixed input geometry. `J=2` controls the number of wavelet scales, and `shape=(32, 32)` tells the object what spatial extent to build filter banks for. The README describes Kymatio as integrating "the construction of wavelet filter banks in 1D, 2D, and 3D, as well as memory-efficient algorithms for extracting wavelet scattering coefficients, under a common application programming interface." Filter bank construction at instantiation time means the object is tied to that shape. If your inputs vary in size, or if you change resolution between experiments, you are constructing a new scattering object rather than reusing one. Increasing J increases the number of scales and therefore the number of output channels, which grows the coefficient tensor you then feed downstream. The README does not state a formula for that growth, so if memory is your constraint, measure it on your own shape rather than assuming. The same applies to the 1D and 3D cases: the README asserts support for both, but the examples are all 2D, so the 1D and 3D APIs are documented by assertion rather than by worked code in the README itself.

Where it breaks down: fixed filters, framework coupling, and Windows

The clearest limitation is the one built into the name. Filters are fixed. If your task needs a representation that adapts to the data, Kymatio will not learn it for you, and no amount of training will change the wavelet bank. That makes it a poor fit for problems where the discriminative structure is not scale-and-translation-like, and it makes the choice of J and shape a real modelling decision rather than a hyperparameter you can tune away. The second limitation is coupling. Choosing a frontend means choosing a framework's installation, device placement and version constraints. The README lists a `PyTorch>=1.10` pair separately from a plain PyTorch pair, which implies version sensitivity in the torch path. The `torch_skcuda` backend adds two more dependencies, `scikit-cuda` and `cupy`, both of which are GPU-specific and will not help you on a CPU-only machine. The third limitation is platform. Linux and macOS are the officially supported operating systems; Windows is not listed, so treat it as unverified. Finally, the README's speedup figures compare against MATLAB code, not against other Python implementations, so they tell you about the GPU-versus-CPU gap in that comparison rather than about Kymatio against its Python peers.

The alternative worth weighing: a learned convolutional front end

The obvious alternative is to skip the scattering transform and let a standard convolutional network learn its first-layer filters from data. The difference is not cosmetic. A learned conv stack adapts its filters to the task and typically needs labelled data and training time to become useful; a scattering transform produces a deterministic, translation-invariant representation with no training at all, and the README's framing of backpropagation through scattering coefficients means you can still place it at the front of an end-to-end trainable pipeline. So the trade is fixed-and-immediate versus learned-and-data-hungry. A second alternative is the family of packages the README names as predecessors: ScatNet, scattering.m, PyScatWave, WaveletScattering.jl and PyScatHarm. The README says the Kymatio organization associates the developers of these packages, and that Kymatio's contribution is putting them under a common API with deep learning framework integration. If you are already committed to MATLAB or Julia, moving to Kymatio means moving your whole pipeline into Python, which is a bigger change than swapping a library. If you are in Python already, Kymatio's argument is that you get the same transform with a framework-native object.

Maintenance, licence, and what to check before you depend on it

The licence is BSD-3-Clause, per the README badge and the linked LICENSE.md file, which is permissive and places few obligations beyond attribution and the standard disclaimer. That is a low-friction choice for both academic and commercial use, though it is not legal advice and you should read the actual licence text for your own situation. On maintenance, the repository is not archived and the last push is recent, and the README carries CI and coverage badges, so there is an active build. The README does not describe a deprecation policy, a version support matrix beyond the Python badge, or a release cadence, so if you need long-term API stability guarantees you will not find them stated here. The upgrade risk sits mostly in the framework coupling: a major PyTorch, TensorFlow or Jax release can affect the corresponding frontend, and the README's separate PyTorch and PyTorch>=1.10 entries suggest that has already happened at least once. Pin your framework version alongside Kymatio, and test the specific frontend you import rather than assuming all eight behave identically.

Editorial conclusion

Adopt Kymatio if you already have a PyTorch, TensorFlow, Keras or Jax pipeline and you want a fixed, non-learned convolutional front end that stays differentiable end to end. Do not adopt it if you need a learned representation, if you cannot install the framework that matches your frontend, or if you are targeting Windows, since only Linux and macOS are listed as officially supported. Before committing, verify the shape and J parameters your data actually needs, confirm the installed Kymatio version exposes the frontend you intend to import, and check whether backend='torch_skcuda' plus scikit-cuda and cupy is worth the extra dependency for your input size.

Official sources

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