# dlconv

## Description

The convolution operation applies sliding filters to the input
data. Use the `dlconv`

function for deep learning convolution, grouped
convolution, and channel-wise separable convolution.

The `dlconv`

function applies the deep learning convolution operation
to `dlarray`

data.
Using `dlarray`

objects makes working with high
dimensional data easier by allowing you to label the dimensions. For example, you can label
which dimensions correspond to spatial, time, channel, and batch dimensions using the
`"S"`

, `"T"`

, `"C"`

, and
`"B"`

labels, respectively. For unspecified and other dimensions, use the
`"U"`

label. For `dlarray`

object functions that operate
over particular dimensions, you can specify the dimension labels by formatting the
`dlarray`

object directly, or by using the `DataFormat`

option.

**Note**

To apply convolution within a `layerGraph`

object
or `Layer`

array, use
one of the following layers:

applies the deep learning convolution operation to the formatted `Y`

= dlconv(`X`

,`weights`

,`bias`

)`dlarray`

object `X`

. The function uses sliding convolutional filters defined by
`weights`

and adds the constant `bias`

. The output
`Y`

is a formatted `dlarray`

object with the same format
as `X`

.

The function, by default, convolves over up to three dimensions
of `X`

labeled `"S"`

(spatial). To convolve over dimensions
labeled `"T"`

(time), specify `weights`

with a
`"T"`

dimension using a formatted `dlarray`

object or by
using the `WeightsFormat`

option.

For unformatted input data, use the `DataFormat`

option.

applies the deep learning convolution operation to the unformatted `Y`

= dlconv(`X`

,`weights`

,`bias`

,DataFormat=FMT)`dlarray`

object `X`

with format specified by `FMT`

. The output
`Y`

is an unformatted `dlarray`

object with dimensions
in the same order as `X`

. For example,
`DataFormat="SSCB"`

specifies data for 2-D convolution with format
`"SSCB"`

(spatial, spatial, channel, batch).

specifies options using one or more name-value pair arguments using any of the previous
syntaxes. For example, `Y`

= dlconv(___,`Name=Value`

)`WeightsFormat="TCU"`

specifies weights for 1-D
convolution with format `"TCU"`

(time, channel, unspecified).

## Examples

### Perform 2-D Convolution

Create a formatted `dlarray`

object containing a batch of 128 28-by-28 images with 3 channels. Specify the format `"SSCB"`

(spatial, spatial, channel, batch).

```
miniBatchSize = 128;
inputSize = [28 28];
numChannels = 3;
X = rand(inputSize(1),inputSize(2),numChannels,miniBatchSize);
X = dlarray(X,"SSCB");
```

View the size and format of the input data.

size(X)

`ans = `*1×4*
28 28 3 128

dims(X)

ans = 'SSCB'

Initialize the weights and bias for 2-D convolution. For the weights, specify 64 3-by-3 filters. For the bias, specify a vector of zeros.

filterSize = [3 3]; numFilters = 64; weights = rand(filterSize(1),filterSize(2),numChannels,numFilters); bias = zeros(1,numFilters);

Apply 2-D convolution using the `dlconv`

function.

Y = dlconv(X,weights,bias);

View the size and format of the output.

size(Y)

`ans = `*1×4*
26 26 64 128

dims(Y)

ans = 'SSCB'

### Perform Grouped Convolution

Convolve the input data in three groups of two channels each. Apply four filters per group.

Create the input data as 10 observations of size 100-by-100 with six channels.

```
height = 100;
width = 100;
channels = 6;
numObservations = 10;
X = rand(height,width,channels,numObservations);
X = dlarray(X,"SSCB");
```

Initialize the convolutional filters. Specify three groups of convolutions that each apply four convolution filters to two channels of the input data.

filterHeight = 8; filterWidth = 8; numChannelsPerGroup = 2; numFiltersPerGroup = 4; numGroups = 3; weights = rand(filterHeight,filterWidth,numChannelsPerGroup,numFiltersPerGroup,numGroups);

Initialize the bias term.

