sim

(To be removed) Simulate neural network

sim will be removed in a future release. For more information, see Transition Legacy Neural Network Code to dlnetwork Workflows.

For advice on updating your code, see Version History.

Syntax

[Y,Xf,Af] = sim(net,X,Xi,Ai,T)
[Y,Xf,Af] = sim(net,{Q TS},Xi,Ai)
[Y,...] = sim(net,...,'useParallel',...)
[Y,...] = sim(net,...,'useGPU',...)
[Y,...] = sim(net,...,'showResources',...)
[Ycomposite,...] = sim(net,Xcomposite,...)
[Ygpu,...] = sim(net,Xgpu,...)


To Get Help

Type help network/sim.

Description

sim simulates neural networks.

[Y,Xf,Af] = sim(net,X,Xi,Ai,T) takes

net	Network
X	Network inputs
Xi	Initial input delay conditions (default = zeros)
Ai	Initial layer delay conditions (default = zeros)
T	Network targets (default = zeros)

and returns

Y	Network outputs
Xf	Final input delay conditions
Af	Final layer delay conditions

sim is usually called implicitly by calling the neural network as a function. For instance, these two expressions return the same result:

y = sim(net,x,xi,ai)
y = net(x,xi,ai)

Note that arguments Xi, Ai, Xf, and Af are optional and need only be used for networks that have input or layer delays.

The signal arguments can have two formats: cell array or matrix.

The cell array format is easiest to describe. It is most convenient for networks with multiple inputs and outputs, and allows sequences of inputs to be presented:

X	Ni-by-TS cell array	Each element X{i,ts} is an Ri-by-Q matrix.
Xi	Ni-by-ID cell array	Each element Xi{i,k} is an Ri-by-Q matrix.
Ai	Nl-by-LD cell array	Each element Ai{i,k} is an Si-by-Q matrix.
T	No-by-TS cell array	Each element X{i,ts} is a Ui-by-Q matrix.
Y	No-by-TS cell array	Each element Y{i,ts} is a Ui-by-Q matrix.
Xf	Ni-by-ID cell array	Each element Xf{i,k} is an Ri-by-Q matrix.
Af	Nl-by-LD cell array	Each element Af{i,k} is an Si-by-Q matrix.

where

Ni	=	net.numInputs
Nl	=	net.numLayers
No	=	net.numOutputs
ID	=	net.numInputDelays
LD	=	net.numLayerDelays
TS	=	Number of time steps
Q	=	Batch size
Ri	=	net.inputs{i}.size
Si	=	net.layers{i}.size
Ui	=	net.outputs{i}.size

The columns of Xi, Ai, Xf, and Af are ordered from oldest delay condition to most recent:

Xi{i,k}	=	Input i at time ts = k - ID
Xf{i,k}	=	Input i at time ts = TS + k - ID
Ai{i,k}	=	Layer output i at time ts = k - LD
Af{i,k}	=	Layer output i at time ts = TS + k - LD

The matrix format can be used if only one time step is to be simulated (TS = 1). It is convenient for networks with only one input and output, but can also be used with networks that have more.

Each matrix argument is found by storing the elements of the corresponding cell array argument in a single matrix:

X	(sum of Ri)-by-Q matrix
Xi	(sum of Ri)-by-(ID*Q) matrix
Ai	(sum of Si)-by-(LD*Q) matrix
T	(sum of Ui)-by-Q matrix
Y	(sum of Ui)-by-Q matrix
Xf	(sum of Ri)-by-(ID*Q) matrix
Af	(sum of Si)-by-(LD*Q) matrix

[Y,Xf,Af] = sim(net,{Q TS},Xi,Ai) is used for networks that do not have an input when cell array notation is used.

[Y,...] = sim(net,...,'useParallel',...), [Y,...] = sim(net,...,'useGPU',...), or [Y,...] = sim(net,...,'showResources',...) (or the network called as a function) accepts optional name/value pair arguments to control how calculations are performed. Two of these options allow training to happen faster or on larger datasets using parallel workers or GPU devices if Parallel Computing Toolbox is available. These are the optional name/value pairs:

