utils.conv_layer

utils.conv_layer#

Convolutional building blocks used across BRIDGE and related models.

This module provides lightweight wrappers around common 1D/2D convolution patterns and a KAN-based 1D convolution layer used in BRIDGE experiments:

  • Conv2d: nn.Conv2d + optional BatchNorm2d + optional ReLU + dropout.

  • Conv1d: nn.Conv1d + optional BatchNorm1d + optional ReLU + dropout.

  • SimpleConvKAN_1layer: a 1D convolution block built on FastKANConv1DLayer from torch_conv_kan with optional BatchNorm1d.

These wrappers standardize padding, normalization, and regularization so the rest of the project can define architectures concisely and consistently.

Who this is for#

  • Users who are implementing or modifying BRIDGE/sequence CNN architectures and want convenient, repeatable conv blocks.

  • Researchers comparing standard convolutions with KAN-parameterized convolutions.

This module is not a training script. It assumes the caller will construct the full model, handle device placement, and supply properly-shaped tensors.

Dependencies#

  • torch, torch.nn, torch.nn.functional

  • torch_conv_kan.kan_convs.FastKANConv1DLayer (required only for SimpleConvKAN_1layer)

Core conventions#

Tensor layouts

  • 1D conv inputs: (N, C_in, L)

  • 2D conv inputs: (N, C_in, H, W)

“Same” padding behavior

  • Conv2d: if same_padding=True, uses padding_h = floor((kH-1)/2), padding_w = floor((kW-1)/2).

  • Conv1d: if same_padding=True, uses padding = floor((k-1)/2).

This approximates “same” output size when stride=1 and kernel sizes are odd. Even kernel sizes can lead to off-by-one behavior.

Dropout behavior (important)#

  • Conv1d and Conv2d apply F.dropout(x, p=0.3, training=self.training) unconditionally in forward. Dropout is active only in training mode.

  • SimpleConvKAN_1layer does not apply F.dropout in forward; instead it passes dropout=... into FastKANConv1DLayer (dropout is handled inside that layer).

If you combine these blocks, be mindful of the total regularization strength.

How to use#

Basic examples:

import torch
from conv_layer import Conv1d, Conv2d, SimpleConvKAN_1layer

# 1D example
x1 = torch.randn(8, 64, 101)          # (N, C_in, L)
conv1 = Conv1d(64, 128, kernel_size=(3,), same_padding=True)
y1 = conv1(x1)                        # (8, 128, L_out)

# 2D example
x2 = torch.randn(8, 16, 32, 32)       # (N, C_in, H, W)
conv2 = Conv2d(16, 32, kernel_size=(3, 3), same_padding=True)
y2 = conv2(x2)                        # (8, 32, H_out, W_out)

# KAN-based 1D conv example
kan = SimpleConvKAN_1layer(64, 64, kernel_size=3, grid_size=8, dropout=0.3)
yk = kan(x1)                          # (8, 64, L_out)

Notes and caveats#

  • Shape preservation with same_padding is guaranteed only for odd kernels and stride=1.

  • SimpleConvKAN_1layer requires torch_conv_kan; if unavailable, importing this module will fail. If you need graceful degradation, consider importing FastKANConv1DLayer inside the class or behind a try/except.

  • Conv1d / Conv2d apply dropout with fixed p=0.3. If you need configurable dropout, you can add a dropout argument and store it as self.dropout_p.

Classes

Conv1d(*args, **kwargs)

A lightweight Conv1D block: Conv1d -> (optional) BatchNorm1d -> (optional) ReLU -> Dropout.

Conv2d(*args, **kwargs)

A lightweight Conv2D block: Conv2d -> (optional) BatchNorm2d -> (optional) ReLU -> Dropout.

SimpleConvKAN_1layer(input_channels, ...[, ...])

A single-layer 1D convolutional block using a KAN-based convolution operator.
class utils.conv_layer.Conv2d(*args: Any, **kwargs: Any)[source]#

Bases: Module

A lightweight Conv2D block: Conv2d -> (optional) BatchNorm2d -> (optional) ReLU -> Dropout.

This module is a convenience wrapper frequently used in CNN backbones. It supports “same” padding (for odd kernel sizes) by choosing padding = floor((k-1)/2) along both spatial dimensions.

Parameters:

  • in_channels (int) – Number of input channels (C_in).

  • out_channels (int) – Number of output channels (C_out).

  • kernel_size (tuple[int, int]) – Kernel size (kH, kW). If same_padding=True, typical usage is odd kernels like (3, 3), (5, 5) to preserve spatial size under stride=1.

  • stride (int or tuple[int, int], optional) – Convolution stride. Default is 1.

  • if_bias (bool, optional) – Whether to include bias in the Conv2d layer. Default False. NOTE: If BatchNorm is enabled (bn=True), bias is often unnecessary.

  • relu (bool, optional) – If True, apply ReLU after BN. Default True.

  • same_padding (bool, optional) – If True, apply padding that approximates “same” padding: padding_h = floor((kH-1)/2), padding_w = floor((kW-1)/2). Default True.

  • bn (bool, optional) – If True, apply BatchNorm2d after convolution. Default True.

