idNeuralStateSpace
Description
Use idNeuralStateSpace
to create a blackbox continuoustime or
discretetime neural statespace model with identifiable (estimable) network weights and bias.
You can use the trained blackbox model for control, estimation, optimization, and reduced
order modeling.
Continuoustime neural statespace models have the following general form,
$$\begin{array}{l}\dot{x}\left(t\right)=F\left(t,x\left(t\right),u\left(t\right)\right)\\ y\left(t\right)=\left[\begin{array}{c}{y}_{1}(t)\\ {y}_{2}(t)\end{array}\right]=\left[\begin{array}{c}x\left(t\right)+{e}_{1}(t)\\ H\left(t,x\left(t\right),u\left(t\right)\right)+{e}_{2}(t)\end{array}\right]\end{array}$$
where the state function F and the nontrivial output function H are approximated by neural networks. Because you need to measure all the states to properly train the state function, the states measurements are considered to be part of the output function. Here, e_{1} and e_{2} are measurement noises in the data sets which are minimized by the network training algorithm.
For discretetime statespace systems, the state and output functions have this form.
$$\begin{array}{l}x\left(t+1\right)=F\left(t,x\left(t\right),u\left(t\right)\right)\\ y\left(t\right)=\left[\begin{array}{c}{y}_{1}(t)\\ {y}_{2}(t)\end{array}\right]=\left[\begin{array}{c}x\left(t\right)+{e}_{1}(t)\\ H\left(t,x\left(t\right),u\left(t\right)\right)+{e}_{2}(t)\end{array}\right]\end{array}$$
For more information on neural statespace models, see What are Neural StateSpace Models?.
Creation
Description
creates an autonomous (noinput) timeinvariant continuoustime neural statespace
object with nss
= idNeuralStateSpace(nx
)nx
state variables and output identical to
state.
specifies namevalue pair arguments after any of the input argument in the previous
syntax. You can use namevalue pair arguments to set the number of inputs and outputs
and other system configurations such as time domain, whether the system is time
invariant and whether the system output has feedthrough.nss
= idNeuralStateSpace(___,Name=Value
)
For example, nss =
idNeuralStateSpace(3,NumInputs=2,NumOutputs=4,Ts=0.1)
creates a
timeinvariant discretetime neural statespace object with 3
states,
2
inputs, four outputs (the first three are state measurements),
and sample time 0.1
. The system is also time invariant (both state
and output functions do not explicitly depend on time) and does not have direct
feedthrough (the input does not have immediate impact on output).
Input Arguments
nx
— Number of state variables
positive integer
Number of state variables, specified as a positive integer.
Example: 2
Specify optional pairs of arguments as
Name1=Value1,...,NameN=ValueN
, where Name
is
the argument name and Value
is the corresponding value.
Namevalue arguments must appear after other arguments, but the order of the
pairs does not matter.
Use namevalue pair arguments to specify NumInputs
,
NumOutputs
and the Ts
,
IsTimeInvariant
, and HasFeedthrough
properties
of nss
.
Example: Ts=0.1
NumInputs
— Number of input variables
0 (default)  nonnegative integer
Number of input variables, specified as a nonnegative integer.
Example: NumInputs=2
NumOutputs
— Number of output variables
nx
(default)  nonnegative integer
Number of output variables, specified as a positive integer greater than or
equal to nx
. The value must be greater than
nx
because all the states are measured.
For example, if nx
is 2
,
NumOutputs=4
means that the state space system has four
outputs, with the first two outputs being state measurements, and the last two are
outputs from the output function H.
Example: NumOutputs=4
HasFeedthrough
— Option to set direct feedthrough
false
(default)  true
Option to set direct feedthrough, specified as one of the following:
true
— the nontrivial output measurement y_{2} is an explicit function of the input, that is y_{2}(t) = H(t,x,u).false
— the nontrivial output measurement y_{2} is not an explicit function of the input, even ifNumInputs
is greater than zero. This is the default case, and y_{2}(t) = H(t,x).
This argument sets the value of the readonly property
FeedthroughInOutputNetwork
of
nss
.
Example: false
Properties
StateNetwork
— State function network
dlnetwork
object
State function network, specified as a dlnetwork
(Deep Learning Toolbox) object. This network
approximates the state function of the statespace system (F). For
continuous statespace systems the state function returns the system state derivative
with respect to time, while for discretetime statespace systems it returns the next
state. The inputs of the function are time (if IsTimeInvariant
is
false
), the current state, and the current input (if
NumInputs
is positive), in that order.
When an idNeuralStateSpace
model is constructed, a default state
network is created. It is a multilayer perceptron (MLP) network with the following features:
Two hidden layers: each is a fullyconnected layer with 64 nodes.
Two activation layers: each featuring a hyperbolic tangent (tanh) function.
One output layer: a fullyconnected layer with
nx
nodes.
To change the default network configuration, use createMLPNetwork
. For
example:
nss.StateNetwork = createMLPNetwork(nss,"state",... LayerSizes=[64 64 64],... Activations="sigmoid")
You can also directly assign a custom dlnetwork
object as the state
function network when the sizes of the input layers are distinguishable. For
example:
nss.StateNetwork = dlnet;
dlnet
is a custom dlnetwork
object with the
configuration as mentioned under the dlnet
argument in setNetwork
.
For more information on custom networks and how to assign them to an
idNeuralStateSpace
object when the input layer sizes are not
distinguishable, see setNetwork
.
To train both state and output networks, use nlssest
. For
example:
options1 = nssTrainingOptions("adam");
nss = nlssest(U, Y, nss, options1);
Note
To train the network, use
nlssest
which updates the weights and biases of the network. After training completes, the network weights and biases are said to be "trained".A new training starts with the previously trained network. To reset the network, you can either manually assign the learnables of the
dlnetwork
object or initialize it.Multilayer perceptron (MLP) networks with at least one hidden layer featuring squashing functions (such as hyperbolic tangent or sigmoid) are universal approximators, that is, are theoretically capable of approximating any function to any desired degree of accuracy provided that sufficiently many hidden units are available.
Deeper networks (networks with more hidden layers) can approximate compositional functions as well as shallow networks but with exponentially lower number of training parameters and sample complexity.
OutputNetwork
— Output function networks
dlnetwork
object
Output function networks, specified as a 2by1 array of dlnetwork
(Deep Learning Toolbox) objects. The first network
represents the identity relation between y_{1}
and x, since all the states are measured. This network has no
learnable parameters, is fixed, and cannot be changed or trained.
The second network approximates the output function H of the
statespace system, which is a function of time (if IsTimeInvariant
is false
), the current state, and the current input (if
NumInputs
is positive and HasFeedthrough
is
true
), in that order.
When you create an idNeuralStateSpace
model, the default network
created to approximate H is a multilayer perceptron (MLP) network
with the following features:
Two hidden layers: each is a fullyconnected layer with 64 nodes.
Two activation layers: each featuring a hyperbolic tangent (tanh) function.
One output layer: a fullyconnected layer with
NumOutputs
nx
nodes.
To change the default network configuration, use createMLPNetwork
. For
example:
nss.OutputNetwork = createMLPNetwork(nss,"output",... LayerSizes=[64 64 64],... Activations="sigmoid")
You can also directly assign a custom dlnetwork
object as the
output function network when the sizes of the input layers are distinguishable. For
example:
nss.OutputNetwork = dlnet;
dlnet
is a custom dlnetwork
object with the
configuration as mentioned under the dlnet
argument in setNetwork
.
For more information on custom networks and how to assign them to an
idNeuralStateSpace
object when the input layer sizes are not
distinguishable, see setNetwork
.
To train both state and output networks, use nlssest
. For
example:
options1 = nssTrainingOptions("adam") options2 = nssTrainingOptions("sgdm") nss = nlssest(U, Y, nss, [options1; options2])
Encoder
— Encoder function network
[]
(default)  dlnetwork
object
Encoder function network, specified as a dlnetwork
(Deep Learning Toolbox) object. The encoder maps the
state to a latent state (usually, of a lower dimension), which is the input to the state
function network. The dimension of this latent state is specified by LatentDim.
The default value is []
, which means that you are not using the
encoder. You add an encoder to your model by changing the default value of
LatentDim
. This encoder network, by default contains two layers
of size 64 with tanh
as the activation function.
To change the default encoder network configuration, use createMLPNetwork
. For
example:
nss.Encoder = createMLPNetwork(nss,"encoder",... LayerSizes=[4 4],... Activations="sigmoid")
You can also directly assign a custom dlnetwork
object as the
encoder function network. For
example:
nss.Encoder = dlnet;
dlnet
is a custom dlnetwork
object with one input
representing the original state and one output representing the latent state.
For more information on autoencoders, see What are Neural StateSpace Models?
Decoder
— Decoder function network
[]
(default)  dlnetwork
object
Decoder function network, specified as a dlnetwork
(Deep Learning Toolbox) object. The output of the
state function network is the input of the decoder. The decoder maps the latent state
back to the original state. The dimension of the latent state is specified by LatentDim.
The default value is []
, which means that you are not using the
decoder. You add a decoder to your model by changing the default value of
LatentDim
. This decoder network, by default, contains two layers
of size 64 with tanh
as the activation function.
To change the default decoder network configuration, use createMLPNetwork
. For
example:
nss.Decoder = createMLPNetwork(nss,"decoder",... LayerSizes=[4 4],... Activations="sigmoid")
You can also directly assign a custom dlnetwork
object as the
decoder function network. For
example:
nss.Decoder = dlnet;
dlnet
is a custom dlnetwork
object with one input
representing the latent state and one output representing the original state.
For more information on autoencoders, see What are Neural StateSpace Models?
LatentDim
— Dimension of internal state
NaN
(default)  finite positive integer
Dimension of the internal (latent) state, specified as NaN
or a
positive integer. To add an encoder or decoder to your model, specify
LatentDim
as a positive integer.
LatentDim Value  Model Framework 

