Table of Contents

Class DeformableConvolutionalLayer<T>

Namespace
AiDotNet.NeuralNetworks.Layers
Assembly
AiDotNet.dll

Deformable Convolutional Layer that learns spatial sampling offsets.

public class DeformableConvolutionalLayer<T> : LayerBase<T>, ILayer<T>, IJitCompilable<T>, IDiagnosticsProvider, IWeightLoadable<T>, IDisposable, IChainableComputationGraph<T>

Type Parameters

T

The numeric type used for calculations.

Inheritance
DeformableConvolutionalLayer<T>
Implements
Inherited Members

Remarks

Deformable convolution augments standard convolution with learnable 2D offsets for each sampling location. This allows the convolution to adapt its receptive field to the geometric structure of the input, making it particularly effective for video alignment.

For Beginners: Regular convolutions look at fixed grid positions around each pixel. Deformable convolutions can look at shifted positions learned from the data itself.

This is useful for:

  1. Aligning features between video frames (different objects may have moved differently)
  2. Handling geometric transformations (rotation, scale, perspective)
  3. Object detection with varying shapes and poses

Reference: Dai et al., "Deformable Convolutional Networks", ICCV 2017. https://arxiv.org/abs/1703.06211

Constructors

DeformableConvolutionalLayer(int, int, int, int, int, int, int, int, int, bool, IEngine?)

Creates a new Deformable Convolutional Layer.

public DeformableConvolutionalLayer(int inputHeight, int inputWidth, int inputChannels, int outputChannels, int kernelSize = 3, int stride = 1, int padding = 1, int groups = 1, int deformGroups = 1, bool useModulation = true, IEngine? engine = null)

Parameters

inputHeight int

Height of input feature map.

inputWidth int

Width of input feature map.

inputChannels int

Number of input channels.

outputChannels int

Number of output channels.

kernelSize int

Size of the convolution kernel (default: 3).

stride int

Convolution stride (default: 1).

padding int

Padding size (default: 1).

groups int

Number of convolution groups. Currently only groups=1 is supported (default: 1).

deformGroups int

Number of deformable groups (default: 1).

useModulation bool

Whether to use modulation mask (DCNv2, default: true).

engine IEngine

Optional computation engine (CPU or GPU). If null, uses default CPU engine.

Exceptions

NotSupportedException

Thrown when groups is not 1 (grouped deformable convolution is not yet supported).

Properties

SupportsJitCompilation

Gets whether this layer supports JIT compilation.

public override bool SupportsJitCompilation { get; }

Property Value

bool

True if the layer can be JIT compiled, false otherwise.

Remarks

This property indicates whether the layer has implemented ExportComputationGraph() and can benefit from JIT compilation. All layers MUST implement this property.

For Beginners: JIT compilation can make inference 5-10x faster by converting the layer's operations into optimized native code.

Layers should return false if they:

  • Have not yet implemented a working ExportComputationGraph()
  • Use dynamic operations that change based on input data
  • Are too simple to benefit from JIT compilation

When false, the layer will use the standard Forward() method instead.

SupportsTraining

Gets a value indicating whether this layer supports training.

public override bool SupportsTraining { get; }

Property Value

bool

true if the layer has trainable parameters and supports backpropagation; otherwise, false.

Remarks

This property indicates whether the layer can be trained through backpropagation. Layers with trainable parameters such as weights and biases typically return true, while layers that only perform fixed transformations (like pooling or activation layers) typically return false.

For Beginners: This property tells you if the layer can learn from data.

A value of true means:

  • The layer has parameters that can be adjusted during training
  • It will improve its performance as it sees more data
  • It participates in the learning process

A value of false means:

  • The layer doesn't have any adjustable parameters
  • It performs the same operation regardless of training
  • It doesn't need to learn (but may still be useful)

Methods

Backward(Tensor<T>)

Performs the backward pass of the layer.

public override Tensor<T> Backward(Tensor<T> gradOutput)

Parameters

gradOutput Tensor<T>

Returns

Tensor<T>

The gradient of the loss with respect to the layer's input.

Remarks

This abstract method must be implemented by derived classes to define the backward pass of the layer. The backward pass propagates error gradients from the output of the layer back to its input, and calculates gradients for any trainable parameters.

