Documentation

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.

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

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

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

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

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

`x0` — Initial state values
column vector of zeros (default) | vector

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

`sys0` — Dynamic system
dynamic system model

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

`A,B,C,D` — Values of state-space matrices
matrices

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 N_y outputs, N_u inputs, and N_x states, the state-space matrices have the following dimensions:

A — N_x-by-N_x matrix
B — N_x-by-N_u matrix
C — N_y-by-N_x matrix
D — N_y-by-N_u 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.

`K` — Value of state disturbance matrix
zero matrix (default) | matrix

Value of the state disturbance matrix K, specified as an N_x-by-N_y matrix, where N_x is the number of states and N_y 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.

`StateName` — State names
`''` (default) | character vector | cell array

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

`StateUnit` — State units
`''` (default) | character vector | cell array

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

`Structure` — Information about estimable parameters
structure property values

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.

Field	Description	Examples
Value	Parameter 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`.
Minimum	Minimum 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.
Maximum	Maximum value that the parameter can assume during estimation
Free	Boolean 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.
Scale	Scale of the value of the parameter. The estimation algorithm does not use `Scale`.
Info	Structure 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.

`NoiseVariance` — Variance of model innovations
scalar | matrix

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

SISO model — Scalar
MIMO model with N_y outputs — N_y-by-N_y 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.

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

`InputDelay` — Input delay for each input channel
`0` (default) | scalar | vector

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 N_u inputs, set InputDelay to an N_u-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.

`OutputDelay` — Output delay for each output channel
`0` (default)

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

`Ts` — Sample Time
`-1` (default) | `0` | positive scalar

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.

`TimeUnit` — Units for time variable
`'seconds'` (default) | `'nanoseconds'` | `'microseconds'` | `'milliseconds'` | `'minutes'` | `'hours'` | `'days'` | `'weeks'` | `'months'` | `'years'`

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

`InputName` — Input channel names
`''` (default) | character vector | cell array

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

`InputUnit` — Input channel units
`''` (default) | character vector | cell array

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.

`InputGroup` — Input channel groups
`struct` with no fields (default) | `struct`

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

`OutputName` — Output channel names
`''` (default) | character vector | cell array

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

`OutputUnit` — Output channel units
`''` (default) | character vector | cell array

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.

`OutputGroup` — Output channel groups
`struct` with no fields (default) | `struct`

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 = [1];
sys.OutputGroup.measurement = [3 5];

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

sys('measurement',:)

`Name` — System Name
`''` (default) | character vector

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

`Notes` — Notes on system
`0`-by-`1` string (default) | string | character vector

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

`UserData` — Data to associate with system
`[]` (default) | any MATLAB^® data type

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

`SamplingGrid` — Sampling grid
`[]` (default) | `struct`

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.

Functions that operate and return idss model objects enable you to transform and manipulate idss models. For instance:
- Use canon to transform an idss model into canonical form
- Use merge to merge estimated idss models.
- Use c2d to convert an idss from continuous to discrete time. Use d2c to convert an idss from discrete to continuous time.
Functions that perform analytical and simulation functions on idss objects, such as bode and sim
Functions that retrieve or interpret model information, such as advice and getpar
Functions that convert idss objects into a different model type, such as idpoly or idtf for time domain or idfrd for continuous domain

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

Transformation and Manipulation

`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 initial parameter values of `idnlgrey` model object
`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

Analysis and Simulation

`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

Information Extraction and Interpretation

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

Conversion to Other Model Structures

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

Examples

collapse all

Create State-Space Model with Identifiable Parameters

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.

Specify Additional Attributes of State-Space Model

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 Identifiable Parameters of State-Space Model

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.

Convert Transfer Function into State-Space Model

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 (s) = \frac{s + 4}{s^{2} + 20 s + 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.

Array of State-Space Models