functionLayer
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
Description
creates a function layer and sets the layer
= functionLayer(fun
)PredictFcn
property.
sets optional properties using
one or more name-value arguments. For example,
layer
= functionLayer(fun
,Name=Value
)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
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 .
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 be0
(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 be0
(false)
Version History
Introduced in R2021bR2024a: 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.
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)