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

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

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

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

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

Array of State-Space Models

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.