NaN 

A finite positive scalar 

Example: 2
IsTimeInvariant
— Flag indicating time invariance
true
(default)  false
Flag indicating time invariance, returned as one of the following:
true
— (default), the system is time invariant, neither the state function F of the output function H depend explicitly on time.false
— the system is time varying, both the state of the output function depend explicitly on time.
This property is readonly and cannot be set using dot notation. You can only
specify this properly when you create nss
. To do so, use the
corresponding namevalue pair argument in idNeuralStateSpace
. For
example:
nss = idNeuralStateSpace(3,NumInputs=2,IsTimeInvariant=false)
FeedthroughInOutputNetwork
— Flag indicating direct feedthrough
false
(default)  true
 array of logical
Flag indicating direct feedthrough in the output networks, returned as
false
or as an array logical values.
If NumOutputs
= nx
,
FeedthroughInOutputNetwork
is false
, because
the only output is the measured state, and there is no contribution from any
input.
If NumOutputs
> nx
,
FeedthroughInOutputNetwork
is a 1by2 logical array in which the
elements are as follows.
The first logical value corresponds to y_{1} and is always false.
The second value corresponds to y_{2} and is the same value that you specify with the namevalue pair argument
HasFeedThrough
when you create the object. When this value is true, then y_{2} is an explicit function of the input, otherwise, as default, there is no explicit contribution from the input to y_{2}.
Note
This property is readonly and you can change it only when you create
nss
, using the HasFeedThrough
argument in
idNeuralStateSpace
.
Example: [false, false]
StateName
— State names
{'x1','x2',...}
(default)  character vector  cell array of character vectors
State names, specified as one of these values:
Character vector — For firstorder models
Cell array of character vectors — For models with two or more states
''
— For unnamed states
You can specify StateName
using a string, such as
"velocity"
, but the state name is stored as a character vector,
'velocity'
.
Example:
{'velocity','distance'}
StateUnit
— State units
{''}
(default)  character vector  cell array of character vectors or stings  string  string array
State units, specified as:
A character vector or string — For firstorder models
A cell array of character vectors or string array — For models with two or more states
''
— For states without specified units
Use StateUnit
to keep track of the units each state is expressed in. StateUnit
has no effect on system behavior.
If you specify StateUnit
using a string, such as
"mph"
, the state units are stored as a character
vector, 'mph'
.
Example: 'mph'
Example: {'rpm','rad/s'}
TimeVariable
— Independent variable name
"t"
(default)  string  char vector
Independent variable name, specified as a string or character vector, for the state, input and output functions.
Example: "t"
NoiseVariance
— Innovation covariance matrix
matrix
Innovation covariance matrix, specified as an
NumOutputs
byNumOutputs
positive
semidefinite matrix. Typically this property is automatically set by the estimation
algorithm.
Example: 1e3*eye(2)
InputName
— Names of input channels
{''}
(default)  character vector  cell array of character vectors  string  string array
Names of input channels, specified as:
A character vector or string — For singleinput models
A cell array of character vectors or a string array — For models with two or more inputs
''
— For inputs without specified names
You can use automatic vector expansion to assign input names for multiinput models. For
example, if sys
is a twoinput model, you can specify
InputName
as follows.
sys.InputName = 'controls';
The input names automatically expand to {'controls(1)';'controls(2)'}
.
You can use the shorthand notation u
to refer to the InputName
property. For example, sys.u
is equivalent to sys.InputName
.
Input channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
If you specify InputName
using a string or string array, such as
"voltage"
, the input name is stored as a character vector,
'voltage'
.
When you estimate a model using an iddata
object, data
, the software automatically sets InputName
to data.InputName
.
InputUnit
— Units of input signals
{''}
(default)  character vector  cell array of character vectors  string  string array
Units of input signals, specified as:
A character vector or string — For singleinput models
A cell array of character vectors or string array — For models with two or more inputs
''
— For inputs without specified units
Use InputUnit
to keep track of the units each input signal is expressed in. InputUnit
has no effect on system behavior.
If you specify InputUnit
using a string, such as
"voltage"
, the input units are
stored as a character vector,
'voltage'
.
Example: 'voltage'
Example: {'voltage','rpm'}
InputGroup
— Input channel groups
structure with no fields (default)  structure
Input channel groups, specified as a structure where the fields are the group names and the values are the indices of the input channels belonging to the corresponding group. When you use InputGroup
to assign the input channels of MIMO systems to groups, you can refer to each group by name when you need to access it. For example, suppose you have a fiveinput model sys
, where the first three inputs are control inputs and the remaining two inputs represent noise. Assign the control and noise inputs of sys
to separate groups.
sys.InputGroup.controls = [1:3]; sys.InputGroup.noise = [4 5];
Use the group name to extract the subsystem from the control inputs to all outputs.
sys(:,'controls')
Example: struct('controls',[1:3],'noise',[4 5])
OutputName
— Names of output channels
{''}
(default)  character vector  cell array of character vectors or strings  string  string array
Names of output channels, specified as:
A character vector or string— For singleoutput models
A cell array of character vectors or string array — For models with two or more outputs
''
— For outputs without specified names
You can use automatic vector expansion to assign output names for multioutput models. For
example, if sys
is a twooutput model, you can specify
OutputName
as follows.
sys.OutputName = 'measurements';
The output names automatically expand to {'measurements(1)';'measurements(2)'}
.
You can use the shorthand notation y
to refer to the OutputName
property. For example, sys.y
is equivalent to sys.OutputName
.
Output channel names have several uses, including:
Identifying channels on model display and plots
Extracting subsystems of MIMO systems
Specifying connection points when interconnecting models
If you specify OutputName
using a string, such as
"rpm"
, the output name is
stored as a character vector,
'rpm'
.
When you estimate a model using an iddata
object, data
, the software automatically sets OutputName
to data.OutputName
.
OutputUnit
— Units of output signals
{''}
(default)  character vector  cell array of character vectors  string  string array
Units of output signals, specified as:
A character vector or string — For singleoutput models
A cell array of character vectors or string array — For models with two or more outputs
''
— For outputs without specified units
Use OutputUnit
to keep track of the units each output signal is expressed in. OutputUnit
has no effect on system behavior.
If you specify OutputUnit
using a string, such as
"voltage"
, the output units are stored as a character vector,
'voltage'
.
Example: 'voltage'
Example: {'voltage','rpm'}
OutputGroup
— Output channel groups
structure with no fields (default)  structure
Output channel groups, specified as a structure where the fields are the group names and the values are the indices of the output channels belonging to the corresponding group. When you use OutputGroup
to assign the output channels of MIMO systems to groups, you can refer to each group by name when you need to access it. For example, suppose you have a fouroutput model sys
, where the second output is a temperature, and the rest are state measurements. Assign these outputs to separate groups.
sys.OutputGroup.temperature = [2]; sys.OutputGroup.measurements = [1 3 4];
Use the group name to extract the subsystem from all inputs to the measurement outputs.
sys('measurements',:)
Example: struct('temperature',[2],'measurement',[1 3 4])
Notes
— Text notes about model
[0×1 string]
(default)  string  character vector  cell array of character vectors or strings  string array
Text notes about the model, specified as a string or character vector. The property stores
whichever of these two data types you provide. For instance, suppose that
sys1
and sys2
are dynamic system models. You
can set their Notes
properties to a string and a character vector,
respectively.
sys1.Notes = "sys1 has a string."; sys2.Notes = 'sys2 has a character vector.'; sys1.Notes sys2.Notes
ans = "sys1 has a string." ans = 'sys2 has a character vector.'
You can also specify Notes
as string array or a cell array of
character vectors or strings.
UserData
— Data associated with model
[]
(default)  any data type
Data of any kind that you want to associate and store with the model, specified as any MATLAB^{®} data type.
Ts
— Sample time
nonnegative scalar
Sample time, specified as a nonnegative scalar, in units specified by the
TimeUnit
property. For a continuous time model,
Ts
is equal to 0 (default). Changing the value of Ts has no impact
on the system data and does not discretize or resample the model.
Note
If you change Ts
to a different value after networks are
trained, you need to train the networks again because the original trained networks
are no longer valid.
Example: 0.1
TimeUnit
— Model time units
'seconds'
(default)  'minutes'
 'milliseconds'
 ...