bias = rand(numFiltersPerGroup*numGroups,1);

Perform the convolution.

Y = dlconv(X,weights,bias); size(Y)

`ans = `*1×4*
93 93 12 10

dims(Y)

ans = 'SSCB'

The 12 channels of the convolution output represent the three groups of convolutions with four filters per group.

### Perform Channel-Wise Separable Convolution

Separate the input data into channels and perform convolution on each channel separately.

Create the input data as a single observation with a size of 64-by-64 and 10 channels. Create the data as an unformatted `dlarray`

.

height = 64; width = 64; numChannels = 10; X = rand(height,width,numChannels); X = dlarray(X);

Initialize the convolutional filters. Specify an ungrouped convolution that applies a single convolution to all three channels of the input data.

filterHeight = 8; filterWidth = 8; numChannelsPerGroup = 1; numFiltersPerGroup = 1; numGroups = numChannels; weights = rand(filterHeight,filterWidth,numChannelsPerGroup,numFiltersPerGroup,numGroups);

Initialize the bias term.

bias = rand(numFiltersPerGroup*numGroups,1);

Perform the convolution. Specify the dimension labels of the input data using the `DataFormat`

option.

```
Y = dlconv(X,weights,bias,DataFormat="SSC");
size(Y)
```

`ans = `*1×3*
57 57 10

Each channel is convolved separately, so there are 10 channels in the output.

### Perform 1-D Convolution

Create a formatted `dlarray`

object containing 128 sequences of length 512 containing 5 features. Specify the format `"CBT"`

(channel, batch, time).

```
numChannels = 5;
miniBatchSize = 128;
sequenceLength = 512;
X = rand(numChannels,miniBatchSize,sequenceLength);
X = dlarray(X,"CBT");
```

Initialize the weights and bias for 1-D convolution. For the weights, specify 64 filters with a filter size of 3. For the bias, specify a vector of zeros.

filterSize = 3; numFilters = 64; weights = rand(filterSize,numChannels,numFilters); bias = zeros(1,numFilters);

Apply 1-D convolution using the `dlconv`

function. To convolve over the `"T"`

(time) dimension of the input data, specify the weights format `"TCU"`

(time, channel, unspecified) using the `WeightsFormat`

option.

`Y = dlconv(X,weights,bias,WeightsFormat="TCU");`

View the size and format of the output.

size(Y)

`ans = `*1×3*
64 128 510

dims(Y)

ans = 'CBT'

## Input Arguments

`X`

— Input data

`dlarray`

| numeric array

Input data, specified as a formatted `dlarray`

, an unformatted
`dlarray`

, or a numeric array.

If `X`

is an unformatted `dlarray`

or a numeric
array, then you must specify the format using the `DataFormat`

option. If `X`

is a numeric array, then
either `weights`

or `bias`

must be a
`dlarray`

object.

The function, by default, convolves over up to three dimensions
of `X`

labeled `"S"`

(spatial). To convolve over dimensions
labeled `"T"`

(time), specify `weights`

with a
`"T"`

dimension using a formatted `dlarray`

object or by
using the `WeightsFormat`

option.

`weights`

— Convolutional filters

`dlarray`

| numeric array

Convolutional filters, specified as a formatted `dlarray`

, an
unformatted `dlarray`

, or a numeric array.

The size and format of the weights depends on the type of task. If
`weights`

is an unformatted `dlarray`

or a numeric
array, then the size and shape of `weights`

depends on the
`WeightsFormat`

option.

The following table describes the size and format of the weights for various tasks.
You can specify an array with the dimensions in any order using formatted
`dlarray`

objects or by using the `WeightsFormat`

option. When the weights has multiple dimensions with the same label (for example,
multiple dimensions labeled `"S"`

), then those dimensions must be in
ordered as described in this table.

Task | Required Dimensions | Size | Example | |
---|---|---|---|---|

Weights | Format | |||

1-D convolution | `"S"` (spatial) or `"T"` (time) | Filter size |
| `"SCU"` (spatial, channel,
unspecified) |

