# WTConv replaces the strided convolution with a wavelet decomposition

> WTConv is the ECCV 2024 research code for wavelet convolutions, a depthwise convolution that reaches a large receptive field without stacking many layers. It ships as a drop-in layer, a timm-registered WTConvNeXt family, and a fast path with CUDA, Metal and Triton backends.

**BGU-CS-VIL/WTConv** — Wavelet Convolutions for Large Receptive Fields. ECCV 2024.

- Repository: https://github.com/BGU-CS-VIL/WTConv
- Stars: 608 · Forks: 24
- Language: Python
- License: MIT
- Published: 2026-10-22 · Updated: 2026-10-22 · Language: en
- Canonical page: https://hysenlabs.com/projects/bgu-cs-vil-wtconv

## The receptive field problem WTConv was written to solve

A depthwise convolution with a kernel of size three sees three pixels at a time. To see a wide slice of an image, a network has to stack many layers, and every extra layer costs memory and compute. WTConv attacks that cost from a different direction: it applies a wavelet decomposition to the feature map first, and the decomposition spreads information across the tensor before the convolution even runs.

The project is the code release for the paper Wavelet Convolutions for Large Receptive Fields, accepted at ECCV 2024, authored by Shahaf E. Finder, Roy Amoyal, Eran Treister and Oren Freifeld from Ben-Gurion University. The arXiv entry is 2407.05848. The repository also contains erf.py and an outputs_erf directory, which is the effective receptive field analysis that accompanies the method.

The audience is a computer vision researcher or engineer who trains convolutional backbones and needs a wide context without a transformer. The claim in the title is about receptive field size, not about accuracy on a leaderboard, and the artefacts shipped here (a layer, a model family, an ERF script) match that framing: this is a component you drop into your own network, not a finished application.

## WTConv2d as a single layer inside an existing CNN

The primary entry point is a class you import and drop in place of a depthwise convolution. The documentation gives this usage:

```python
from wtconv import WTConv2d

conv_dw = WTConv2d(32, 32, kernel_size=5, wt_levels=3)
```

The arguments shown are channels in, channels out, the kernel size, and wt_levels, which is the number of wavelet decomposition levels the layer performs. The wtconv directory holds that implementation. Everything else in the package is arranged around the same idea: a wtconvnext directory for the model family, a semantic_segmentation directory for a downstream task, a train.py and validate.py at the root, and the fast_wtconv directory for the accelerated version.

Because the layer is a normal PyTorch module, the constraint is dependency weight rather than API friction. The stated requirements are Python 3.12, timm 1.0.7 and PyWavelets 1.6.0. PyWavelets is the wavelet transform library doing the actual decomposition, and the pinned timm version matters because the model family is registered against timm's registry.

The June 11, 2025 update added WTConv1d, implemented for a separate project called TimePoint, which extends the same idea to one dimensional sequences rather than images.

## WTConvNeXt registers into timm's model registry

For people who want the whole backbone rather than a single layer, the project provides WTConvNeXt and registers it with timm. The documentation describes importing wtconvnext and then calling timm's create_model:

```python
import wtconvnext

model = create_model(
    "wtconvnext_tiny",
    pretrained=False,
    num_classes=1000
)
```

The registration happens as a side effect of importing the wtconvnext module, so a missing import is the usual cause of a model name that timm cannot resolve. Three sizes are released, with ImageNet-1k results at 224x224 resolution: WTConvNeXt-T at 82.5 top-1 accuracy with 30M parameters and 4.5G FLOPs, WTConvNeXt-S at 83.6 with 54M parameters and 8.8G FLOPs, and WTConvNeXt-B at 84.1 with 93M parameters and 15.5G FLOPs. Trained checkpoints for each size are linked from the results table.

The alternative to this route is the plain timm model zoo. WTConvNeXt is a NeXt-style backbone with the convolution replaced, so a team that wants a comparison point can train the unmodified NeXt model under the same recipe and change one line of configuration. The WTConvNeXt code and the training and validation scripts were adapted from the timm library, which is acknowledged explicitly and means the recipes follow timm conventions rather than inventing a new training scheme.

## Training on ImageNet-1k with the timm script and a fixed effective batch size

Training uses a script taken from timm. The single GPU command for WTConvNeXt-T looks like this:

```sh
python train.py --model wtconvnext_tiny --drop-path 0.1 \
                --data-dir IMAGENET_PATH \
                --epochs 300 --warmup-epochs 20 \
                --batch-size 64 --grad-accum-steps 64 --sched-on-updates \
                --lr 4e-3 --weight-decay 5e-2 \
                --opt adamw --layer-decay 1.0 \
                --aa rand-m9-mstd0.5-inc1 \
                --reprob 0.25 --mixup 0.8 --cutmix 1.0 \
                --model-ema --model-ema-decay 0.9999 \
                --output checkpoints/wtconvnext_tiny_300/
```

The learning rate of 4e-3 with AdamW, 300 epochs, a 20 epoch warmup, RandAugment with mixup and cutmix, and exponential moving average at 0.9999 are all standard timm settings for a large ImageNet run. What matters most is the batch arithmetic. The documentation states that the effective batch size should be 4096, calculated as gpus times batch-size times grad-accum-steps, and gives an example of a single machine with 4 GPUs using batch-size 64 and grad-accum-steps 16.

