Convolution (Deep Java Library 0.5.0 API specification)

java.lang.Object
- ai.djl.nn.AbstractBlock
- - ai.djl.nn.ParameterBlock
  - - ai.djl.nn.convolutional.Convolution

All Implemented Interfaces:

Block

Direct Known Subclasses:

Conv1D, Conv2D, Conv3D
```
public abstract class Convolution
extends ParameterBlock
```
A convolution layer does a dot product calculation on each channel of \(k\)-channel input data by specified number of filters, each containing \(k\) kernels for calculating each channel in the input data and then summed per filter, hence the number of filters denote the number of output channels of a convolution layer. Some modifications may be set on a convolution layer, namely stride which shows the distance between each convolved input data in a channel, and padding which shows the preservation of input size (width and/or height and/or depth) by adding specified padding to the sides of the output. A convolution layer extracts features of input data with different representations where each representation lies per channel in the output, often known as feature map or feature vector.
While convolution process itself has been around for quite some time in mathematics, in 1998 LeCun et al. implemented the very first convolution layers forming a network called LeNet-5 for character recognition task; details of the network's implementation can be find in LeNet-5's paper. When other approaches at that time used handcrafted features with external stage of feature extraction, convolution layer performed feature extraction on its own with no human interference. This marks a new era of machine-extracted features, but it was not until 2012 that the published paper of AlexNet marked the beginning of convolutional neural networks, which by the name itself heavily relies on convolution layer.
Convolution layer is usually used in image-related tasks due to its well-renowned performance as shown by existing works and currently, other non-image-related fields of study are beginning to incorporate convolution layer as an addition or replacement of previous approaches, with one example being time series processing with 1-dimensional convolution layer. Due to the nature of convolution that processes all points in the input data, it is computationally expensive, hence the use of GPU is strongly recommended for faster performance as opposed to using CPU. Note that it is also common to stack convolution layers with different output channels for more representations of the input data.
Current implementations of Convolution are Conv1D with input dimension of LayoutType.WIDTH, Conv2D with input dimension of LayoutType.WIDTH and LayoutType.HEIGHT, and lastly Conv3D with input dimension of LayoutType.WIDTH, LayoutType.HEIGHT, and LayoutType.DEPTH. These implementations share the same core principal as a Convolution layer does, with the difference being the number of input dimension each operates on as denoted by ConvXD for X dimension(s).

Nested Class Summary

Nested Classes
Modifier and Type Class and Description

static class Convolution.ConvolutionBuilder<T extends Convolution.ConvolutionBuilder>
A builder that can build any Convolution block.

Nested Classes
Modifier and Type	Class and Description
`static class`	`Convolution.ConvolutionBuilder<T extends Convolution.ConvolutionBuilder>` A builder that can build any `Convolution` block.

Field Summary

Fields
Modifier and Type	Field and Description
`protected Parameter`	`bias`
`protected Shape`	`dilate`
`protected boolean`	`includeBias`
`protected Shape`	`kernel`
`protected int`	`numFilters`
`protected int`	`numGroups`
`protected Shape`	`pad`
`protected Shape`	`stride`
`protected Parameter`	`weight`

Fields inherited from class ai.djl.nn.AbstractBlock
inputNames, inputShapes

Constructor Summary

Constructors
Constructor and Description

Convolution(Convolution.ConvolutionBuilder<?> builder)
Creates a Convolution object.

Constructors
Constructor and Description
`Convolution(Convolution.ConvolutionBuilder<?> builder)` Creates a `Convolution` object.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`protected void`	`beforeInitialize(Shape[] inputs)` Performs any action necessary before initialization.
`NDList`	`forward(ParameterStore parameterStore, NDList inputs, boolean training, ai.djl.util.PairList<java.lang.String,java.lang.Object> params)` Applies the operating function of the block once.
`java.util.List<Parameter>`	`getDirectParameters()` Returns a list of all the direct parameters of the block.
`protected abstract LayoutType[]`	`getExpectedLayout()` Returns the expected layout of the input.
`Shape[]`	`getOutputShapes(NDManager manager, Shape[] inputs)` Returns the expected output shapes of the block for the specified input shapes.
`Shape`	`getParameterShape(java.lang.String name, Shape[] inputShapes)` Returns the shape of the specified direct parameter of this block given the shapes of the input to the block.
`protected abstract java.lang.String`	`getStringLayout()` Returns the string representing the layout of the input.
`void`	`loadParameters(NDManager manager, java.io.DataInputStream is)` Loads the parameters from the given input stream.
`protected abstract int`	`numDimensions()` Returns the number of dimensions of the input.
`void`	`saveParameters(java.io.DataOutputStream os)` Writes the parameters of the block to the given outputStream.

