functionLayer

Function layer

Since R2021b

Description

A function layer applies a specified function to the layer input.

If Deep Learning Toolbox™ does not provide the layer that you need for your task, then you can define new layers by creating function layers using functionLayer. Function layers only support operations that do not require additional properties, learnable parameters, or states. For layers that require this functionality, define the layer as a custom layer. For more information, see Define Custom Deep Learning Layers.

Creation

Syntax

layer = functionLayer(fun)

layer = functionLayer(fun,Name=Value)

Description

layer = functionLayer(fun) creates a function layer and sets the PredictFcn property.

layer = functionLayer(fun,Name=Value) sets optional properties using one or more name-value arguments. For example, functionLayer(fun,NumInputs=2,NumOutputs=3) specifies that the layer has two inputs and three outputs. You can specify multiple name-value arguments.

Properties

Function

PredictFcn — Function to apply to layer input

function handle

This property is read-only.

Function to apply to layer input, specified as a function handle.

The specified function must have the syntax [Y1,...,YM] = fun(X1,...,XN), where the inputs and outputs are dlarray objects, and M and N correspond to the NumOutputs and NumInputs properties, respectively.

The inputs X1, …, XN correspond to the layer inputs with names given by InputNames. The outputs Y1, …, YM correspond to the layer outputs with names given by OutputNames.

If the specified function is not accessible when you create the layer, you must specify the NumInputs and NumOutputs properties.

The inputs and outputs of the predict function can be complex-valued. (since R2024a) If the layer outputs complex-valued data, then when you use the layer in a neural network, you must ensure that the subsequent layers or loss function support complex-valued input.

Before R2024a: The inputs and outputs of the predict function must not be complex. If the predict function of the layer involves complex numbers, convert all outputs to real values before returning them.

For a list of functions that support dlarray input, see List of Functions with dlarray Support.

Tip

When using the layer, you must ensure that the specified function is accessible. For example, to ensure that the layer can be reused in multiple live scripts, save the function in its own separate file.

Data Types: function_handle

Formattable — Flag indicating that function operates on formatted dlarray objects

0 (false) (default) | 1 (true)

This property is read-only.

Flag indicating whether the layer function operates on formatted dlarray objects, specified as 0 (false) or 1 (true).

Data Types: logical

Acceleratable — Flag indicating that function supports acceleration

0 (false) (default) | 1 (true)

This property is read-only.

Flag indicating whether the layer function supports acceleration using dlaccelerate, specified as 0 (false) or 1 (true).

Tip

Setting Acceleratable to 1 (true) can significantly improve the performance of training and inference (prediction) using a dlnetwork.

Most simple functions support acceleration using dlaccelerate. For more information, see Deep Learning Function Acceleration for Custom Training Loops.

Data Types: logical

Layer

Name — Layer name

"" (default) | character vector | string scalar

Layer name, specified as a character vector or string scalar. For Layer array input, the trainnet and dlnetwork functions automatically assign names to layers with the name "".

The FunctionLayer object stores this property as a character vector.

Data Types: char | string

Description — One-line description of layer

string scalar | character vector

This property is read-only.

One-line description of the layer, specified as a string scalar or a character vector. This description appears when the layer is displayed in a Layer array.

If you do not specify a layer description, then the software displays the layer operation.

Data Types: char | string

NumInputs — Number of inputs

positive integer

This property is read-only.

Number of inputs, specified as a positive integer.

The layer must have a fixed number of inputs. If PredictFcn supports a variable number of input arguments using varargin, then you must specify the number of layer inputs using NumInputs.

If you do not specify NumInputs, then the software sets NumInputs to nargin(PredictFcn).

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

InputNames — Input names

string array | cell array of character vectors

This property is read-only.

Input names of the layer, specified as a string array or a cell array of character vectors.

If you do not specify InputNames and NumInputs is 1, then the software sets InputNames to {'in'}. If you do not specify InputNames and NumInputs is greater than 1, then the software sets InputNames to {'in1',...,'inN'}, where N is the number of inputs.

Data Types: string | cell

