giagrad.nn.Conv2D#

class giagrad.nn.Conv2D(*args, **kwargs)[source]#

2D convolution layer.

Adapted from PyTorch Conv2d. Note that this implementation matches PyTorch LazyConv2d, so in_channels is inferred at runtime.

In the simplest case, the output value of the layer with input size \((N, C_{\text{in}}, H, W)\) and output \((N, C_{\text{out}}, H_{\text{out}}, W_{\text{out}})\) can be precisely described as:

\[\text{out}(N_i, C_{\text{out}_j}) = \text{bias}(C_{\text{out}_j}) + \sum_{k = 0}^{C_{\text{in}} - 1} \text{weight}(C_{\text{out}_j}, k) \star \text{input}(N_i, k)\]

where \(\star\) is the valid 2D cross-correlation operator, \(N\) is a batch size, \(C\) denotes a number of channels, \(H\) is a height of input planes in pixels, and \(W\) is width in pixels.

  • stride

    Controls the stride for the cross-correlation, a single number or a one-element tuple.

  • padding

    Controls the amount of padding applied to the input. It can be either a string {‘same’}, a tuple of ints or tuples of two ints (at the same time) giving the amount of implicit padding applied on both sides. Internally calls giagrad.Tensor.pad().

  • dilation

    Controls the spacing between the kernel points; also known as the à trous algorithm. It is harder to describe, but this link has a nice visualization of what dilation does.

  • groups

    Controls the connections between inputs and outputs. in_channels and out_channels must both be divisible by groups. For example,

    • At groups = 1

      all inputs are convolved to all outputs.

    • At groups = 2

      the operation becomes equivalent to having two conv layers side by side, each seeing half the input channels and producing half the output channels, and both subsequently concatenated.

    • At groups = in_channels

      each input channel is convolved with its own set of filters (of size \(\frac{\text{out_channels}}{\text{in_channels}}\)).

See Animated AI for an outstanding explanation.

Note

When groups == in_channels and out_channels == K * in_channels, where K is a positive integer, this operation is also known as a “depthwise convolution”.

In other words, for an input of size \((N, C_{in}, L_{in})\), a depthwise convolution with a depthwise multiplier K can be performed with the arguments \((C_\text{in}=C_\text{in}, C_\text{out}=C_\text{in} \times \text{K}, ..., \text{groups}=C_\text{in})\). See Animated AI.

Note

padding='valid' is the same as padding=0, which is the default value. However padding='same' pads the input so the output has the shape as the input. However, in some cases padding before and after may vary, mainly due tue assymetrical kernel sizes. For example, the formula to compute padding for a given dimension \(X_{in}\):

\[\begin{split}\begin{align*} padding &= \frac{ (X_{in}-1) \times \text{stride} - X_{in} + K_{X_{in}} + (K_{X_{in}}-1)*(\text{dilation}-1) }{2} \\ pad_{before} &= \lceil padding \rceil \\ pad_{after} &= \lfloor padding \rfloor \\ \end{align*}\end{split}\]
Parameters:

  • out_channels (int) – Number of channels produced by the convolution.

  • kernel_size (int or Tuple[int, int]) – Size of the convolving kernel.

  • stride (int or Tuple[int, int], default: 1) – Stride of the convolution.

  • dilation (int or Tuple[int, int], default: 1) – Spacing between kernel elements.

  • padding (int, tuple or str, default: 0) – Padding added to both sides of the input. See giagrad.Tensor.pad().

  • padding_mode (str, default: 'constant') – Padding mode defined by numpy.pad.

  • groups (int, default: 1) – Number of blocked connections from input channels to output channels.

  • bias (bool, default: True) – If True, adds a learnable bias to the output.

  • **padding_kwargs – Optional arguments passed to numpy.pad.

Shape:

  • Input (\(N, C_{in}, H_{in}, W_{in})\) or \((C_{in}, H_{in}, W_{in}\))

  • Output (\(N, C_{out}, H_{out}, W_{out})\) or \((C_{out}, H_{out}, W_{out}\)) –

    \[H_{out} = \left\lfloor\frac{H_{in} + 2 \times \text{padding}[0] - \text{dilation}[0] \times (\text{kernel_size}[0] - 1) - 1}{\text{stride}[0]} + 1\right\rfloor\]
    \[W_{out} = \left\lfloor\frac{W_{in} + 2 \times \text{padding}[1] - \text{dilation}[1] \times (\text{kernel_size}[1] - 1) - 1}{\text{stride}[1]} + 1\right\rfloor\]
Variables:

  • w (Tensor) – The learnable weights of the module of shape \((\text{out_channels}, \frac{\text{in_channels}}{\text{groups}},\) \(\text{kernel_size[0]}, \text{kernel_size[1]})\). The values of these weights are sampled from \(\mathcal{U}(-\sqrt{k}, \sqrt{k})\) where \(k = \frac{groups}{C_\text{in} * \prod_{i=0}^{1}\text{kernel_size}[i]}\)

  • b (Tensor) – The learnable bias of the module of shape (out_channels). If bias is True, then the values of these weights are sampled from \(\mathcal{U}(-\sqrt{k}, \sqrt{k})\) where \(k = \frac{groups}{C_\text{in} * \prod_{i=0}^{1}\text{kernel_size}[i]}\)

Examples

>>> # With square kernels and equal stride
>>> m = nn.Conv2D(33, 3, stride=2)
>>> # non-square kernels and unequal stride and with padding
>>> m = nn.Conv2D(33, (3, 5), stride=(2, 1), padding=(4, 2))
>>> # non-square kernels and unequal stride and with padding and dilation
>>> m = nn.Conv2D(33, (3, 5), stride=(2, 1), padding=(4, 2), dilation=(3, 1))
>>> input = Tensor.empty(20, 16, 50, 100).uniform()
>>> output = m(input)