# idss

State-space model with identifiable parameters

## Description

Use `idss` to create a continuous-time or discrete-time state-space model with identifiable (estimable) coefficients, or to convert Dynamic System Models to state-space form.

A state-space model of a system with input vector u, output vector y, and disturbance e takes the following form in continuous time:

`$\begin{array}{c}\frac{dx\left(t\right)}{dt}=Ax\left(t\right)+Bu\left(t\right)+Ke\left(t\right)\\ y\left(t\right)=Cx\left(t\right)+Du\left(t\right)+e\left(t\right)\end{array}$`

In discrete time, the state-space model takes the following form:

`$\begin{array}{c}x\left[k+1\right]=Ax\left[k\right]+Bu\left[k\right]+Ke\left[k\right]\\ y\left[k\right]=Cx\left[k\right]+Du\left[k\right]+e\left[k\right]\end{array}$`

For `idss` models, the elements of the state-space matrices A, B, C, and D can be estimable parameters. The elements of the state disturbance K can also be estimable parameters. The `idss` model stores the values of these matrix elements in the `A`, `B`, `C`, `D`, and `K` properties of the model.

## Creation

You can obtain an `idss` model object in one of three ways.

• Estimate the `idss` model based on the input-output measurements of a system by using `n4sid` or `ssest`. These estimation commands estimate the values of the estimable elements of the state-space matrices. The estimated values are stored in the `A`, `B`, `C`, `D`, and `K` properties of the resulting `idss` model. The `Report` property of the resulting model stores information about the estimation, such as on the handling of initial state values and the options used in estimation. For example:

```sys = ssest(data,nx); A = sys.A; B = sys.B; sys.Report```

For more examples of estimating an `idss` model, see `ssest` or `n4sid`.

• Create an `idss` model using the `idss` command. For example:

`sys = idss(A,B,C,D)`
You can create an `idss` model to configure an initial parameterization for estimation of a state-space model to fit measured response data. When you do so, you can specify constraints on one or more of the state-space matrix elements. For instance, you can fix the values of some elements, or specify minimum or maximum values for the free elements. You can then use the configured model as an input argument to an estimation command (`ssest` or `n4sid`) to estimate parameter values with those constraints. For examples, see Create State-Space Model with Identifiable Parameters and Configure Identifiable Parameters of State-Space Model.

• Convert an existing dynamic system model to an `idss` model using the `idss` command. For example:

`sys_ss = idss(sys_tf);`

For information on functions you can use to extract information from or transform `idss` model objects, see Object Functions.

### Syntax

``sys = idss(A,B,C,D)``
``sys = idss(A,B,C,D,K)``
``sys = idss(A,B,C,D,K,x0)``
``sys = idss(A,B,C,D,K,x0,Ts)``
``sys = idss(___,Name,Value)``
``sys = idss(sys0)``
``sys = idss(sys0,'split')``

### Description

#### Create State-Space Model

example

````sys = idss(A,B,C,D)` creates a state-space model with specified state-space matrices `A,B,C,D`. By default, `sys` is a discrete-time model with an unspecified sample time and no state disturbance element. Use this syntax especially when you want to configure an initial parameterization as an input to a state-space estimation function such as `n4sid` or `ssest`.```

example

````sys = idss(A,B,C,D,K)` specifies a disturbance matrix `K`.```

example

````sys = idss(A,B,C,D,K,x0)` initializes the state values with the vector `x0`.```

example

````sys = idss(A,B,C,D,K,x0,Ts)` specifies the sample time property `Ts`. Use `Ts = 0` to create a continuous-time model.```

example

````sys = idss(___,Name,Value)` sets additional properties using one or more name-value pair arguments. Specify name-value pair arguments after any of the input argument combinations in the previous syntaxes.```

#### Convert Dynamic System Model to State-Space Model

example