`"C"` (channel) | Number of channels | |||

`"U"` (unspecified) | Number of filters | |||

1-D grouped convolution | `"S"` (spatial) or `"T"` (time) | Filter size |
| `"SCUU"` (spatial, channel, unspecified,
unspecified) |

`"C"` (channel) | Number of channels per group | |||

First `"U"` (unspecified) | Number of filters per group | |||

Second `"U"` (unspecified) | Number of groups | |||

2-D convolution | First `"S"` (spatial) | Filter height |
| `"SSCU"` (spatial, spatial, channel,
unspecified) |

Second `"S"` (spatial) or `"T"`
(time) | Filter width | |||

`"C"` (channel) | Number of channels | |||

`"U"` (unspecified) | Number of filters | |||

2-D grouped convolution | First `"S"` (spatial) | Filter height |
| `"SSCUU"` (spatial, spatial, channel,
unspecified, unspecified) |

Second `"S"` (spatial) or `"T"`
(time) | Filter width | |||

`"C"` (channel) | Number of channels per group | |||

First `"U"` (unspecified) | Number of filters per group | |||

Second `"U"` (unspecified) | Number of groups | |||

3-D convolution | First `"S"` (spatial) | Filter height |
| `"SSSCU"` (spatial, spatial, spatial,
channel, unspecified) |

Second `"S"` (spatial) | Filter width | |||

Third `"S"` (spatial) or `"T"`
(time) | Filter depth | |||

`"C"` (channel) | Number of channels | |||

`"U"` (unspecified) | Number of filters |

For channel-wise separable (also known as depth-wise separable) convolution, use grouped convolution with number of groups equal to the number of channels.

**Tip**

The function, by default, convolves over up to three dimensions
of `X`

labeled `"S"`

(spatial). To convolve over dimensions
labeled `"T"`

(time), specify `weights`

with a
`"T"`

dimension using a formatted `dlarray`

object or by
using the `WeightsFormat`

option.

`bias`

— Bias constant

`dlarray`

| numeric vector | numeric scalar

Bias constant, specified as a formatted `dlarray`

, an unformatted
`dlarray`

, a numeric vector, or a numeric scalar.

If

`bias`

is a scalar, then the same bias is applied to each output.If

`bias`

has a nonsingleton dimension, then each element of`bias`

is the bias applied to the corresponding convolutional filter specified by`weights`

. The number of elements of`bias`

must match the number of filters specified by`weights`

.If

`bias`

is`0`

, then the bias term is disabled and no bias is added during the convolution operation.

If `bias`

is a formatted `dlarray`

, then the
nonsingleton dimension must be a channel dimension with label `'C'`

(channel).

### Name-Value Arguments

Specify optional pairs of arguments as
`Name1=Value1,...,NameN=ValueN`

, where `Name`

is
the argument name and `Value`

is the corresponding value.
Name-value arguments must appear after other arguments, but the order of the
pairs does not matter.

*
Before R2021a, use commas to separate each name and value, and enclose*
`Name`

*in quotes.*

**Example: **`DilationFactor=2`

sets the dilation factor for each
convolutional filter to `2`

.

`DataFormat`

— Dimension order of unformatted data

character vector | string scalar

Dimension order of unformatted input data, specified as a character vector or string
scalar `FMT`

that provides a label for each dimension of the data.

When you specify the format of a `dlarray`

object, each character provides a
label for each dimension of the data and must be one of these options:

`"S"`

— Spatial`"C"`

— Channel`"B"`

— Batch (for example, samples and observations)`"T"`

— Time (for example, time steps of sequences)`"U"`

— Unspecified

You can specify multiple dimensions labeled `"S"`

or
`"U"`

. You can use the labels `"C"`

,
`"B"`

, and `"T"`

at most once.

You must specify `DataFormat`

when the input data is not a
formatted `dlarray`

.

**Data Types: **`char`

| `string`

`WeightsFormat`

— Dimension order of weights

character vector | string scalar