For Beginners: This method is used during training to calculate how the layer's input should change to reduce errors.

During the backward pass:

  1. The layer receives information about how its output contributed to errors
  2. It calculates how its parameters should change to reduce errors
  3. It calculates how its input should change, which will be used by earlier layers

This is the core of how neural networks learn from their mistakes during training.

BackwardGpu(IGpuTensor<T>)

GPU-resident backward pass for deformable convolution. Computes gradients for input, weights, bias, offset weights/bias, and mask weights/bias.

public override IGpuTensor<T> BackwardGpu(IGpuTensor<T> outputGradient)

Parameters

outputGradient IGpuTensor<T>

Gradient from the next layer [batch, outChannels, outHeight, outWidth].

Returns

IGpuTensor<T>

Gradient for the input tensor.

BuildComputationGraph(ComputationNode<T>, string)

Builds the computation graph for this layer using the provided input node.

public ComputationNode<T> BuildComputationGraph(ComputationNode<T> inputNode, string namePrefix)

Parameters

inputNode ComputationNode<T>

The input computation node from the parent layer.

namePrefix string

Prefix for naming internal nodes (for debugging/visualization).

Returns

ComputationNode<T>

The output computation node representing this layer's computation.

Remarks

Unlike ILayer<T>.ExportComputationGraph, this method does NOT create a new input variable. Instead, it uses the provided inputNode as its input, allowing the parent layer to chain multiple sub-layers together in a single computation graph.

The namePrefix parameter should be used to prefix all internal node names to avoid naming conflicts when multiple instances of the same layer type are used.

ExportComputationGraph(List<ComputationNode<T>>)

Exports the layer's computation graph for JIT compilation.

public override ComputationNode<T> ExportComputationGraph(List<ComputationNode<T>> inputNodes)

Parameters

inputNodes List<ComputationNode<T>>

List to populate with input computation nodes.

Returns

ComputationNode<T>

The output computation node representing the layer's operation.

Remarks

This method constructs a computation graph representation of the layer's forward pass that can be JIT compiled for faster inference. All layers MUST implement this method to support JIT compilation.

For Beginners: JIT (Just-In-Time) compilation converts the layer's operations into optimized native code for 5-10x faster inference.

To support JIT compilation, a layer must:

  1. Implement this method to export its computation graph
  2. Set SupportsJitCompilation to true
  3. Use ComputationNode and TensorOperations to build the graph

All layers are required to implement this method, even if they set SupportsJitCompilation = false.

Forward(Tensor<T>)

Performs the forward pass of the layer.

public override Tensor<T> Forward(Tensor<T> input)

Parameters

input Tensor<T>

The input tensor to process.

Returns

Tensor<T>

The output tensor after processing.

Remarks

This abstract method must be implemented by derived classes to define the forward pass of the layer. The forward pass transforms the input tensor according to the layer's operation and activation function.

For Beginners: This method processes your data through the layer.

The forward pass:

  • Takes input data from the previous layer or the network input
  • Applies the layer's specific transformation (like convolution or matrix multiplication)
  • Applies any activation function
  • Passes the result to the next layer

This is where the actual data processing happens during both training and prediction.

ForwardGpu(params IGpuTensor<T>[])

Performs the forward pass using GPU-resident tensors, keeping all data on GPU.

public override IGpuTensor<T> ForwardGpu(params IGpuTensor<T>[] inputs)

Parameters

inputs IGpuTensor<T>[]

GPU-resident input tensor [batch, inChannels, inHeight, inWidth] in NCHW format.

Returns

IGpuTensor<T>

GPU-resident output tensor [batch, outChannels, outHeight, outWidth] in NCHW format.

Remarks

For Beginners: This is the GPU-optimized version of the Forward method. The main convolution operation stays on GPU, though offset and mask prediction requires a brief CPU round-trip due to the current DeformableConv2D GPU implementation.

GetInputShape()

Gets the input shape for this layer.

public override int[] GetInputShape()

Returns

int[]

The input shape as an array of integers.

Remarks

This method returns the input shape of the layer. If the layer has multiple input shapes, it returns the first one.

For Beginners: This method tells you what shape of data the layer expects.