````sys = idss(sys0)` converts any dynamic system model `sys0` to `idss` model form.```
````sys = idss(sys0,'split')` converts `sys0` to `idss` model form, and treats the last Ny input channels of `sys0` as noise channels in the returned model. `sys0` must be a numeric (nonidentified) `tf` (Control System Toolbox), `zpk` (Control System Toolbox), or `ss` (Control System Toolbox) model object. Also, `sys0` must have at least as many inputs as outputs. ```

### Input Arguments

expand all

Initial state values, specified as a column vector of Nx values.

Dynamic system, specified as a dynamic system model to convert to an `idss` model.

• When `sys0` is an identified model, its estimated parameter covariance is lost during conversion. If you want to translate the estimated parameter covariance during the conversion, use `translatecov`.

• When `sys0` is a numeric (nonidentified) model, the state-space data of `sys0` defines the `A`, `B`, `C`, and `D` matrices of the converted model. The disturbance matrix `K` is fixed to zero. The `NoiseVariance` value defaults to `eye(Ny)`, where `Ny` is the number of outputs of `sys`.

For the syntax `sys = idss(sys0,'split')`, `sys0` must be a numeric (nonidentified) `tf` (Control System Toolbox), `zpk` (Control System Toolbox), or `ss` (Control System Toolbox) model object. Also, `sys0` must have at least as many inputs as outputs. Finally, the subsystem `sys0(:,Ny+1:Ny+Nu)` must contain a nonzero feedthrough term (the subsystem must be biproper).

## Properties

expand all

Values of the state-space matrices, specified as matrices that correspond to each of the A, B, C, and D matrices.

For a system with Ny outputs, Nu inputs, and Nx states, the state-space matrices have the following dimensions:

• `A`Nx-by-Nx matrix

• `B`Nx-by-Nu matrix

• `C`Ny-by-Nx matrix

• `D`Ny-by-Nu matrix

If you obtain an `idss` model `sys` by identification using `ssest` or `n4sid`, then `sys.A`, `sys.B`, `sys.C`, and `sys.D` contain the estimated values of the matrix elements.

If you create an `idss` model `sys` using the `idss` command, `sys.A`, `sys.B`, `sys.C`, and `sys.D` contain the initial values of the state-space matrices that you specify with the `A,B,C,D` input arguments.

For an `idss` model `sys`, each property `sys.A`, `sys.B`, `sys.C`, and `sys.D` is an alias of the corresponding `Value` entry in the `Structure` property of `sys`. For example, `sys.A` is an alias of the value of the property `sys.Structure.A.Value`.

Value of the state disturbance matrix K, specified as an Nx-by-Ny matrix, where Nx is the number of states and Ny is the number of outputs.

If you obtain an `idss` model `sys` by identification using `ssest` or `n4sid`, then `sys.K` contains the estimated values of the matrix elements.

If you create an `idss` model `sys` using the `idss` command, `sys.K` contains the initial values of the state-space matrices that you specify with the `K` input argument.

For an `idss` model `sys`, `sys.K` is an alias to the value of the property `sys.Structure.K.Value`.

State names, specified as a character vector or cell array.

• First-order model — Character vector

• Model with two or more states — Cell array of character vectors

• Unnamed states — `''`

Example: `'velocity'` names the only state in a first-order model

State units, specified as a character vector or cell array.

• First-order model — Character vector

• Model with two or more states — Cell array of character vectors

• States without specified units — `''`

Use `StateUnit` to keep track of the units each state is expressed in. `StateUnit` has no effect on system behavior.

Example: `'rad'` corresponds to the units of the only state in a first-order model

Information about the estimable parameters of the `idss` model, specified as property-specific values. `Structure.A`, `Structure.B`, `Structure.C`, `Structure.D`, and `Structure.K` contain information about the A, B, C, D, and K matrices, respectively. Each parameter in `Structure` contains the following fields.

