Asymmetric padding should be handled via calculate_padding_2

Error message

Asymmetric padding should be handled via calculate_padding_2d_pairs()

What it means

PaddingConfig2d::calculate_padding_2d only supports symmetric padding. When the computed top/bottom (or left/right) paddings differ, it panics and directs you to calculate_padding_2d_pairs, which returns all four sides. This happens because 'Same' padding with an even kernel size cannot be split evenly across both sides of an axis.

Source

Thrown at crates/burn-nn/src/padding.rs:98

            }
            Self::Explicit(top, left, bottom, right) => ((*top, *bottom), (*left, *right)),
        }
    }

    /// Calculate symmetric padding for 2D operations.
    /// Returns padding values [height, width] (same for both sides).
    /// Panics if asymmetric padding is detected.
    pub(crate) fn calculate_padding_2d(
        &self,
        height: usize,
        width: usize,
        kernel_size: &[usize; 2],
        stride: &[usize; 2],
    ) -> [usize; 2] {
        let ((top, bottom), (left, right)) =
            self.calculate_padding_2d_pairs(height, width, kernel_size, stride);
        if top != bottom || left != right {
            panic!("Asymmetric padding should be handled via calculate_padding_2d_pairs()")
        }
        [top, left]
    }
}

/// Padding configuration for 3D operators.
#[derive(Config, Debug, PartialEq)]
pub enum PaddingConfig3d {
    /// Dynamically calculates padding to preserve input dimensions in output.
    Same,
    /// No padding applied.
    Valid,
    /// Applies explicit symmetric padding values.
    /// Format: (depth, height, width) — same padding on both sides of each dimension.
    Explicit(usize, usize, usize),
}

impl PaddingConfig3d {

View on GitHub (pinned to d16f7ba2ed)

Solutions

Use calculate_padding_2d_pairs to get the full [top, bottom, left, right] padding and pass it to the asymmetric-padding kernel API.
Switch to an odd kernel size (e.g. 3) so Same padding stays symmetric.
Use PaddingConfig2d::Valid and handle padding yourself.

Example fix

// before
let [pad_h, pad_w] = PaddingConfig2d::Same.calculate_padding_2d(h, w, &[2, 2], &[1, 1]); // panics
// after
let ((top, bottom), (left, right)) = PaddingConfig2d::Same
    .calculate_padding_2d_pairs(h, w, &[2, 2], &[1, 1]);

Defensive patterns

Strategy: validation

Validate before calling

fn symmetric_same_padding_ok(kernel_size: [usize; 2]) -> bool {
    kernel_size.iter().all(|k| k % 2 == 1) // odd kernels keep 'Same' padding symmetric
}

Try / catch

// burn panics instead of returning Result; guard before constructing the config
if !symmetric_same_padding_ok(kernel_size) {
    let ((t, b), (l, r)) = PaddingConfig2d::Same.calculate_padding_2d_pairs(h, w, &kernel_size, &stride);
    // use (t, b, l, r) with an asymmetric-padding API
} else {
    let [ph, pw] = PaddingConfig2d::Same.calculate_padding_2d(h, w, &kernel_size, &stride);
}

Prevention

Prefer odd kernel sizes (1, 3, 5) whenever PaddingConfig2d::Same is used.
Call calculate_padding_2d_pairs by default and ignore symmetry when you can consume 4-side padding.
When porting PyTorch configs, check every conv/pool kernel for even sizes before enabling Same padding.

When it happens

Trigger: Calling PaddingConfig2d::Same.calculate_padding_2d(height, width, kernel_size, stride) where kernel_size[0] or kernel_size[1] is even (e.g. [2, 2]), making calculate_same_padding return unequal pairs.

Common situations: Configuring a conv/pool layer with an even kernel size and Same padding; porting a PyTorch model that used even kernels; writing tests (like test_padding_config_2d_calculate_symmetric_asymmetric_panics) that exercise the panic path.

Related errors

AI-assisted analysis of tracel-ai/burn@d16f7ba2ed (2026-09-05). Data as JSON: /api/errors/a613ff0f910d5ac7. Report an issue: GitHub.