'useParallel','no'	Calculations occur on normal MATLAB thread. This is the default 'useParallel' setting.
'useParallel','yes'	Calculations occur on parallel workers if a parallel pool is open. Otherwise calculations occur on the normal MATLAB thread.
'useGPU','no'	Calculations occur on the CPU. This is the default 'useGPU' setting.
'useGPU','yes'	Calculations occur on the current gpuDevice if it is a supported GPU (See Parallel Computing Toolbox for GPU requirements.) If the current gpuDevice is not supported, calculations remain on the CPU. If 'useParallel' is also 'yes' and a parallel pool is open, then each worker with a unique GPU uses that GPU, other workers run calculations on their respective CPU cores.
'useGPU','only'	If no parallel pool is open, then this setting is the same as 'yes'. If a parallel pool is open, then only workers with unique GPUs are used. However, if a parallel pool is open, but no supported GPUs are available, then calculations revert to performing on all worker CPUs.
'showResources','no'	Do not display computing resources used at the command line. This is the default setting.
'showResources','yes'	Show at the command line a summary of the computing resources actually used. The actual resources may differ from the requested resources, if parallel or GPU computing is requested but a parallel pool is not open or a supported GPU is not available. When parallel workers are used, each worker’s computation mode is described, including workers in the pool that are not used.

[Ycomposite,...] = sim(net,Xcomposite,...) takes Composite data and returns Composite results. If Composite data is used, then 'useParallel' is automatically set to 'yes'.

[Ygpu,...] = sim(net,Xgpu,...) takes gpuArray data and returns gpuArray results. If gpuArray data is used, then 'useGPU' is automatically set to 'yes'.

Examples

In the following examples, the sim function is called implicitly by calling the neural network object (net) as a function.

Simulate Feedforward Networks

This example loads a dataset that maps anatomical measurements x to body fat percentages t. A feedforward network with 10 neurons is created and trained on that data, then simulated.

[x,t] =  bodyfat_dataset;  
net = feedforwardnet(10);
net = train(net,x,t);

y = net(x);

Algorithms

sim uses these properties to simulate a network net.

net.numInputs, net.numLayers
net.outputConnect, net.biasConnect
net.inputConnect, net.layerConnect

These properties determine the network’s weight and bias values and the number of delays associated with each weight:

net.IW{i,j}
net.LW{i,j}
net.b{i}
net.inputWeights{i,j}.delays
net.layerWeights{i,j}.delays

These function properties indicate how sim applies weight and bias values to inputs to get each layer’s output:

net.inputWeights{i,j}.weightFcn
net.layerWeights{i,j}.weightFcn
net.layers{i}.netInputFcn
net.layers{i}.transferFcn

Version History

Introduced before R2006a

R2026a: sim will be removed

sim will be removed in a future release.

To learn more about neural network training and prediction, see these examples and topics:

• Training Neural Networks with Tabular Data

• Training Neural Networks with Time Series Data

To train a neural network with tabular data, use one of these functions:

• fitrnet (Statistics and Machine Learning Toolbox) — Train regression neural network. Use this function for simple regression tasks.

• fitcnet (Statistics and Machine Learning Toolbox) — Train classification neural network. Use this function for simple classification tasks.

• trainnet — Train neural network. Use this function when the fitrnet and fitcnet functions do not provide the training options that you need for your task.

To train a neural network with time series data, use one of these options:

• Time Series Modeler app — Interactively design and train neural networks for time series data.

• trainnet — Train neural network. Use this function when you need more flexibility in the network architecture or training algorithm.

To make predictions with Statistics and Machine Learning Toolbox™ neural network models, use one of these functions:

• predict (Statistics and Machine Learning Toolbox) — predict responses using regression neural network.

• predict (Statistics and Machine Learning Toolbox) — predict responses using classification neural network.

To make predictions with dlnetwork objects, use one of these functions:

• forward — compute deep learning network output for training.

• predict — compute deep learning network output for inference.

• minibatchpredict — make neural network predictions using batches of data.

For more information, see Transition Legacy Neural Network Code to dlnetwork Workflows.