FieldDescriptionExamples
ValueParameter Values — Each property `sys.A`, `sys.B`, `sys.C`, and `sys.D` is an alias of the corresponding `Value` entry in the `Structure` property of `sys`.`NaN` represents unknown parameter values.`sys.Structure.A.Value` contains the initial or estimated values of the A matrix.`sys.A` is an alias of the value of the property `sys.Structure.A.Value`.
MinimumMinimum value that the parameter can assume during estimation`sys.Structure.K.Minimum = 0` constrains all entries in the K matrix to be greater than or equal to zero.
MaximumMaximum value that the parameter can assume during estimation
FreeBoolean specifying whether the parameter is a free estimation variable. If you want to fix the value of a parameter during estimation, set the corresponding `Free = false`.If A is a 3-by-3 matrix, ```sys.Structure.A.Free = eyes(3)``` fixes all of the off-diagonal entries in A to the values specified in `sys.Structure.A.Value`. In this case, only the diagonal entries in A are estimable.
ScaleScale of the value of the parameter. The estimation algorithm does not use `Scale`.
InfoStructure array that contains the fields `Label` and `Unit` for storing parameter labels and units. Specify parameter labels and units as character vectors.`'Time'`

For an example of configuring model parameters using the `Structure` property, see Configure Identifiable Parameters of State-Space Model.

Variance (covariance matrix) of the model innovations e, specified as a scalar or matrix.

• SISO model — Scalar

• MIMO model with Ny outputs — Ny-by-Ny matrix

An identified model includes a white Gaussian noise component e(t). `NoiseVariance` is the variance of this noise component. Typically, the model estimation function (such as `ssest`) determines this variance.

Summary report that contains information about the estimation options and results for a state-space model obtained using estimation commands, such as `ssest`, `ssregest`, and `n4sid`. Use `Report` to find estimation information for the identified model, including the:

• Estimation method

• Estimation options

• Search termination conditions

• Estimation data fit and other quality metrics

If you create the model by construction, the contents of `Report` are irrelevant.

```A = [-0.1 0.4; -0.4 -0.1]; B = [1; 0]; C = [1 0]; D = 0; m = idss(A,B,C,D); sys.Report.OptionsUsed```
```ans = []```

If you obtain the using estimation commands, the fields of `Report` contain information on the estimation data, options, and results.

```load iddata2 z2; m = ssest(z2,3); m.Report.OptionsUsed```
```InitialState: 'auto' N4Weight: 'auto' N4Horizon: 'auto' Focus: 'prediction' EstimateCovariance: 1 Display: 'off' InputOffset: [] OutputOffset: [] OutputWeight: [] SearchMethod: 'auto' SearchOptions: [1x1 idoptions.search.identsolver] Regularization: [1x1 struct] Advanced: [1x1 struct]```

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.

Input delay for each input channel, specified as a scalar value or numeric vector. For continuous-time systems, specify input delays in the time unit stored in the `TimeUnit` property. For discrete-time systems, specify input delays in integer multiples of the sample time `Ts`. For example, setting `InputDelay` to `3` specifies a delay of three sample times.

For a system with Nu inputs, set `InputDelay` to an Nu-by-1 vector. Each entry of this vector is a numerical value that represents the input delay for the corresponding input channel.

You can also set `InputDelay` to a scalar value to apply the same delay to all channels.

For identified systems such as `idss`, `OutputDelay` is fixed to zero.

Sample time, specified as one of the following.

• Continuous-time model — `0`

• Discrete-time model with a specified sampling time — a positive scalar representing the sampling period expressed in the unit specified by the `TimeUnit` property of the model

• Discrete-time model with unspecified sample time — `-1`

Changing this property does not discretize or resample the model. Use `c2d` and `d2c` to convert between continuous- and discrete-time representations. Use `d2d` to change the sample time of a discrete-time system.

Units for the time variable, the sample time `Ts`, and any time delays in the model, specified as a scalar.