Methods inherited from class ai.djl.nn.ParameterBlock
getChildren, initialize, toString

Methods inherited from class ai.djl.nn.AbstractBlock
cast, clear, describeInput, getParameters, isInitialized, readInputShapes, saveInputShapes, setInitializer, setInitializer

Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface ai.djl.nn.Block
forward, validateLayout

- Field Detail
  - kernel
```
protected Shape kernel
```
  - stride
```
protected Shape stride
```
  - pad
```
protected Shape pad
```
  - dilate
```
protected Shape dilate
```
  - numFilters
```
protected int numFilters
```
  - numGroups
```
protected int numGroups
```
  - includeBias
```
protected boolean includeBias
```
  - weight
```
protected Parameter weight
```
  - bias
```
protected Parameter bias
```
- Constructor Detail
  - Convolution
```
public Convolution(Convolution.ConvolutionBuilder<?> builder)
```
    Creates a Convolution object.
    
    Parameters:
    
    builder - the Builder that has the necessary configurations
- Method Detail
  - getExpectedLayout
```
protected abstract LayoutType[] getExpectedLayout()
```
    Returns the expected layout of the input.
    
    Returns:
    
    the expected layout of the input
  - getStringLayout
```
protected abstract java.lang.String getStringLayout()
```
    Returns the string representing the layout of the input.
    
    Returns:
    
    the string representing the layout of the input
  - numDimensions
```
protected abstract int numDimensions()
```
    Returns the number of dimensions of the input.
    
    Returns:
    
    the number of dimensions of the input
  - forward
```
public NDList forward(ParameterStore parameterStore,
                      NDList inputs,
                      boolean training,
                      ai.djl.util.PairList<java.lang.String,java.lang.Object> params)
```
    Applies the operating function of the block once. This method should be called only on blocks that are initialized.
    
    Parameters:
    
    parameterStore - the parameter store
    
    inputs - the input NDList
    
    training - true for a training forward pass
    
    params - optional parameters
    
    Returns:
    
    the output of the forward pass
  - beforeInitialize
```
protected void beforeInitialize(Shape[] inputs)
```
    Performs any action necessary before initialization.
    
    Overrides:
    
    beforeInitialize in class AbstractBlock
    
    Parameters:
    
    inputs - the expected shapes of the input
  - getOutputShapes
```
public Shape[] getOutputShapes(NDManager manager,
                               Shape[] inputs)
```
    Returns the expected output shapes of the block for the specified input shapes.
    
    Parameters:
    
    manager - an NDManager
    
    inputs - the shapes of the inputs
    
    Returns:
    
    the expected output shapes of the block
  - getParameterShape
```
public Shape getParameterShape(java.lang.String name,
                               Shape[] inputShapes)
```
    Returns the shape of the specified direct parameter of this block given the shapes of the input to the block.
    
    Parameters:
    
    name - the name of the parameter
    
    inputShapes - the shapes of the input to the block
    
    Returns:
    
    the shape of the parameter specified
  - getDirectParameters
```
public java.util.List<Parameter> getDirectParameters()
```
    Returns a list of all the direct parameters of the block.
    
    Returns:
    
    the list of Parameter
  - saveParameters
```
public void saveParameters(java.io.DataOutputStream os)
                    throws java.io.IOException
```
    Writes the parameters of the block to the given outputStream.
    
    Parameters:
    
    os - the outputstream to save the parameters to
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
  - loadParameters
```
public void loadParameters(NDManager manager,
                           java.io.DataInputStream is)
                    throws java.io.IOException,
                           MalformedModelException
```
    Loads the parameters from the given input stream.
    
    Parameters:
    
    manager - an NDManager to create the parameter arrays
    
    is - the inputstream that stream the parameter values
    
    Throws:
    
    java.io.IOException - if an I/O error occurs
    
    MalformedModelException - if the model file is corrupted or unsupported

Class Convolution

Nested Class Summary

Field Summary

Fields inherited from class ai.djl.nn.AbstractBlock

Constructor Summary

Method Summary

Methods inherited from class ai.djl.nn.ParameterBlock

Methods inherited from class ai.djl.nn.AbstractBlock

Methods inherited from class java.lang.Object

Methods inherited from interface ai.djl.nn.Block

Field Detail

kernel

stride

pad

dilate

numFilters

numGroups

includeBias

weight

bias

Constructor Detail

Convolution

Method Detail

getExpectedLayout

getStringLayout

numDimensions

forward

beforeInitialize

getOutputShapes

getParameterShape

getDirectParameters

saveParameters

loadParameters