Dimension order of the weights, specified as a character vector or string scalar that provides a label for each dimension of the weights.

The default value of `WeightsFormat`

depends on the
task:

Task | Default |
---|---|

1-D convolution | `"SCU"` (spatial, channel, unspecified) |

1-D grouped convolution | `"SCUU"` (spatial, channel, unspecified,
unspecified) |

2-D convolution | `"SSCU"` (spatial, spatial, channel,
unspecified) |

2-D grouped convolution | `"SSCUU"` (spatial, spatial, channel, unspecified,
unspecified) |

3-D convolution | `"SSSCU"` (spatial, spatial, spatial, channel,
unspecified) |

The supported combinations of dimension labels depends on the type of convolution,
for more information, see the `weights`

argument.

**Tip**

`X`

labeled `"S"`

(spatial). To convolve over dimensions
labeled `"T"`

(time), specify `weights`

with a
`"T"`

dimension using a formatted `dlarray`

object or by
using the `WeightsFormat`

option.

**Data Types: **`char`

| `string`

`Stride`

— Step size for traversing input data

`1`

(default) | numeric scalar | numeric vector

Step size for traversing the input data, specified as a numeric scalar or numeric vector.

To use the same step size for all convolution dimensions, specify the stride as a scalar. To specify a different value for each convolution dimension, specify the stride as a vector with elements ordered corresponding to the dimensions labels in the data format.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

`DilationFactor`

— Filter dilation factor

`1`

(default) | numeric scalar | numeric vector

Filter dilation factor, specified as specified as a numeric scalar or numeric vector.

To use the dilation factor all convolution dimensions, specify the dilation factor as a scalar. To specify a different value for each convolution dimension, specify the dilation factor as a vector with elements ordered corresponding to the dimensions labels in the data format.

Use the dilation factor to increase the receptive field of the filter (the area of the input that the filter can see) on the input data. Using a dilation factor corresponds to an effective filter size of `filterSize + (filterSize-1)*(dilationFactor-1)`

.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

`Padding`

— Size of padding

`0`

(default) | `"same"`

| `"causal"`

| numeric scalar | numeric vector | numeric matrix

Size of padding applied to the `"S"`

and `"T"`

dimensions given by the format of the weights, specified as one of the following:

`"same"`

— Apply padding such that the output dimension sizes are`ceil(inputSize/stride)`

, where`inputSize`

is the size of the corresponding input dimension. When`Stride`

is`1`

, the output is the same size as the input.`"causal"`

– Apply left padding with size`(FilterSize - 1)`

.*`DilationFactor`

. This option supports convolving over a single time or spatial dimension only. When`Stride`

is`1`

, the output is the same size as the input.Nonnegative integer

`sz`

— Add padding of size`sz`

to both ends of the`"S"`

or`"T"`

dimensions given by the format of the weights.Vector of integers

`sz`

— Add padding of size`sz(i)`

to both ends of the`i`

th`"S"`

or`"T"`

dimensions given by the format of the weights. The number of elements of`sz`

must match the number of`"S"`

or`"T"`

dimensions of the weights.Matrix of integers

`sz`

— Add padding of size`sz(1,i)`

and`sz(2,i)`

to the start and end of the`i`

th`"S"`

or`"T"`

dimensions given by the format of the weights. For example, for 2-D input,`[t l; b r]`

applies padding of size`t`

,`b`

,`l`

, and`r`

to the top, bottom, left, and right of the input, respectively.

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `char`

| `string`

`PaddingValue`

— Value to pad data

0 (default) | scalar | `'symmetric-include-edge'`

| `'symmetric-exclude-edge'`

| `'replicate'`

Value to pad data, specified as one of the following:

`PaddingValue` | Description | Example |
---|---|---|