Changing this property does not resample or convert the data. Modifying the property changes only the interpretation of the existing data. Use `chgTimeUnit` (Control System Toolbox) to convert data to different time units

Input channel names, specified as a character vector or cell array.

• Single-input model — Character vector. For example, `'controls'`.

• Multi-input model — Cell array of character vectors.

Alternatively, 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)'}`.

When you estimate a model using an `iddata` object `data`, the software automatically sets `InputName` to `data.InputName`.

You can use the shorthand notation `u` to refer to the `InputName` property. For example, `sys.u` is equivalent to `sys.InputName`.

You can use input channel names in several ways, including:

• To identify channels on model display and plots

• To extract subsystems of MIMO systems

• To specify connection points when interconnecting models

Input channel units, specified as a character vector or cell array:

• Single-input model — Character vector

• Multi-input Model — Cell array of character vectors

Use `InputUnit` to keep track of input signal units. `InputUnit` has no effect on system behavior.

Input channel groups, specified as a structure. The `InputGroup` property lets you divide the input channels of MIMO systems into groups so that you can refer to each group by name. In the `InputGroup` structure, set field names to the group names, and field values to the input channels belonging to each group.

For example, create input groups named `controls` and `noise` that include input channels 1, 2 and 3, 5, respectively.

```sys.InputGroup.controls = [1 2]; sys.InputGroup.noise = [3 5];```

You can then extract the subsystem from the `controls` inputs to all outputs using the following syntax:

`sys(:,'controls')`

Output channel names, specified as a character vector or cell array.

• Single-input model — Character vector. For example, `'measurements'`.

• Multi-input model — Cell array of character vectors.

Alternatively, 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)'}`.

When you estimate a model using an `iddata` object, `data`, the software automatically sets `OutputName` to `data.OutputName`.

You can use the shorthand notation `y` to refer to the `OutputName` property. For example, `sys.y` is equivalent to `sys.OutputName`.

You can use output channel names in several ways, including:

• To identify channels on model display and plots

• To extract subsystems of MIMO systems

• To specify connection points when interconnecting models

Output channel units, specified as a character vector or cell array.

• Single-input model — Character vector. For example, `'seconds'`.

• Multi-input Model — Cell array of character vectors.

Use `OutputUnit` to keep track of output signal units. `OutputUnit` has no effect on system behavior.

Output channel groups, specified as a structure. The `OutputGroup` property lets you divide the output channels of MIMO systems into groups and refer to each group by name. In the `OutputGroup` structure, set field names to the group names, and field values to the output channels belonging to each group.

For example, create output groups named `temperature` and `measurement` that include output channels 1, and 3, 5, respectively.

```sys.OutputGroup.temperature = ; sys.OutputGroup.measurement = [3 5];```

You can then extract the subsystem from all inputs to the `measurement` outputs using the following syntax:

`sys('measurement',:)`

System name, specified as a character vector. For example, `'system_1'`.

Any text that you want to associate with the system, specified as a string or a cell array of character vectors. The property stores whichever data type you provide. For instance, if `sys1` and `sys2` are dynamic system models, you can set their `Notes` properties as follows.

```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.' ```

Data to associate with the system, specified as any MATLAB data type.

Sampling grid for model arrays, specified as a structure.

For arrays of identified linear (IDLTI) models that you derive by sampling one or more independent variables, this property tracks the variable values associated with each model. This information appears when you display or plot the model array. Use this information to trace results back to the independent variables.

Set the field names of the data structure to the names of the sampling variables. Set the field values to the sampled variable values associated with each model in the array. All sampling variables must be numeric and scalar valued, and all arrays of sampled values must match the dimensions of the model array.

For example, suppose that you collect data at various operating points of a system. You can identify a model for each operating point separately and then stack the results together into a single system array. You can tag the individual models in the array with information regarding the operating point.

```nominal_engine_rpm = [1000 5000 10000]; sys.SamplingGrid = struct('rpm', nominal_engine_rpm)```

