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.

Input Arguments

fun — Function to apply to layer input

function handle

Function to apply to layer input, specified as a function handle with the syntax [Y1,...,YM] = fun(X1,...,XN), where the inputs and outputs are dlarray objects, and M and N correspond to NumOutputs and NumInputs, respectively. In this syntax, 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.

Tip

When you use 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.

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

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.

This argument sets the PredictFcn property.

Data Types: function_handle

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.

Example: functionLayer(fun,NumInputs=2,NumOutputs=3) specifies that the layer has two inputs and three outputs.

Formattable — Flag to enable customization of processing of formatted and unformatted data

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

Flag to enable customization of processing of formatted and unformatted data, specified as 0 (false) or 1 (true).

This table describes how the software processes formatted and unformatted data in functionLayerobjects.

Formattable Value	Input Data Processing	Output Data Processing
1 (true)	The software passes the layer input to the layer function directly: If the layer receives formatted data, then the software passes the formatted data to the layer function. If the layer receives unformatted data, then the software passes the unformatted data to the layer function.	The software passes the layer function outputs to subsequent layers directly: If the layer function returns formatted data, then the software passes the formatted data to subsequent layers. If the layer receives formatted data and the layer function outputs unformatted data, then the software automatically applies the format of the input data to the output data and passes the formatted data to subsequent layers. If the layer receives unformatted data and the layer function return unformatted data, then the software passes the unformatted data to subsequent layers. Warning For functionLayer objects with the Formattable argument set to 1 (true), support for automatically formatting unformatted data will be removed in a future release. Instead, ensure that the layer outputs formatted data. To reproduce the previous behavior, use the command Y = dlarray(Y,dims(X)); in the layer function, where X and Y are the layer input and output, respectively.
0 (false)	The software removes the formats from any formatted inputs and passes the unformatted data to the layer function: If the layer receives formatted data, then the software removes the format and passes the unformatted data to the layer function. If the layer receives unformatted data, then it passes the unformatted data to the layer function directly. (since R2024b) Before R2024b: If Formattable is 0 (false), then the layer input must be formatted.	The output data must be unformatted. The software applies the formats of the layer inputs to any unformatted layer function outputs, and passes the result to subsequent layers: If the layer receives unformatted data and the layer function outputs unformatted data, then the software passes the unformatted data to subsequent layers. If the layer receives formatted data and the layer function outputs unformatted data, then the software automatically applies the format of the layer input to the and passes the formatted data subsequent layers.

This table describes how the software processes formatted and unformatted data in functionLayerobjects.

Formattable Value	Input Data Processing	Output Data Processing
1 (true)	The software passes the layer input to the layer function directly: If the layer receives formatted data, then the software passes the formatted data to the layer function. If the layer receives unformatted data, then the software passes the unformatted data to the layer function.	The software passes the layer function outputs to subsequent layers directly: If the layer function returns formatted data, then the software passes the formatted data to subsequent layers. If the layer receives formatted data and the layer function outputs unformatted data, then the software automatically applies the format of the input data to the output data and passes the formatted data to subsequent layers. If the layer receives unformatted data and the layer function return unformatted data, then the software passes the unformatted data to subsequent layers. Warning For functionLayer objects with the Formattable argument set to 1 (true), support for automatically formatting unformatted data will be removed in a future release. Instead, ensure that the layer outputs formatted data. To reproduce the previous behavior, use the command Y = dlarray(Y,dims(X)); in the layer function, where X and Y are the layer input and output, respectively.
0 (false)	The software removes the formats from any formatted inputs and passes the unformatted data to the layer function: If the layer receives formatted data, then the software removes the format and passes the unformatted data to the layer function. If the layer receives unformatted data, then it passes the unformatted data to the layer function directly. (since R2024b) Before R2024b: If Formattable is 0 (false), then the layer input must be formatted.	The output data must be unformatted. The software applies the formats of the layer inputs to any unformatted layer function outputs, and passes the result to subsequent layers: If the layer receives unformatted data and the layer function outputs unformatted data, then the software passes the unformatted data to subsequent layers. If the layer receives formatted data and the layer function outputs unformatted data, then the software automatically applies the format of the layer input to the and passes the formatted data subsequent layers.

This argument sets the Formattable property.

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

Acceleratable — Flag indicating that function supports acceleration

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

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

This argument sets the Acceleratable property.

Data Types: logical

NumInputs — Number of inputs

positive integer

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 or InputNames.

If fun has a fixed number of inputs, then the default value is nargin(fun).

This argument sets the NumInputs property.

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

InputNames — Input names

string array | cell array of character vectors

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

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 or InputNames.

If NumInputs is 1, then the default value is "in". If NumInputs is greater than 1, then the default value is ["in1" "in2" ... "inN"], where N is the number of inputs.

This argument sets the InputNames property.

Data Types: string | cell

NumOutputs — Number of outputs

1 (default) | positive integer

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 using varargout, then you must specify the number of layer outputs using NumOutputs or OutputNames.

If fun has a fixed number of outputs, then the default value is nargout(fun).

This argument sets the NumOutputs property.

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

OutputNames — Output names

string array | cell array of character vectors

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

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

If NumOutputs is 1, then the default value is "out". If NumOutputs is greater than 1, then the default is ["out1" "out2" ... "outM"}, where M is the number of outputs.

This argument sets the OutputNames property.

Data Types: string | cell

Name — Layer name

