# idNeuralStateSpace

Neural state-space model with identifiable network weights

## Description

Use `idNeuralStateSpace`

to create a black-box continuous-time or
discrete-time neural state-space model with identifiable (estimable) network weights and bias.
You can use the trained black-box model for control, estimation, optimization, and reduced
order modeling.

Continuous-time neural state space 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*are measurement noises in the data sets which are minimized by the network training algorithm.

_{2}For discrete-time state-space 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}$$

**Note**

Defining and estimating a neural state space system requires that:

You know what the states of the systems are (to your best knowledge).

The states are measured, and thus, their measurements are part of experiment data set.

## Creation

### Description

creates an autonomous (no-input) time-invariant continuous-time neural state-space
object with `nss`

= idNeuralStateSpace(`nx`

)`nx`

state variables and output identical to
state.

specifies name-value pair arguments after any of the input argument in the previous
syntax. You can use name-value 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 feed-through.`nss`

= idNeuralStateSpace(___,`Name=Value`

)

For example, ```
nss =
idNeuralStateSpace(3,NumInputs=2,NumOutputs=4,Ts=0.1)
```

creates a
time-invariant discrete-time neural state-space 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
feed-through (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

**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.

Use name-value 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*is an explicit function of the input, that is_{2}*y*(_{2}*t*) =*H*(*t*,*x*,*u*).`false`

— the nontrivial output measurement*y*is not an explicit function of the input, even if_{2}`NumInputs`

is greater than zero. This is the default case, and*y*(_{2}*t*) =*H*(*x*,*u*).

This argument sets the value of the read-only 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 state-space system (*F*). For
continuous state-space systems the state function returns the system state derivative
with respect to time, while for discrete-time state-space 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 multi-layer perceptron (MLP) network with the
following features:

Two hidden layers: each is a fully-connected layer with 128 nodes.

Two activation layers: each featuring an hyperbolic tangent (tanh) function.

One output layer: a fully-connected 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")

`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 weights and bias, use

`createMLPNetwork`

to create a new network.Multi-layer 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 2-by-1 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 state-space system, which is a function of time (if
`IsTimeInvariant`

is `false`

), the
current state, and the current input (if `NumInputs`

is
positive), in that order.

When you create an `idNeuralStateSpace`

model, the default
network created to approximate *H* is a multi-layer
perceptron (MLP) network with the following features:

Two hidden layers: each is a fully-connected layer with 128 nodes.

Two activation layers: each featuring an hyperbolic tangent (tanh) function.

One output layer: a fully-connected 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")

`nlssest`

. For
example:options1 = nssTrainingOptions('adam') options2 = nssTrainingOptions('sgdm') nss = nlssest(U, Y, nss, [options1; options2])

`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 read-only and cannot be set using dot notation. You can
only specify this properly when you create `nss`

. To do
so, use the corresponding name-value pair argument in
`idNeuralStateSpace`

. For
example:

nss = idNeuralStateSpace(3,NumInputs=2,IsTimeInvariant=false)

**Example: **`true`

`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 1-by-2 logical
array in which the elements are as follows.

The first logical value corresponds to

*y*and is always false._{1}The second value corresponds to

*y*and is the same value that you specify with the name-value pair argument_{2}`HasFeedThrough`

when you create the object. When this value is true, then*y*is an explicit function of the input, otherwise, as default, there is no explicit contribution from the input to_{2}*y*._{2}

**Note**

This property is read-only 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 first-order 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

State units, specified as one of these values:

Character vector — For first-order models

Cell array of character vectors — 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.

You can specify `StateUnit`

using a string, such as
`"mph"`

, but 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`

-by-`NumOutputs`

positive
semi-definite matrix. Typically this property is automatically set by the estimation
algorithm.

**Example: **`1e-3*eye(2)`

`InputName`

— Names of input channels

`{'u1','u2'}`

(default) | character vector | cell array of character vectors

Names of input channels, specified as one of these values:

Character vector — For single-input models

Cell array of character vectors — For models with two or more inputs

`''`

— For inputs without specified names

You can use automatic vector expansion to assign input names for
multi-input models. For example, if `sys`

is a two-input
model, enter:

`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

You can specify `InputName`

using a string, such as
`"voltage"`

, but 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`

.

**Example: **`{'ailerons','elevators','rudder'}`

`InputUnit`

— Units of input signals

`{''}`

(default) | character vector | cell array of character vectors

Units of input signals, specified as one of these values:

Character vector — For single-input models

Cell array of character vectors — 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.

You can specify `InputUnit`

using a string, such as
`"voltage"`

, but 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 five-input 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

`{'y1','y2'}`

(default) | character vector | cell array of character vectors

Names of output channels, specified as one of these values:

Character vector — For single-output models

Cell array of character vectors — For models with two or more outputs

`''`

— For outputs without specified names

You can use automatic vector expansion to assign output names for
multi-output models. For example, if `sys`

is a two-output
model, enter:

`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

You can specify `OutputName`

using a string, such as
`"rpm"`

, but 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

Units of output signals, specified as one of these values:

Character vector — For single-output models

Cell array of character vectors — 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.

You can specify `OutputUnit`

using a string, such as `"voltage"`

, but 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 four-output 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 | cell array of character vector

Text notes about the model, stored as a string or a cell array of character vectors. The property stores whichever of these two data types you provide. For instance, suppose that `sys1`

and `sys2`

are dynamic system models, and 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.'

`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 one of these values:

`'nanoseconds'`

`'microseconds'`

`'milliseconds'`

`'seconds'`

`'minutes'`

`'hours'`

`'days'`

`'weeks'`

`'months'`

`'years'`

You can specify `TimeUnit`

using a string, such as
`"hours"`

, but 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 read-only.

Summary report that contains information about the estimation options and results
for a state-space 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 Multi-Layer Perceptron (MPL) network to be used within a neural state-space system |

`generateMATLABFunction` | Generate MATLAB functions that evaluate the state and output functions of a neural state-space object, and their Jacobians |

`sim` | Simulate response of identified model |

`idNeuralStateSpace/evaluate` | Evaluate a neural state-space 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 state-space model around an operating point |

## Examples

### Create Continuous-Time Neural State-Space Object

Use `idNeuralStateSpace`

to create a continuous-time neural state-space object with two states, no inputs, and outputs identical to states.

nss = idNeuralStateSpace(2)

Use dot notation to access the object properties.

nss.StateNetwork

ans = dlnetwork with properties: Layers: [6×1 nnet.cnn.layer.Layer] Connections: [5×2 table] Learnables: [6×3 table] State: [0×3 table] InputNames: {'x'} OutputNames: {'dxdt'} Initialized: 1 View summary with summary.

nss.Name = "myNssObject"; nss.UserData = ['Created on ' char(datetime)]

You can now re-configure the state network using `createMLPNetwork`

, if needed, and then use time-domain data to perform estimation and validation.

### Create Discrete-Time Neural State-Space Object

Use `idNeuralStateSpace`

to create a discrete-time neural state-space object with three states, two inputs, four outputs, and sample time `0.1`

.

nss = idNeuralStateSpace(3,NumInputs=2,NumOutputs=4,Ts=0.1)

Use dot notation to access the object properties.

nss.OutputNetwork.Layers

ans = 5×1 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 Element-wise addition of 2 inputs

ans = 9×1 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 Element-wise addition of 2 inputs

```
nss.UserData = ['Created on ' char(datetime)];
nss.UserData
```

ans = 'Created on 14-Jul-2022 10:33:14'

Note that by default the output does not explicitly depend on the input.

nss.FeedthroughInOutputNetwork

`ans = `*1×2 logical array*
0 0

You can now re-configure the state and output networks using `createMLPNetwork`

, if needed, and then use time-domain data to perform estimation and validation.

## Version History

**Introduced in R2022b**

## See Also

### Objects

### Functions

`createMLPNetwork`

|`nssTrainingOptions`

|`nlssest`

|`generateMATLABFunction`

|`idNeuralStateSpace/evaluate`

|`idNeuralStateSpace/linearize`

|`sim`

### Blocks

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## 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)