Here, `sys` is an array containing three identified models obtained at 1000, 5000, and 10000 rpm, respectively.

For model arrays that you generate by linearizing a Simulink® model at multiple parameter values or operating points, the software populates `SamplingGrid` automatically with the variable values that correspond to each entry in the array.

## Object Functions

In general, any function applicable to Dynamic System Models is applicable to an `idss` model object. These functions are of four general types.

The following lists contain a representative subset of the functions that you can use with `idss` models.

expand all

 `canon` Canonical state-space realization `ss2ss` State coordinate transformation for state-space model `balred` Model order reduction `translatecov` Translate parameter covariance across model transformation operations `setpar` Set attributes such as values and bounds of linear model parameters `chgTimeUnit` Change time units of dynamic system `d2d` Resample discrete-time model `d2c` Convert model from discrete to continuous time `c2d` Convert model from continuous to discrete time `merge` Merge estimated models

expand all

 `sim` Simulate response of identified model `predict` Predict state and state estimation error covariance at next time step using extended or unscented Kalman filter, or particle filter `compare` Compare identified model output and measured output `impulse` Impulse response plot of dynamic system; impulse response data `step` Step response plot of dynamic system; step response data `bode` Bode plot of frequency response, or magnitude and phase data `data2state` Map past data to states of state-space and nonlinear ARX models `findstates` Estimate initial states of model

expand all

 `idssdata` State-space data of identified system `get` Access model property values `getpar` Obtain attributes such as values and bounds of linear model parameters `getcov` Parameter covariance of identified model `advice` Analysis and recommendations for data or estimated linear models

expand all

 `idpoly` Polynomial model with identifiable parameters `idtf` Transfer function model with identifiable parameters `idfrd` Frequency response data or model

## Examples

collapse all

Create a 4th-order SISO state-space model with identifiable parameters. Initialize the initial state values to 0.1 for all entries. Set the sample time to 0.1 s.

```A = blkdiag([-0.1 0.4; -0.4 -0.1],[-1 5; -5 -1]); B = [1; zeros(3,1)]; C = [1 0 1 0]; D = 0; K = zeros(4,1); x0 = [0.1,0.1,0.1,0.1]; Ts = 0.1; sys = idss(A,B,C,D,K,x0,Ts);```

`sys` is a 4th-order SISO `idss` model. The number of states and input-output dimensions are determined by the dimensions of the state-space matrices. By default, all entries in the matrices `A`, `B`, `C`, `D`, and `K` are identifiable parameters.

You can use `sys` to specify an initial parameterization for state-space model estimation with `ssest` or `n4sid`.

Create a 4th-order SISO state-space model with identifiable parameters. Name the input and output channels of the model, and specify minutes as the model time unit.

You can use name-value pair arguments to specify additional model properties during model creation.

```A = blkdiag([-0.1 0.4; -0.4 -0.1],[-1 5; -5 -1]); B = [1; zeros(3,1)]; C = [1 0 1 0]; D = 0; sys = idss(A,B,C,D,'InputName','Drive','TimeUnit','minutes');```

To change or specify most attributes of an existing model, you can use dot notation. For example, change the output name.

`sys.OutputName = 'Torque';`

Configure an `idss` model so that it has no state disturbance element and only the nonzero entries of the `A` matrix are estimable. Additionally, fix the values of the `B` matrix.

You can configure individual parameters of an `idss` model to specify constraints for state-space model estimation with `ssest` or `n4sid`.

Create an `idss` model.

```A = blkdiag([-0.1 0.4; -0.4 -0.1],[-1 5; -5 -1]); B = [1; zeros(3,1)]; C = [1 0 1 0]; D = 0; K = zeros(4,1); x0 = [0.1,0.1,0.1,0.1]; sys = idss(A,B,C,D,K,x0,0);```