Distributing the run uses torchrun, and the accumulation steps drop accordingly:

```sh
torchrun --nproc-per-node=4  \
         python train.py --model wtconvnext_tiny --drop-path 0.1 \
                --data-dir IMAGENET_PATH \
                --epochs 300 --warmup-epochs 20 \
                --batch-size 64 --grad-accum-steps 16 --sched-on-updates \
                --lr 4e-3 --weight-decay 5e-2 \
                --opt adamw --layer-decay 1.0 \
                --aa rand-m9-mstd0.5-inc1 \
                --reprob 0.25 --mixup 0.8 --cutmix 1.0 \
                --model-ema --model-ema-decay 0.9999 \
                --output checkpoints/wtconvnext_tiny_300/
```

Drop path differs between the sizes: 0.1 for tiny, 0.4 for the small single-GPU command, and 0.5 for the base multi-GPU command. The validation script is the matching counterpart:

```sh
python validate.py --model wtconvnext_tiny \
                   --data-dir IMAGENET_PATH \
                   --checkpoint WTConvNeXt_tiny_5_300e_ema.pth
```

The README does not document a fine-tuning recipe for a downstream dataset, and the semantic_segmentation directory is present without documented commands for it.

## fast_wtconv adds CUDA, Metal and Triton backends

The most recent update, dated February 7, 2026, added fast_wtconv, described as a high-performance implementation with CUDA, Metal and Triton backends, and pointing readers to fast_wtconv/README.md for details. The motivation is straightforward: the reference implementation performs a wavelet decomposition on every forward pass, and that transform is the expensive part, not the convolution.

Three backends cover most hardware. CUDA serves NVIDIA GPUs, Metal covers Apple Silicon through MPS, and Triton opens the door to custom kernels compiled at runtime. In practice this means a machine on a Mac can run the layer without falling back to a slow path, which matters because the authors are based at Ben-Gurion University and the timm-based recipes were developed on academic hardware.

The honest caveat is that the documentation for this part lives in a separate file, fast_wtconv/README.md, and the top-level readme does not summarise its interface. So the question of whether fast_wtconv is a drop-in replacement or a separate module with its own import path is answered there, not here. That is the first file to open if you are evaluating the layer for production latency rather than for a paper experiment.

## Research code with a MIT licence and no released versions

The licence is MIT, which is the simplest case for adoption: you can use the code commercially, modify it, and redistribute it, keeping the copyright notice and the licence text. The repository states this directly and points to the LICENSE file. There is no CLA to sign and no separate model licence mentioned for the released checkpoints, so the weights inherit the same terms as the code unless the authors say otherwise elsewhere.

On upkeep, the last push was on 2026-08-12 and the repository has no GitHub releases at all, so there is no versioned artifact to pin. There is no package on PyPI mentioned, no supported Python version matrix beyond the stated Python 3.12 requirement, and no continuous integration configuration in the repository root. The update list is short and dated, which makes the trajectory clear: the original ECCV code, the WTConv1d extension for TimePoint in June 2025, and the accelerated backends in February 2026.

That makes this a repository to vendor or pin to a commit, not a dependency to declare and forget. The absence of releases means the code you get is whatever the default branch holds, and the maintainers are free to change it.

## Conclusion

WTConv suits a vision researcher who needs a large receptive field without the depth of a very deep CNN, and who is already working in PyTorch and timm. It is the wrong tool for a production service that needs a stable, versioned dependency with published wheels and support commitments, and for anyone who cannot add PyWavelets and timm 1.0.7 to their dependency set. Before adopting it, run the ImageNet-1k validation command with the released WTConvNeXt-T checkpoint to confirm the numbers reproduce on your hardware, then read fast_wtconv/README.md to see whether the CUDA, Metal or Triton backend applies to your device, since that path was added on February 7, 2026 and is the part most likely to have changed.

## FAQ

### What are the requirements for running WTConv?

The stated requirements are Python 3.12, timm 1.0.7 and PyWavelets 1.6.0. PyWavelets performs the wavelet decomposition inside the layer, and the pinned timm version matters because the WTConvNeXt models are registered with timm's model registry.

### How do I use WTConv2d in my own CNN?

Import the class from the wtconv package and instantiate it in place of a depthwise convolution. The documented example is WTConv2d(32, 32, kernel_size=5, wt_levels=3), where wt_levels sets how many levels of wavelet decomposition the layer performs.

### Which ImageNet-1k accuracy do the released WTConvNeXt models reach?

At 224x224 resolution, WTConvNeXt-T is listed at 82.5 top-1 accuracy with 30M parameters and 4.5G FLOPs, WTConvNeXt-S at 83.6 with 54M parameters and 8.8G FLOPs, and WTConvNeXt-B at 84.1 with 93M parameters and 15.5G FLOPs. Checkpoints for each size are linked from the results table.

## Sources

- [BGU-CS-VIL/WTConv on GitHub](https://github.com/BGU-CS-VIL/WTConv)
- [Issues](https://github.com/BGU-CS-VIL/WTConv/issues)
- [License: MIT](https://github.com/BGU-CS-VIL/WTConv/blob/main/LICENSE)
- [README](https://github.com/BGU-CS-VIL/WTConv/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/bgu-cs-vil-wtconv