Scalar | Pad with the specified scalar value. |
$$\left[\begin{array}{ccc}3& 1& 4\\ 1& 5& 9\\ 2& 6& 5\end{array}\right]\to \left[\begin{array}{ccccccc}0& 0& 0& 0& 0& 0& 0\\ 0& 0& 0& 0& 0& 0& 0\\ 0& 0& 3& 1& 4& 0& 0\\ 0& 0& 1& 5& 9& 0& 0\\ 0& 0& 2& 6& 5& 0& 0\\ 0& 0& 0& 0& 0& 0& 0\\ 0& 0& 0& 0& 0& 0& 0\end{array}\right]$$ |

`'symmetric-include-edge'` | Pad using mirrored values of the input, including the edge values. |
$$\left[\begin{array}{ccc}3& 1& 4\\ 1& 5& 9\\ 2& 6& 5\end{array}\right]\to \left[\begin{array}{ccccccc}5& 1& 1& 5& 9& 9& 5\\ 1& 3& 3& 1& 4& 4& 1\\ 1& 3& 3& 1& 4& 4& 1\\ 5& 1& 1& 5& 9& 9& 5\\ 6& 2& 2& 6& 5& 5& 6\\ 6& 2& 2& 6& 5& 5& 6\\ 5& 1& 1& 5& 9& 9& 5\end{array}\right]$$ |

`'symmetric-exclude-edge'` | Pad using mirrored values of the input, excluding the edge values. |
$$\left[\begin{array}{ccc}3& 1& 4\\ 1& 5& 9\\ 2& 6& 5\end{array}\right]\to \left[\begin{array}{ccccccc}5& 6& 2& 6& 5& 6& 2\\ 9& 5& 1& 5& 9& 5& 1\\ 4& 1& 3& 1& 4& 1& 3\\ 9& 5& 1& 5& 9& 5& 1\\ 5& 6& 2& 6& 5& 6& 2\\ 9& 5& 1& 5& 9& 5& 1\\ 4& 1& 3& 1& 4& 1& 3\end{array}\right]$$ |

`'replicate'` | Pad using repeated border elements of the input |
$$\left[\begin{array}{ccc}3& 1& 4\\ 1& 5& 9\\ 2& 6& 5\end{array}\right]\to \left[\begin{array}{ccccccc}3& 3& 3& 1& 4& 4& 4\\ 3& 3& 3& 1& 4& 4& 4\\ 3& 3& 3& 1& 4& 4& 4\\ 1& 1& 1& 5& 9& 9& 9\\ 2& 2& 2& 6& 5& 5& 5\\ 2& 2& 2& 6& 5& 5& 5\\ 2& 2& 2& 6& 5& 5& 5\end{array}\right]$$ |

**Data Types: **`single`

| `double`

| `int8`

| `int16`

| `int32`

| `int64`

| `uint8`

| `uint16`

| `uint32`

| `uint64`

| `char`

| `string`

## Output Arguments

`Y`

— Convolved feature map

`dlarray`

Convolved feature map, returned as a `dlarray`

with the same
underlying data type as `X`

.

If the input data `X`

is a formatted `dlarray`

,
then `Y`

has the same format as `X`

. If the input
data is not a formatted `dlarray`

, then `Y`

is an
unformatted `dlarray`

with the same dimension order as the input
data.

The size of the `"C"`

(channel) dimension of `Y`

depends on the task.

Task | Size of `"C"` Dimension |
---|---|

Convolution | Number of filters |

Grouped convolution | Number of filters per group multiplied by the number of groups |

## More About

### Deep Learning Convolution

The `dlconv`

function applies sliding convolution
filters to the input data. The `dlconv`

function supports convolution in
one, two, or three spatial dimensions or one time dimension. To learn more about deep
learning convolution, see the definition of convolutional layer
on the `convolution2dLayer`

reference page.

## Extended Capabilities

### GPU Arrays

Accelerate code by running on a graphics processing unit (GPU) using Parallel Computing Toolbox™.

Usage notes and limitations:

When at least one of the following input arguments is a

`gpuArray`

or a`dlarray`

with underlying data of type`gpuArray`

, this function runs on the GPU.`X`

`weights`

`bias`

For more information, see Run MATLAB Functions on a GPU (Parallel Computing Toolbox).

## Version History

**Introduced in R2019b**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)