Model time units, specified as:
'nanoseconds'
'microseconds'
'milliseconds'
'seconds'
'minutes'
'hours'
'days'
'weeks'
'months'
'years'
If you specify TimeUnit
using a string, such as
"hours"
, the time units are stored as a character vector,
'hours'
.
Model properties such as sample time Ts
,
InputDelay
, OutputDelay
, and other time
delays are expressed in the units specified by TimeUnit
. Changing
this property has no effect on other properties, and therefore changes the overall
system behavior. Use chgTimeUnit
to
convert between time units without modifying system behavior.
Report
— Summary report
report field values
This property is readonly.
Summary report that contains information about the estimation options and results
for a statespace model obtained using estimation commands. Use
Report
to find estimation information for the identified model,
including the:
Status (estimated or constructed)
Estimation method
Estimation options
Search termination conditions
Estimation data fit and other quality metrics
For more information on this property and how to use it, see the Output Arguments section of the corresponding estimation command reference page and Estimation Report.
Object Functions
createMLPNetwork  Create and initialize a MultiLayer Perceptron (MLP) network to be used within a neural statespace system 
setNetwork  Assign dlnetwork object as the state or output function of a
neural statespace model 
generateMATLABFunction  Generate MATLAB functions that evaluate the state and output functions, and their Jacobians, of a nonlinear greybox or neural statespace model 
sim  Simulate response of identified model 
idNeuralStateSpace/evaluate  Evaluate a neural statespace system for a given set of state and input values and return state derivative (or next state) and output values 
idNeuralStateSpace/linearize  Linearize a neural statespace model around an operating point 
Examples
Create ContinuousTime Neural StateSpace Object
Use idNeuralStateSpace
to create a continuoustime neural statespace object with two states, no inputs, and outputs identical to states.
nss = idNeuralStateSpace(2)
nss = Continuoustime Neural ODE in 2 variables dx/dt = f(x(t)) y(t) = x(t) + e(t) f(.) network: Deep network with 2 fully connected, hidden layers Activation function: tanh Variables: x1, x2 Status: Created by direct construction or transformation. Not estimated.
Use dot notation to access the object properties.
nss.StateNetwork
ans = dlnetwork with properties: Layers: [6x1 nnet.cnn.layer.Layer] Connections: [5x2 table] Learnables: [6x3 table] State: [0x3 table] InputNames: {'x'} OutputNames: {'dxdt'} Initialized: 1 View summary with summary.
nss.Name = "myNssObject"; nss.UserData = ['Created on ' char(datetime)]
nss = Continuoustime Neural ODE in 2 variables dx/dt = f(x(t)) y(t) = x(t) + e(t) f(.) network: Deep network with 2 fully connected, hidden layers Activation function: tanh Variables: x1, x2 Status: Created by direct construction or transformation. Not estimated.
You can now reconfigure the state network using createMLPNetwork
, if needed, and then use timedomain data to perform estimation and validation.
Create DiscreteTime Neural StateSpace Object
Use idNeuralStateSpace
to create a discretetime neural statespace object with three states, two inputs, four outputs, and sample time 0.1
.
nss = idNeuralStateSpace(3,NumInputs=2,NumOutputs=4,Ts=0.1)
nss = Discretetime Neural StateSpace Model with 4 outputs, 3 states, and 2 inputs x(t+1) = f(x(t),u(t)) y_1(t) = x(t) + e_1(t) y_2(t) = g(x(t),u(t)) + e_2(t) y(t) = [y_1(t); y_2(t)] f(.) network: Deep network with 2 fully connected, hidden layers Activation function: tanh g(.) network: Deep network with 2 fully connected, hidden layers Activation function: tanh Inputs: u1, u2 Outputs: y1, y2, y3, y4 States: x1, x2, x3 Sample time: 0.1 seconds Status: Created by direct construction or transformation. Not estimated.
Use dot notation to access the object properties.
nss.OutputNetwork.Layers
ans = 5x1 Layer array with layers: 1 'x[k]' Feature Input 3 features 2 'u[k]' Feature Input 2 features 3 'yx' Function @(x)x(:) 4 'yu' Function @(u)zeros(nx,nu)*u(:) 5 'y[k]' Addition Elementwise addition of 2 inputs
ans = 9x1 Layer array with layers: 1 'x[k]' Feature Input 3 features 2 'fc1' Fully Connected 64 fully connected layer 3 'act1' Tanh Hyperbolic tangent 4 'fc2' Fully Connected 64 fully connected layer 5 'act2' Tanh Hyperbolic tangent 6 'yx' Fully Connected 1 fully connected layer 7 'u[k]' Feature Input 2 features 8 'yu' Function @(u)zeros(ny,nu)*u 9 'y[k]' Addition Elementwise addition of 2 inputs
nss.UserData = ['Created on ' char(datetime)];
nss.UserData
ans = 'Created on 20Jul2024 13:09:43'
Note that by default the output does not explicitly depend on the input.
nss.FeedthroughInOutputNetwork
ans = 1x2 logical array
0 0
You can now reconfigure the state and output networks using createMLPNetwork
, if needed, and then use timedomain data to perform estimation and validation.
References
[1] Chen, Ricky T. Q., Yulia Rubanova, Jesse Bettencourt, and David Duvenaud. “Neural Ordinary Differential Equations.” arXiv, December 13, 2019. http://arxiv.org/abs/1806.07366.
Version History
Introduced in R2022b
See Also
Objects
Functions
createMLPNetwork
setNetwork
nssTrainingOptions
nlssest
generateMATLABFunction
idNeuralStateSpace/evaluate
idNeuralStateSpace/linearize
sim
Blocks
Live Editor Tasks
Topics
 What are Neural StateSpace Models?
 Estimate Neural StateSpace System
 Estimate Nonlinear Autonomous Neural StateSpace System
 Neural StateSpace Model of Simple Pendulum System
 Reduced Order Modeling of a Nonlinear Dynamical System using Neural StateSpace Model with Autoencoder
 Augment Known Linear Model with Flexible Nonlinear Functions
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)