torch.nn.CircularPad3d
class CircularPad3d extends Modulenew CircularPad3d(padding: Padding3D)
- readonly
padding([number, number, number, number, number, number])
3D circular padding: pads volumes with wraparound in all dimensions.
Treats 3D data as periodic in all spatial dimensions: edges wrap around to opposite sides. Creates seamless wraparound without reflection or repetition. Essential for:
- 3D periodic data (volumetric textures, wave simulations)
- FFT-based 3D processing (expects periodic extension in all axes)
- Volumetric data with natural cyclic symmetry
- Medical imaging with toroidal topology
- Avoiding boundary effects in 3D Fourier transforms
Circular padding wraps in all three dimensions: front↔back, left↔right, top↔bottom. For volume [..., d, h, w] with padding, depth wraps front-to-back, height wraps top-to-bottom, width wraps left-to-right. Produces seamless boundaries perfect for periodic domains.
When to use CircularPad3d:
- Volumetric periodic patterns (crystal lattices, textures, simulations)
- 3D FFT preprocessing (assumes periodic extension in all dimensions)
- Volumetric data with toroidal/periodic topology
- Avoiding boundary artifacts in 3D convolutions on periodic data
- Fluid dynamics simulations with periodic boundary conditions
- Materials science (periodic unit cells)
Trade-offs:
- vs ZeroPad3d: Circular wraps seamlessly; zero simpler but causes boundary artifacts
- vs ReflectionPad3d: Circular periodic; reflection symmetric but different continuity
- vs ReplicationPad3d: Circular wraps; replication repeats edges
- Computation: Same as other padding modes
- Gradient: Backprop includes wraparound effects at all boundaries
- Use case: Only for genuinely periodic/cyclic 3D data
Circular mechanics: For volume with shape [D, H, W] and padding=(p_left, p_right, p_top, p_bottom, p_front, p_back):
- Depth axis: front boundary wraps to back, back boundary wraps to front
- Height axis: top boundary wraps to bottom, bottom boundary wraps to top
- Width axis: left boundary wraps to right, right boundary wraps to left
- All padding extracted cyclically from opposite side of volume
- True 3D periodic: Wraps in all three spatial dimensions simultaneously
- FFT-compatible: Perfect for 3D Fourier transforms of periodic data
- Toroidal topology: Implements toroidal (donut-shaped) boundary conditions
- Smooth continuity: Left connects to right, top to bottom, front to back
- Gradient wraps: Backprop includes wraparound effects at all six boundaries
- Symmetric boundaries: Opposite edges connect smoothly for all three dimensions
- Only for periodic data: Don't use unless data is genuinely periodic in all dimensions
- Assumes continuity: Expects volume naturally continues from back to front and top to bottom
- No edge repetition: Unlike ReplicationPad3d, circular doesn't repeat edge values
Examples
// 3D volumetric wraparound padding
const pad = new torch.nn.CircularPad3d(1);
const volume = torch.randn([8, 1, 32, 32, 32]); // Batch of volumes
const padded = pad.forward(volume); // [8, 1, 34, 34, 34] with wraparound// Asymmetric padding on different dimensions
const pad = new torch.nn.CircularPad3d([1, 1, 2, 2, 3, 3]);
const vol = torch.randn([1, 16, 64, 64, 64]);
const padded = pad.forward(vol);
// Padded shape: [1, 16, 64+3+3, 64+2+2, 64+1+1] = [1, 16, 70, 68, 66]
// Front/back wrapped by 3 slices, top/bottom by 2 rows, left/right by 1 column// 3D FFT preprocessing with periodic boundary conditions
const pad = new torch.nn.CircularPad3d(2);
const waves = torch.randn([1, 1, 128, 128, 128]); // Wave field
const padded = pad.forward(waves); // Add periodic boundaries for FFT
// FFT expects periodic extension - circular padding provides it perfectly// Crystallographic structure with periodic unit cells
const pad = new torch.nn.CircularPad3d(3);
const crystal = torch.randn([1, 8, 50, 50, 50]); // Atomic coordinates
const periodic_crystal = pad.forward(crystal);
// Padding creates periodic continuation of unit cell