"" (default) | character vector | string scalar

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

This argument sets the Name property.

Data Types: char | string

Description — One-line description of layer

string scalar | character vector

One-line description of the layer, specified as a string scalar or a character vector. This description appears when you display a Layer array and when you use the analyzeNetwork function.

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

Data Types: char | string

Properties

Function

PredictFcn — Function to apply to layer input

function handle

This property is read-only after creation.

Function to apply to layer input, specified as a function handle with the syntax [Y1,...,YM] = fun(X1,...,XN), where the inputs and outputs are dlarray objects, and M and N correspond to NumOutputs and NumInputs, respectively. In this syntax, 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.

Tip

When you use 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 to enable customization of processing of formatted and unformatted data

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

This property is read-only after creation.

Flag to enable customization of processing of formatted and unformatted data, specified as 0 (false) or 1 (true).

This table describes how the software processes formatted and unformatted data in functionLayerobjects.

Formattable Value	Input Data Processing	Output Data Processing
1 (true)	The software passes the layer input to the layer function directly: If the layer receives formatted data, then the software passes the formatted data to the layer function. If the layer receives unformatted data, then the software passes the unformatted data to the layer function.	The software passes the layer function outputs to subsequent layers directly: If the layer function returns formatted data, then the software passes the formatted data to subsequent layers. If the layer receives formatted data and the layer function outputs unformatted data, then the software automatically applies the format of the input data to the output data and passes the formatted data to subsequent layers. If the layer receives unformatted data and the layer function return unformatted data, then the software passes the unformatted data to subsequent layers. Warning For functionLayer objects with the Formattable argument set to 1 (true), support for automatically formatting unformatted data will be removed in a future release. Instead, ensure that the layer outputs formatted data. To reproduce the previous behavior, use the command Y = dlarray(Y,dims(X)); in the layer function, where X and Y are the layer input and output, respectively.
0 (false)	The software removes the formats from any formatted inputs and passes the unformatted data to the layer function: If the layer receives formatted data, then the software removes the format and passes the unformatted data to the layer function. If the layer receives unformatted data, then it passes the unformatted data to the layer function directly. (since R2024b) Before R2024b: If Formattable is 0 (false), then the layer input must be formatted.	The output data must be unformatted. The software applies the formats of the layer inputs to any unformatted layer function outputs, and passes the result to subsequent layers: If the layer receives unformatted data and the layer function outputs unformatted data, then the software passes the unformatted data to subsequent layers. If the layer receives formatted data and the layer function outputs unformatted data, then the software automatically applies the format of the layer input to the and passes the formatted data subsequent layers.

Data Types: logical

Acceleratable — Flag indicating that function supports acceleration

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

This property is read-only after creation.

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

Data Types: logical

Layer

Name — Layer name

'' (default) | character vector | string scalar

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

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 after creation.

One-line description of the layer, specified as a string scalar or a character vector. This description appears when you display a Layer array and when you use the analyzeNetwork function.

Data Types: char | string

NumInputs — Number of inputs

positive integer

This property is read-only after creation.

Number of inputs, specified as a positive integer.

Data Types: double

InputNames — Input names

cell array of character vectors

This property is read-only after creation.

Input names of the layer, stored as a cell array of character vectors.

Data Types: cell

NumOutputs — Number of outputs

1 (default) | positive integer

This property is read-only after creation.

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

Data Types: double

OutputNames — Output names

cell array of character vectors

This property is read-only after creation.

Output names of the layer, stored as a cell array of character vectors.

Data Types: 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.

  Show 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 = 
  3×1 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

Layer Input and Output Formats

Layers in a layer array or layer graph pass data to subsequent layers as formatted dlarray objects. The format of a dlarray object is a string of characters in which each character describes the corresponding dimension of the data. The format consists of one or more of these characters:

• "S" — Spatial

• "C" — Channel

• "B" — Batch

• "T" — Time

• "U" — Unspecified

For example, you can describe 2-D image data that is represented as a 4-D array, where the first two dimensions correspond to the spatial dimensions of the images, the third dimension corresponds to the channels of the images, and the fourth dimension corresponds to the batch dimension, as having the format "SSCB" (spatial, spatial, channel, batch).

Using formatted dlarray objects in layers functions also allows you to define layers where the inputs and outputs have different formats, such as layers that permute, add, or remove dimensions. For example, you can define a layer that takes as input a mini-batch of images with the format "SSCB" (spatial, spatial, channel, batch) and output a mini-batch of sequences with the format "CBT" (channel, batch, time). Using formatted dlarray objects also allows you to define layers that can operate on data with different input formats, for example, layers that support inputs with the formats "SSCB" (spatial, spatial, channel, batch) and "CBT" (channel, batch, time).

You can specify how to processes formatted and unformatted data that the software passes to and from the layer by setting the Formattable argument.

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

R2025a: Support for unformatted layer inputs

Function layers now support receiving unformatted data directly. When these layers receive unformatted data, they pass the unformatted data to subsequent layers.

For more information, see the Formattable argument.

R2025a: Support for automatically formatting outputs will be removed

For functionLayer objects with the Formattable property set to 1 (true), support for automatically formatting unformatted data will be removed in a future release. Instead, ensure that the layer outputs formatted data. To reproduce the previous behavior, use the command Y = dlarray(Y,dims(X)); in the layer forward functions, where X and Y are the layer input and output, respectively.

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.