The input shape:

  • Shows the dimensions of data this layer processes
  • Is needed to connect this layer with previous layers
  • Helps verify the network structure is correct

For layers with multiple inputs, this returns just the first input shape.

GetOutputShape()

Gets the output shape for this layer.

public int[] GetOutputShape()

Returns

int[]

GetParameterGradients()

Gets the gradients of all trainable parameters in this layer.

public override Vector<T> GetParameterGradients()

Returns

Vector<T>

A vector containing the gradients of all trainable parameters.

Remarks

This method returns the gradients of all trainable parameters in the layer. If the gradients haven't been calculated yet, it initializes a new vector of the appropriate size.

For Beginners: This method provides the current adjustment values for all parameters.

The parameter gradients:

  • Show how each parameter should be adjusted during training
  • Are calculated during the backward pass
  • Guide the optimization process

These gradients are usually passed to an optimizer like SGD or Adam, which uses them to update the parameters in a way that reduces errors.

GetParameters()

Gets all trainable parameters of the layer as a single vector.

public override Vector<T> GetParameters()

Returns

Vector<T>

A vector containing all trainable parameters.

Remarks

This abstract method must be implemented by derived classes to provide access to all trainable parameters of the layer as a single vector. This is useful for optimization algorithms that operate on all parameters at once, or for saving and loading model weights.

For Beginners: This method collects all the learnable values from the layer.

The parameters:

  • Are the numbers that the neural network learns during training
  • Include weights, biases, and other learnable values
  • Are combined into a single long list (vector)

This is useful for:

  • Saving the model to disk
  • Loading parameters from a previously trained model
  • Advanced optimization techniques that need access to all parameters

ResetState()

Resets the internal state of the layer.

public override void ResetState()

Remarks

This abstract method must be implemented by derived classes to reset any internal state the layer maintains between forward and backward passes. This is useful when starting to process a new sequence or when implementing stateful recurrent networks.

For Beginners: This method clears the layer's memory to start fresh.

When resetting the state:

  • Cached inputs and outputs are cleared
  • Any temporary calculations are discarded
  • The layer is ready to process new data without being influenced by previous data

This is important for:

  • Processing a new, unrelated sequence
  • Preventing information from one sequence affecting another
  • Starting a new training episode

SetParameters(Vector<T>)

Sets the trainable parameters of the layer.

public override void SetParameters(Vector<T> parameters)

Parameters

parameters Vector<T>

A vector containing all parameters to set.

Remarks

This method sets all the trainable parameters of the layer from a single vector of parameters. The parameters vector must have the correct length to match the total number of parameters in the layer. By default, it simply assigns the parameters vector to the Parameters field, but derived classes may override this to handle the parameters differently.

For Beginners: This method updates all the learnable values in the layer.

When setting parameters:

  • The input must be a vector with the correct length
  • The layer parses this vector to set all its internal parameters
  • Throws an error if the input doesn't match the expected number of parameters

This is useful for:

  • Loading a previously saved model
  • Transferring parameters from another model
  • Setting specific parameter values for testing

Exceptions

ArgumentException

Thrown when the parameters vector has incorrect length.

UpdateParameters(T)

Updates the parameters of the layer using the calculated gradients.

public override void UpdateParameters(T learningRate)

Parameters

learningRate T

The learning rate to use for the parameter updates.

Remarks

This abstract method must be implemented by derived classes to define how the layer's parameters are updated during training. The learning rate controls the size of the parameter updates.

For Beginners: This method updates the layer's internal values during training.

When updating parameters:

  • The weights, biases, or other parameters are adjusted to reduce prediction errors
  • The learning rate controls how big each update step is
  • Smaller learning rates mean slower but more stable learning
  • Larger learning rates mean faster but potentially unstable learning

This is how the layer "learns" from data over time, gradually improving its ability to extract useful patterns from inputs.

UpdateParametersGpu(IGpuOptimizerConfig)

GPU-resident parameter update with polymorphic optimizer support. Updates all weight tensors directly on GPU using the specified optimizer configuration.

public override void UpdateParametersGpu(IGpuOptimizerConfig config)

Parameters

config IGpuOptimizerConfig

GPU optimizer configuration specifying the optimizer type and hyperparameters.

Edit this page