Setting all entries of `K` `to` `0` creates an `idss` model with no state disturbance element.

Use the `Structure` property of the model to fix the values of some of the parameters.

```sys.Structure.A.Free = (A~=0); sys.Structure.B.Free = false; sys.Structure.K.Free = false;```

The entries in `sys.Structure.A.Free` determine whether the corresponding entries in `sys.A` are free (identifiable) or fixed. The first line sets `sys.Structure.A.Free` to a logical matrix that is `true` wherever `A` is nonzero, and `false` everywhere else. This setting fixes the values of the zero entries in `sys.A`.

The remaining lines fix all the values in `sys.B` and `sys.K` to the values that you specified during model creation.

Model a dynamic system using a transfer function. Then use `idss` to convert the transfer-function model into state-space form.

Using `idtf`, construct a continuous-time, single-input, single-output (SISO) transfer function described by:

`$G\left(s\right)=\frac{s+4}{{s}^{2}+20s+5}$`

```num = [1 4]; den = [1 20 5]; G = idtf(num,den)```
```G = s + 4 -------------- s^2 + 20 s + 5 Continuous-time identified transfer function. Parameterization: Number of poles: 2 Number of zeros: 1 Number of free coefficients: 4 Use "tfdata", "getpvec", "getcov" for parameters and their uncertainties. Status: Created by direct construction or transformation. Not estimated. ```

Convert the transfer function into state-space form.

`sys0 = idss(G)`
```sys0 = Continuous-time identified state-space model: dx/dt = A x(t) + B u(t) + K e(t) y(t) = C x(t) + D u(t) + e(t) A = x1 x2 x1 -20 -2.5 x2 2 0 B = u1 x1 2 x2 0 C = x1 x2 y1 0.5 1 D = u1 y1 0 K = y1 x1 0 x2 0 Parameterization: FREE form (all coefficients in A, B, C free). Feedthrough: none Disturbance component: none Number of free coefficients: 8 Use "idssdata", "getpvec", "getcov" for parameters and their uncertainties. Status: Created by direct construction or transformation. Not estimated. ```

Create an array of state-space models.

You can create an array of state-space models in one of several ways:

• Direct array construction using $n$-dimensional state-space arrays

• Array-building by indexed assignment

• Array-building using the `stack` command

• Sampling an identified model using the `rsample` command

Create an array by providing $n$-dimensional arrays as an input argument to `idss`, instead of 2-dimensional matrices.

```A = rand(2,2,3,4); sysarr = idss(A,[2;1],[1 1],0);```

When you provide a multi-dimensional array to `idss` in place of one of the state-space matrices, the first two dimensions specify the numbers of states, inputs, or outputs of each model in the array. The remaining dimensions specify the dimensions of the array itself. `A` is a 2-by-2-by-3-by-4 array. Therefore, `sysarr` is a 3-by-4 array of `idss` models. Each model in `sysarr` has two states, specified by the first two dimensions of `A`. Further, each model in `sysarr` has the same `B`, `C`, and `D` values.

Create an array by indexed assignment.

```sysarr = idss(zeros(1,1,2)); sysarr(:,:,1) = idss([4 -3; -2 0],[2;1],[1 1],0); sysarr(:,:,2) = idss(rand(2),rand(2,1),rand(1,2),1);```

The first command preallocates the array. The first two dimensions of the array are the I/O dimensions of each model in the array. Therefore, `sysarr` is a 2-element vector of SISO models.

The remaining commands assign an `idss` model to each position in `sysarr`. Each model in an array must have the same I/O dimensions.

Add another model to `sysarr` using `stack`.

`stack` is an alternative to building an array by indexing.

`sysarr = stack(1,sysarr,idss([1 -2; -4 9],[0;-1],[1 1],0));`

This command adds another `idss` model along the first array dimension of `sysarr`. `sysarr` is now a 3-by-1 array of SISO `idss` models.

## Version History

Introduced in R2006a