Inputs:
x (torch.Tensor):

Shape (N, C_in, H, W).

Returns:

torch.Tensor – Shape (N, C_out, H_out, W_out), where spatial sizes depend on stride/padding.

Behavior / Notes:

  • Applies dropout with p=0.3 unconditionally (controlled by model.train()/eval()).

  • If same_padding=True and kernel sizes are even, this padding is not perfectly symmetric “same” behavior; use odd kernels for clean size preservation.

forward(x)[source]#

Forward pass.

Parameters:

x (torch.Tensor) – Input tensor of shape (N, C_in, H, W).

Returns:

torch.Tensor – Output tensor of shape (N, C_out, H_out, W_out).

class utils.conv_layer.Conv1d(*args: Any, **kwargs: Any)[source]#

Bases: Module

A lightweight Conv1D block: Conv1d -> (optional) BatchNorm1d -> (optional) ReLU -> Dropout.

This module is a convenience wrapper for 1D convolutional feature extractors, used for sequence models (e.g., RNA sequences) where the input shape is (N, C_in, L).

Parameters:

  • in_channels (int) – Number of input channels (C_in).

  • out_channels (int) – Number of output channels (C_out).

  • kernel_size (tuple[int] or int) – Kernel size. The code assumes indexable form kernel_size[0], so the most compatible usage is a 1-tuple like (3,) rather than integer 3.

  • stride (tuple[int] or int, optional) – Stride for convolution. Default (1,). PyTorch also accepts int.

  • dilation (tuple[int] or int, optional) – Dilation factor. Default (1,). PyTorch also accepts int.

  • if_bias (bool, optional) – Whether Conv1d has bias. Default False.

  • relu (bool, optional) – If True, apply ReLU after BN. Default True.

  • same_padding (bool, optional) – If True, uses padding = floor((k-1)/2) to approximate “same” padding when stride=1. Default True.

  • bn (bool, optional) – If True, apply BatchNorm1d after convolution. Default True.

Inputs:
x (torch.Tensor):

Shape (N, C_in, L).

Returns:

torch.Tensor – Shape (N, C_out, L_out).

Behavior / Notes:

  • Applies dropout p=0.3 unconditionally (active only when training).

  • For “same” length preservation, prefer odd kernel sizes with stride=1.

  • If you pass kernel_size as int (e.g., 3), kernel_size[0] will error. To keep this wrapper robust, call with (3,) or adapt the implementation.

forward(x)[source]#

Forward pass.

Parameters:

x (torch.Tensor) – Input tensor of shape (N, C_in, L).

Returns:

torch.Tensor – Output tensor of shape (N, C_out, L_out).

class utils.conv_layer.SimpleConvKAN_1layer(input_channels, out_channels, kernel_size=3, groups=1, grid_size=8, same_padding=True, bn=True, dropout=0.3)[source]#

Bases: Module

A single-layer 1D convolutional block using a KAN-based convolution operator.

This wraps FastKANConv1DLayer from torch_conv_kan, optionally followed by BatchNorm1d. It is intended as a drop-in replacement for standard Conv1d blocks when experimenting with Kolmogorov–Arnold Network (KAN) style parameterizations.

Parameters:

  • input_channels (int) – Number of input channels (C_in).

  • out_channels (int) – Number of output channels (C_out).

  • kernel_size (int, optional) – Convolution kernel size. Default 3.

  • groups (int, optional) – Grouped convolution parameter passed to FastKANConv1DLayer. Default 1.

  • grid_size (int, optional) – KAN grid size controlling the resolution/complexity of the KAN function basis (exact meaning depends on torch_conv_kan implementation). Default 8.

  • same_padding (bool, optional) – If True, uses padding = floor((k-1)/2) to preserve length when stride=1 (odd kernels). Default True.

  • bn (bool, optional) – If True, apply BatchNorm1d after the KAN convolution. Default True.

  • dropout (float, optional) – Dropout probability passed into FastKANConv1DLayer (NOT applied via F.dropout here). Default 0.3.

Inputs:
x (torch.Tensor):

Shape (N, C_in, L).

Returns:

torch.Tensor – Shape (N, C_out, L_out).

Behavior / Notes:

  • Dropout is handled inside FastKANConv1DLayer via its dropout argument. The wrapper does not additionally apply F.dropout in forward (commented out).

  • stride and dilation are hard-coded to 1 in this wrapper.

forward(x)[source]#

Forward pass.

Parameters:

x (torch.Tensor) – Input tensor of shape (N, C_in, L).

Returns:

torch.Tensor – Output tensor of shape (N, C_out, L_out).

Contents