NumOutputs — Number of outputs

1 (default) | positive integer

This property is read-only.

Number of outputs of the layer, specified as a positive integer.

The layer must have a fixed number of outputs. If PredictFcn supports a variable number of output arguments, then you must specify the number of layer outputs using NumOutputs.

If you do not specify NumOutputs, then the software sets NumOutputs to nargout(PredictFcn).

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

OutputNames — Output names

string array | cell array of character vectors

This property is read-only.

Output names of the layer, specified as a string array or a cell array of character vectors.

If you do not specify OutputNames and NumOutputs is 1, then the software sets OutputNames to {'out'}. If you do not specify OutputNames and NumOutputs is greater than 1, then the software sets OutputNames to {'out1',...,'outM'}, where M is the number of outputs.

Data Types: string | cell

Examples

Define Softsign Layer as Function Layer

Create a function layer object that applies the softsign operation to the input. The softsign operation is given by the function $\mathit{f}\left(\mathit{x}\right)=\frac{\mathit{x}}{1+\left|\mathit{x}\right|}$.

layer = functionLayer(@(X) X./(1 + abs(X)))

Include a softsign layer, specified as a function layer, in a layer array. Specify that the layer has the description "softsign".

layers = [
    imageInputLayer([28 28 1])
    convolution2dLayer(5,20)
    functionLayer(@(X) X./(1 + abs(X)),Description="softsign")
    maxPooling2dLayer(2,Stride=2)
    fullyConnectedLayer(10)
    softmaxLayer]

Reformat Data Using Function Layer

Create a function layer that reformats input data with the format "CB" (channel, batch) to have the format "SBC" (spatial, batch, channel). To specify that the layer operates on formatted data, set the Formattable option to true. To specify that the layer function supports acceleration using dlaccelerate, set the Acceleratable option to true.

layer = functionLayer(@(X) dlarray(X,"SBC"),Formattable=true,Acceleratable=true)

layer = 
  FunctionLayer with properties:

             Name: ''
       PredictFcn: @(X)dlarray(X,"SBC")
      Formattable: 1
    Acceleratable: 1

   Learnable Parameters
    No properties.

   State Parameters
    No properties.

Use properties method to see a list of all properties.

Include a function layer that reformats the input to have the format "SB" in a layer array. Set the layer description to "channel to spatial".

layers = [
    featureInputLayer(10)
    functionLayer(@(X) dlarray(X,"SBC"),Formattable=true,Acceleratable=true,Description="channel to spatial")
    convolution1dLayer(3,16)]

layers = 
  3x1 Layer array with layers:

     1   ''   Feature Input     10 features
     2   ''   Function          channel to spatial
     3   ''   1-D Convolution   16 3 convolutions with stride 1 and padding [0  0]

In this network, the 1-D convolution layer convolves over the "S" (spatial) dimension of its input data. This operation is equivalent to convolving over the "C" (channel) dimension of the network input data.

Convert the layer array to a dlnetwork object and pass a random array of data with the format "CB".

dlnet = dlnetwork(layers);

X = rand(10,64);
dlX = dlarray(X,"CB");

dlY = forward(dlnet,dlX);

View the size and format of the output data.

size(dlY)

ans = 1×3

     8    16    64

dims(dlY)

ans = 
'SCB'

Algorithms

Complex-valued inputs and outputs

FunctionLayer objects support complex-valued input and outputs. (since R2024a) The layer applies the same forward function to complex-valued input as it does to real-valued input and outputs complex-valued data where applicable.

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• The layer function fun must be a named function on the path.

• The Formattable property must be 0 (false)

GPU Code Generation

Generate CUDA® code for NVIDIA® GPUs using GPU Coder™.

Usage notes and limitations:

• The layer function fun must be a named function on the path.

• The Formattable property must be 0 (false)

Version History

Introduced in R2021b

R2024a: Support for complex-valued inputs and outputs

FunctionLayer objects support complex-valued input and outputs. The layer applies the same forward function to complex-valued input as it does to real-valued input and outputs complex-valued data where applicable.