Skip to content
Tutorials Center
My learning

Topics

Lesson 33 of 40 ยท Neural Networks with Flax

Convolutional Networks in Flax

Build a CNN with Flax: nn.Conv, NHWC layout, pooling, flattening, parameter shapes, and how lax.conv works underneath, with a runnable NumPy convolution you can inspect.

Images have structure that a plain dense layer ignores: nearby pixels are related, and a pattern (an edge, a corner) means the same thing wherever it appears. A convolution slides a small learned filter across the image, reusing the same few weights at every position. This gives far fewer parameters than a dense layer and builds in translation equivariance.

Flax provides nn.Conv, which wraps JAX's lax.conv_general_dilated. The important things to learn are the data layout, the shape arithmetic, and how to put convolutions, pooling and a classifier head together.

Flax and JAX do not run in the live editors on this site, so the Flax code below is read-only. The runnable blocks implement a convolution in NumPy so you can verify the shape rules and see what a filter computes; their output comes from NumPy.

NHWC layout

JAX and Flax use channels-last layout by default: an image batch has shape (batch, height, width, channels), called NHWC. A convolution kernel has shape (kernel_h, kernel_w, in_channels, out_channels). If you come from PyTorch (channels-first, NCHW), remember to transpose.

Python
import jax, jax.numpy as jnp
import flax.linen as nn

class SmallCNN(nn.Module):
    num_classes: int = 10

    @nn.compact
    def __call__(self, x):                       # x: (N, 28, 28, 1)
        x = nn.Conv(features=16, kernel_size=(3, 3))(x)       # -> (N, 28, 28, 16)
        x = nn.relu(x)
        x = nn.avg_pool(x, window_shape=(2, 2), strides=(2, 2))  # -> (N, 14, 14, 16)
        x = nn.Conv(features=32, kernel_size=(3, 3))(x)       # -> (N, 14, 14, 32)
        x = nn.relu(x)
        x = nn.avg_pool(x, window_shape=(2, 2), strides=(2, 2))  # -> (N, 7, 7, 32)
        x = x.reshape((x.shape[0], -1))                        # -> (N, 1568)
        x = nn.Dense(64)(x)
        x = nn.relu(x)
        return nn.Dense(self.num_classes)(x)

model = SmallCNN()
params = model.init(jax.random.key(0), jnp.ones((1, 28, 28, 1)))["params"]
print(jax.tree_util.tree_map(jnp.shape, params))

The printed tree would show kernels such as (3, 3, 1, 16) for the first conv and (3, 3, 16, 32) for the second, each with a bias vector. Notice that the first dense layer receives 7 * 7 * 32 = 1568 inputs: you must know the flattened size only when you write the model by hand; Flax infers it from the example input at init.

Shape arithmetic

For one spatial dimension with input size n, kernel size k, stride s and padding p (on each side), the output size is floor((n + 2p - k) / s) + 1. Flax's padding argument is usually a string:

  • "SAME" pads so that the output size is ceil(n / s). With stride 1, output equals input size.
  • "VALID" uses no padding, so the output shrinks to n - k + 1 (stride 1).

nn.Conv defaults to "SAME". The block below implements VALID and SAME convolution and lets you check the formula.

Python Convolution and output shapes (NumPy)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

The edge filter produces zero over flat regions and a strong response exactly at the step, which is what early convolutional layers learn on their own.

Counting parameters

A convolution with kernel (kh, kw), C_in input and C_out output channels has kh * kw * C_in * C_out + C_out parameters, regardless of image size. A dense layer connecting a 28 x 28 image to 16 outputs would need 784 * 16 weights for one dense step; a 3 x 3 convolution with 16 filters on one channel needs only 3 * 3 * 1 * 16 + 16 = 160.

Python Parameter counts: convolution versus dense

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Most parameters sit in the dense head, not in the convolutions. That is why many modern designs replace flattening with global average pooling (average over height and width, then one dense layer).

Pooling, strides and downsampling

nn.avg_pool and nn.max_pool shrink the spatial size by summarizing windows. An alternative is a convolution with strides=(2, 2), which learns its own downsampling. Both are common.

Training notes

  • Batch norm and dropout in a CNN follow the rules from the previous lesson: pass a train flag, thread batch_stats.
  • Normalize inputs. Scale pixels to [0, 1] or standardize them. Raw 0-255 values make training unstable.
  • Keep batch shapes fixed under jit, as shown in the training loop lesson.
  • Use vmap only when you write single-image code. nn.Conv already handles a batch dimension; adding vmap is usually unnecessary (see vmap basics).
  • Data augmentation (random flips and crops) needs fresh keys per example; split keys as in random sampling patterns.

What lax does underneath

nn.Conv calls jax.lax.conv_general_dilated(lhs, rhs, window_strides, padding, dimension_numbers=...). You can call it yourself when you need unusual layouts, dilation (atrous convolution) or transposed convolutions. Read more about low-level primitives in lax operations.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What input layout does Flax use for images by default?

    Flax uses channels-last NHWC; kernels are (kh, kw, in_channels, out_channels).
  2. 2. A 6x6 input, 3x3 kernel, stride 1, padding VALID gives what output size?

    VALID output is n - k + 1 = 6 - 3 + 1 = 4 in each spatial dimension.
  3. 3. How many parameters does a 3x3 convolution from 16 to 32 channels have (with bias)?

    3 * 3 * 16 * 32 + 32 = 4,640, independent of image size.
  4. 4. Why is the first Dense layer after flattening often the largest in a small CNN?

    Flattened size grows with spatial dimensions and channels, so a dense layer there has many weights.

Summary

  • Flax images are NHWC; kernels are (kh, kw, in, out).
  • SAME keeps size at stride 1; VALID shrinks by k - 1; strides divide the size.
  • Convolutions share weights across positions, so parameter counts do not depend on image size.
  • Pooling or strided convolutions downsample; global average pooling shrinks the dense head.
  • Normalize inputs, keep batch shapes fixed, and handle dropout and BatchNorm with the train flag.

Next: Saving and Loading Models, Schedules and Gradient Clipping