idpoly

Polynomial model with identifiable parameters

Description

An idpoly model represents a system as a continuous-time or discrete-time polynomial model with identifiable (estimable) coefficients. Use idpoly to create a polynomial model or to convert Dynamic System Models to polynomial form.

A polynomial model of a system with input vector u, output vector y, and disturbance e takes the following form in discrete time:

$A (q) y (t) = \frac{B (q)}{F (q)} u (t) + \frac{C (q)}{D (q)} e (t)$

The variables A, B, C, D, and F are polynomials expressed with the time-shift operator q^-1. For instance, the A polynomial takes this form:

$A (q) = 1 + a_{1} q^{- 1} + a_{2} q^{- 2} + \dots + a_{n a} q^{- n a}$

Here, na is the order of the A polynomial. q^-1y(t) is equivalent to y(t-1).

For example, if A(q) = 1 + a₁q^-1 + a₂q^-2, then A(y(t)) = 1 + a₁(t-1) + a₂(t-2).

The C, D, and F polynomials take the same form as the A polynomial, starting with 1. The B polynomial does not start with 1.

In continuous time, a polynomial model takes the following form:

$A (s) Y (s) = \frac{B (s)}{F (s)} U (s) + \frac{C (s)}{D (s)} E (s)$

U(s) contains the Laplace transformed inputs to sys. Y(s) contains the Laplace transformed outputs. E(s) contains the Laplace transform of the disturbances for each output.

For idpoly models, the coefficients of the polynomials A, B, C, D, and F can be estimable parameters. The idpoly model stores the values of these matrix elements in the A, B, C, D, and F properties of the model.

Time-series models are special cases of polynomial models for systems without measured inputs. For AR models, B and F are empty, and C and D are 1 for all outputs. For ARMA models, B and F are empty, while D is 1.

Although idpoly supports continuous-time models, idtf and idproc enable more choices for estimation of continuous-time models. Therefore, for most continuous-time applications, these other model types are preferable.

For more information about polynomial models, see What Are Polynomial Models?

Creation

You can obtain an idpoly model in one of three ways.

Estimate the idpoly model based on output or input-output measurements of a system by using commands such as polyest, arx, armax, oe, bj, iv4, or ivar. These commands estimate the values of the free polynomial coefficients. The estimated values are stored in the A, B, C, D, and F properties of the resulting idpoly model. The Report property of the resulting model stores information about the estimation, such as information on the handling of initial conditions and options used in estimation.
When you obtain an idpoly model by estimation, you can extract estimated coefficients and their uncertainties from the model using commands such as polydata, getpar, or getcov.
Create an idpoly model using the idpoly command. You can create an idpoly model to configure an initial parameterization for estimation of a polynomial model to fit measured response data. When you do so, you can specify constraints on the polynomial coefficients. For example, you can fix the values of some coefficients, or specify minimum or maximum values for the free coefficients. You can then use the configured model as an input argument to polyest to estimate parameter values with those constraints.
Convert an existing dynamic system model to an idpoly model using the idpoly command.

Syntax

sys = idpoly(A,B,C,D,F,NoiseVariance,Ts)

sys = idpoly(A,B,C,D,F,NoiseVariance,Ts,Name,Value)

sys = idpoly(A)

sys = idpoly(A,[],C,D,[],NoiseVariance,Ts)

sys = idpoly(A,[],C,D,[],NoiseVariance,Ts,Name,Value)

sys = idpoly(sys0)

sys = idpoly(sys0,'split')

Description

Create Input-Output Polynomial Model

sys = idpoly(A,B,C,D,F,NoiseVariance,Ts) creates a polynomial model with identifiable coefficients. A, B, C, D, and F specify the initial values of the coefficients. NoiseVariance specifies the initial value of the variance of the white noise source. Ts is the model sample time.

example

sys = idpoly(A,B,C,D,F,NoiseVariance,Ts,Name,Value) creates a polynomial model using additional options specified by one or more name-value pair arguments.

example

Create Time-Series Model

sys = idpoly(A) creates a time-series model with only an autoregressive term. In this case, sys represents the AR model given by A(q) y(t) = e(t). The noise e(t) has variance 1. A specifies the initial values of the estimable coefficients.

sys = idpoly(A,[],C,D,[],NoiseVariance,Ts) creates a time-series model with an autoregressive and a moving average term. The inputs A, C, and D, specify the initial values of the estimable coefficients. NoiseVariance specifies the initial value of the noise e(t). Ts is the model sample time. (Omit NoiseVariance and Ts to use their default values.)

If D is set to [], then sys represents the ARMA model given by

$A (q) y (t) = C (q) e (t)$

example

sys = idpoly(A,[],C,D,[],NoiseVariance,Ts,Name,Value) creates a time-series model using additional options specified by one or more name-value pair arguments.

example

Convert Dynamic System Model to Polynomial Model

sys = idpoly(sys0) converts the dynamic system model sys0 to idpoly model form. sys0 can be any dynamic system model.

example

sys = idpoly(sys0,'split') converts sys0 to idpoly model form, and treats the last N_y input channels of sys0 as noise channels in the returned model. sys0 must be a numeric 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

`sys0` — Dynamic system
dynamic system model

Dynamic system, specified as a dynamic system model to convert to an idpoly 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.

For the syntax sys = idpoly(sys0,'split'), sys0 must meet the following requirements.

sys0 is a numeric tf (Control System Toolbox), zpk (Control System Toolbox), or ss (Control System Toolbox) model object.
sys0 has at least as many inputs as outputs.
The subsystem sys0(:,Ny+1:Nu) must be biproper.

Properties

expand all

`A,B,C,D,F` — Values of polynomial coefficients
`[]` | `1` | row vectors | array of row vectors

Values of the polynomial coefficients, specified as row vectors for SISO models or, for MIMO models, cell arrays of row vectors that correspond to each of the A, B, C, D, and F polynomials. For each polynomial, the coefficients are stored in the following order:

Ascending powers of z^–1 or q^–1 (for discrete-time polynomial models).
Descending powers of s or p (for continuous-time polynomial models).

The leading coefficients of A, C, D, and F are always 1.

For MIMO models with N_y outputs and N_u inputs, A, B, C, D, and F are cell arrays of row vectors. Each entry in the cell array contains the coefficients of a particular polynomial that relates input, output, and noise values.

Polynomial Dimension and Constraints Relation Described

Polynomial	Dimension and Constraints	Relation Described
`A`	N_y-by-N_y cell array of row vectors Leading coefficients: Diagonal entries — Fixed to 1 Off-diagonal entries — Fixed to 0	`A{i,j}` contains coefficients that relate the output y_i to the output y_j. For example, for a two-output system, `A` is a 2-by-2 cell array, such as: A{1,1} = [1 .1] A{1,2} = [0.4 -0.6] A{2,1} = 0 A{2,2} = [1 0.2 0.3]
`B,F`	N_y-by-N_u array of row vectors Leading coefficients: B — Not constrained F — Fixed to 1	`B{i,j}` and `F{i,j}` contain coefficients that relate the output y_i to the input u_j. For example, for a two-output system, `B` and `F` are 2-by-1 cell arrays, such as: B{1,1} = [0.1 0.2] B{2,1} = [0.5 0.3] F{1,1} = [1 0.8] F{2,1} = [1 0.4]
`C,D`	N_y-by-1 array of row vectors Leading coefficients: C — Fixed to 1 D — Fixed to 1	`C{i}` and `D{i}` contain coefficients that relate the output y_i to the noise e_i. For example, for a two-output system, `C` and `D` are 2-by-1 cell arrays, such as: C{1,1} = [1 0.3] C{2,1} = [1 0.5 0.3] D{1,1} = [1 0.7] D{2,1} = [1 0.1 0.2]

A

N_y-by-N_y cell array of row vectors

Leading coefficients:

Diagonal entries — Fixed to 1
Off-diagonal entries — Fixed to 0

A{i,j} contains coefficients that relate the output y_i to the output y_j.

For example, for a two-output system, A is a 2-by-2 cell array, such as:

A{1,1} = [1 .1]
A{1,2} = [0.4 -0.6]
A{2,1} = 0
A{2,2} = [1 0.2 0.3]

B,F

N_y-by-N_u array of row vectors

Leading coefficients:

B — Not constrained
F — Fixed to 1

B{i,j} and F{i,j} contain coefficients that relate the output y_i to the input u_j.

For example, for a two-output system, B and F are 2-by-1 cell arrays, such as:

B{1,1} = [0.1 0.2]
B{2,1} = [0.5 0.3]
F{1,1} = [1 0.8]
F{2,1} = [1 0.4]

C,D

N_y-by-1 array of row vectors

Leading coefficients:

C — Fixed to 1
D — Fixed to 1

C{i} and D{i} contain coefficients that relate the output y_i to the noise e_i.

For example, for a two-output system, C and D are 2-by-1 cell arrays, such as:

C{1,1} = [1 0.3]
C{2,1} = [1 0.5 0.3]
D{1,1} = [1 0.7]
D{2,1} = [1 0.1 0.2]

For a time series model (a model with no measured inputs), B = [] and F = [].

If you obtain an idpoly model sys by identification using a function such as polyest or arx, then sys.A, sys.B, sys.C, sys.D, and sys.F contain the estimated values of the polynomial coefficients.

If you create an idpoly model sys using the idpoly command, sys.A, sys.B, sys.C, sys.D, and sys.F contain the initial coefficient values that you specify with the A,B,C,D,F input arguments. Use NaN for any coefficient whose initial value is not known. Use [] for any polynomial that is not present in the model structure that you want to create. For example, to create an ARX model, use [] for C, D, and F. For an ARMA time series model, use [] for B and F. Default initial values when you create an idpoly model are:

B — []
C — 1 for all outputs
D — 1 for all outputs
F — []

For an idpoly model sys, each property sys.A, sys.B, sys.C, sys.D, and sys.F 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.

`Variable` — Polynomial model display variable
`'s'` (default) | `'p'` | `'z^-1'` | `'q^-1'`

Polynomial model display variable, specified as one of the following values:

'z^-1' — Default for discrete-time models
'q^-1' — Equivalent to 'z^-1'
's' — Default for continuous-time models
'p' — Equivalent to 's'

The value of Variable is reflected in the display, and also affects the interpretation of the A, B, C, D, and F coefficient vectors for discrete-time models. When Variable is set to 'z^-1' or 'q^-1', the coefficient vectors are ordered as ascending powers of the variable.

`IODelay` — Transport delays
`0` (default) | scalar | numeric array

Transport delays, specified as a numeric array containing a separate transport delay for each input-output pair or as a scalar that applies the same delay to each input-output pair.

For continuous-time systems, transport delays are expressed in the time unit stored in the TimeUnit property. For discrete-time systems, transport delays are expressed as integers denoting a delay of a multiple of the sample time Ts.

For a MIMO system with N_y outputs and N_u inputs, IODelay is an N_y-by-N_u array. Each entry of this array is a numerical value representing the transport delay for the corresponding input-output pair. You can set IODelay to a scalar value to apply the same delay to all input-output pairs.

If you create an idpoly model sys using the idpoly command, sys.IODelay contains the initial values of the transport delay that you specify with a name-value pair argument.

If you obtain an idpoly model sys by identification using a function such as polyest or arx, then sys.IODelay contains the estimated values of the transport delay.

For an idpoly model sys, the property sys.IODelay is an alias for the value of the property sys.Structure.IODelay.Value.

`IntegrateNoise` — Presence of integration on noise channels
logical vector of zeros (default) | logical vector

Logical vector denoting the presence or absence of integration on noise channels, specified as a logical vector with length equal to the number of outputs.

IntegrateNoise(i) = true indicates that the noise channel for the ith output contains an integrator. In this case, the corresponding D polynomial contains an additional term that is not represented in the property sys.D. This integrator term is equal to 1/s for continuous-time systems and 1/(1-z^-1) for discrete-time systems.

`Structure` — Information about the estimable parameters
structure property values

Property-specific information about the estimable parameters of the idpoly model, specified as a structure.

For a system with N_y outputs and N_u inputs, the dimensions of the Structure elements are as follows:

sys.Structure.A — N_y-by-N_y
sys.Structure.B — N_y-by-N_u
sys.Structure.C — N_y-by-1
sys.Structure.D — N_y-by-1
sys.Structure.F — N_y-by-N_u

sys.Structure.A, sys.Structure.B, sys.Structure.C, sys.Structure.D, and sys.Structure.F contain information about the polynomial coefficients. sys.Structure.IODelay contains information about the transport delay. sys.Structure.IntegrateNoise contains information about the integration terms on the noise. Each parameter in Structure contains the following fields.

Field	Description	Examples
Value	Parameter values. Each property 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 SISO A polynomial. `sys.A` is an alias of the value of this property. `sys.A{i,j}` is the alias of the MIMO property `sys.Structure.A(i,j).Value`.
Minimum	Minimum value that the parameter can assume during estimation	`sys.Structure.IODelay.Minimum = 0.1` constrains the transport delay to values greater than or equal to 0.1. `sys.Structure.IODelay.Minimum` must 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` to `false`. For fixed values, such as the leading coefficients of the values of A polynomial, which are always equal to 1, the corresponding value of `Free` is always `false`.	If B is a 3-by-3 matrix,`sys.Structure.B.Free = eye(3)` fixes all of the off-diagonal entries in B to the values specified in `sys.Structure.B.Value`. In this case, only the diagonal entries in B 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.	Example: `'Time'`

An inactive polynomial, such as the B polynomial in a time series model, is not available as a parameter in the Structure property. For example, sys = idpoly([1 -0.2 0.5]) creates an AR model. sys.Structure contains the fields sys.Structure.A and sys.Structure.IntegrateNoise. However, there is no field in Structure corresponding to B, C, D, F, or IODelay.

`NoiseVariance` — Variance of model innovations
positive scalar | matrix

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

SISO model — Scalar
MIMO model with N_y outputs — N_y-by-N_y positive semidefinite 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 polyest) 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 polyest, armax, oe, and bj. Use Report to find estimation information for the identified model, including:

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.

m = idpoly({[1 0.5]},{[1 5]},{[1 0.01]});
m.Report.OptionsUsed

ans =

     []

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

load iddata2 z2;
m = polyest(z2,[2 2 3 3 2 1]);
m.Report.OptionsUsed

Option set for the polyest command:

    InitialCondition: 'auto'
               Focus: 'prediction'
  EstimateCovariance: 1
             Display: 'off'
         InputOffset: []
        OutputOffset: []
      Regularization: [1x1 struct]
        SearchMethod: 'auto'
       SearchOptions: [1x1 idoptions.search.identsolver]
            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.

In estimation, InputDelay is a fixed constant of the model. The software uses the IODelay property for estimating time delays. To specify initial values and constraints for estimation of time delays, use sys.Structure.IODelay.

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

This property is read-only.

Output delay for each output channel, specified as 0. This value is fixed for identified systems such as idpoly.

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

Sample time, specified as one of the following.

Discrete-time model with an unspecified sample time — -1
Continuous-time model — 0
Discrete-time model with a specified sampling time — Positive scalar representing the sampling period expressed in the unit specified by the TimeUnit property of the model

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 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 the following:

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
structure with no fields (default) | structure

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 the following:

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` — Text to associate with system
`0`-by-`1` string (default) | string | string array | character vector

Any text that you want to associate with the system, specified as a string.

For a single note, specify Notes as a string or a character vector
For multiple notes, specify Notes as a string array.

The property preserves the string or character data type that you specify. When you specify a character vector, the software packages the character vector in a 1-by-1 cell array.

For example, if sys1, sys2, and sys3 are dynamic system models, you can set their Notes properties as follows.

sys1.Notes = "sys1 has a string.";
sys2.Notes = ["sys2 has a first string";"sys3 has a second string"];
sys3.Notes = 'sys3 has a character vector.';
sys1.Notes
sys2.Notes
sys3.Notes

ans = 

    "sys1 has a string."

ans = 

  2×1 string array

    "sys2 has a first string"
    "sys2 has a second string"

ans =

  1×1 cell array

    {'sys3 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) | structure

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 idpoly model object. These functions are of four general types.

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

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

expand all

Transformation and Manipulation

`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

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 with measured output
`impulse`	Impulse response plot of dynamic system; impulse response data
`step`	Step response of dynamic system
`bode`	Bode frequency response of dynamic system

expand all

Information Extraction and Interpretation

`tfdata`	Access transfer function data
`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

Conversion to Other Model Structures

`idtf`	Transfer function model with identifiable parameters
`idss`	State-space model with identifiable parameters
`idfrd`	Frequency response data or model

Examples

collapse all

Create Polynomial Model

Open Live Script

Create an idpoly model representing the single-input, single-output ARMAX model described by the following equation:

$y (t) + 0.5 y = u (t) + 5 u (t - 1) + 2 u (t - 2) + e (t) + 0.01 e (t - 1)$ .

$y$ is the output, $u$ is the input, and $e$ is the white-noise disturbance on $y$ .

To create the idpoly model, define the A, B, and C polynomials that describe the relationships between the output, input, and noise values, respectively. Because there are no denominator terms in the system equation, D and F are 1.

A = [1 0.5];
B = [1 5 2];
C = [1 0.01];

Create an idpoly model with the specified coefficients.

sys = idpoly(A,B,C)

sys =
Discrete-time ARMAX model: A(z)y(t) = B(z)u(t) + C(z)e(t)
  A(z) = 1 + 0.5 z^-1                                    
                                                         
  B(z) = 1 + 5 z^-1 + 2 z^-2                             
                                                         
  C(z) = 1 + 0.01 z^-1                                   
                                                         
Sample time: unspecified
  
Parameterization:
   Polynomial orders:   na=1   nb=3   nc=1   nk=0
   Number of free coefficients: 5
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

The display shows all the polynomials and allows you to verify them. The display also states that there are five free coefficients.

Create an idpoly model with specified noise variance nv and sample time Ts. To do so, you must also include values of 1 for D and F.

Ts = 0.1;
nv = 0.01;
sys = idpoly(A,B,C,1,1,nv,Ts)

sys =
Discrete-time ARMAX model: A(z)y(t) = B(z)u(t) + C(z)e(t)
  A(z) = 1 + 0.5 z^-1                                    
                                                         
  B(z) = 1 + 5 z^-1 + 2 z^-2                             
                                                         
  C(z) = 1 + 0.01 z^-1                                   
                                                         
Sample time: 0.1 seconds
  
Parameterization:
   Polynomial orders:   na=1   nb=3   nc=1   nk=0
   Number of free coefficients: 5
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

The display shows a sample time of 0.1 seconds.

Specify an input-output delay iod of one sample when you create an idpoly model.

iod = 1;
sys = idpoly(A,B,C,1,1,nv,Ts,'IODelay',1)

sys =
Discrete-time ARMAX model: A(z)y(t) = B(z)u(t) + C(z)e(t)
  A(z) = 1 + 0.5 z^-1                                    
                                                         
  B(z) = 1 + 5 z^-1 + 2 z^-2                             
                                                         
  C(z) = 1 + 0.01 z^-1                                   
                                                         
Input delays (listed by channel): 1                      
Sample time: 0.1 seconds
  
Parameterization:
   Polynomial orders:   na=1   nb=3   nc=1   nk=0
   Number of free coefficients: 5
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

The display shows an input delay of one sample.

You can use sys to specify an initial parameterization for estimation with commands such as polyest or armax.

Create Polynomial Time-Series Model

Open Live Script

Create an idpoly model representing the single-output ARMA model described by the following equation:

$y (t) + 0.5 y = e (t) + 0.01 e (t - 1)$

Because a time series has no measured inputs, this model contains only A and C polynomials.

A = [1 0.5];
C = [1 0.01];

Create a discrete-time time-series model without specifying a sample time.

sys = idpoly(A,[],C)

sys =
Discrete-time ARMA model: A(z)y(t) = C(z)e(t)
  A(z) = 1 + 0.5 z^-1                        
                                             
  C(z) = 1 + 0.01 z^-1                       
                                             
Sample time: unspecified
  
Parameterization:
   Polynomial orders:   na=1   nc=1
   Number of free coefficients: 2
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

The display reflects your specifications.

Create a continuous-time time-series by specifying a sample time of 0 for the name-value pair argument 'Ts'.

sys = idpoly(A,[],C,'Ts',0)

sys =
Continuous-time ARMA model: A(s)y(t) = C(s)e(t)
  A(s) = s + 0.5                               
                                               
  C(s) = s + 0.01                              
                                               
Parameterization:
   Polynomial orders:   na=1   nc=1
   Number of free coefficients: 2
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

You can also set the sample time using the Ts input argument rather than the name-value pair argument, but the syntax is more complex. You must specify the D value as 1 or empty, and set both the F position and the noise variance position (if you are not specifying noise variance) to empty.

Ts = 0;
sys = idpoly(A,[],C,1,[],[],Ts)

sys =
Continuous-time ARMA model: A(s)y(t) = C(s)e(t)
  A(s) = s + 0.5                               
                                               
  C(s) = s + 0.01                              
                                               
Parameterization:
   Polynomial orders:   na=1   nc=1
   Number of free coefficients: 2
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

Multi-Output ARMAX Model

Open Live Script

Create an idpoly model representing the one-input, two-output ARMAX model described by the following equations:

$\begin{array}{l} y_{1} (t) + 0.5 y_{1} (t - 1) + 0.9 y_{2} (t - 1) + 0.1 y_{2} (t - 2) = \\ u (t) + 5 u (t - 1) + 2 u (t - 2) + e_{1} (t) + 0.01 e_{1} (t - 1) \\ y_{2} (t) + 0.05 y_{2} (t - 1) + 0.3 y_{2} (t - 2) = \\ 10 u (t - 2) + e_{2} (t) + 0.1 e_{2} (t - 1) + 0.02 e_{2} (t - 2) . \end{array}$

$y_{1}$ and $y_{2}$ are the two outputs, and $u$ is the input. $e_{1}$ and $e_{2}$ are the white noise disturbances on the outputs $y_{1}$ and $y_{2}$ , respectively.

To create the idpoly model, define the A, B, and C polynomials that describe the relationships between the outputs, inputs, and noise values. (Because there are no denominator terms in the system equations, D and F are 1.)

Define the cell array containing the coefficients of the A polynomials.

A = cell(2,2); 		
A{1,1} = [1 0.5];	
A{1,2} = [0 0.9 0.1];
A{2,1} = [0]; 	
A{2,2} = [1 0.05 0.3];

You can read the values of each entry in the A cell array from the left side of the equations describing the system. For example, A{1,1} describes the polynomial that gives the dependence of $y_{1}$ on itself. This polynomial is $A_{11} = 1 + 0.5 q^{- 1}$ , because each factor of $q^{- 1}$ corresponds to a unit time decrement. Therefore, A{1,1} = [1 0.5], giving the coefficients of $A_{11}$ in increasing exponents of $q^{- 1}$ .

Similarly, A{1,2} describes the polynomial that gives the dependence of $y_{1}$ on $y_{2}$ . From the equations, $A_{12} = 0 + 0.9 q^{- 1} + 0.1 q^{- 2}$ . Thus, A{1,2} = [0 0.9 0.1].

The remaining entries in A are similarly constructed.

Define the cell array containing the coefficients of the B polynomials.

B = cell(2,1);
B{1,1} = [1 5 2];	
B{2,1} = [0 0 10];

B describes the polynomials that give the dependence of the outputs $y_{1}$ and $y_{2}$ on the input $u$ . From the equations, $B_{11} = 1 + 5 q^{- 1} + 2 q^{- 2}$ . Therefore, B{1,1} = [1 5 2].

Similarly, from the equations, $B_{21} = 0 + 0 q^{- 1} + 10 q^{- 2}$ . Therefore, B{2,1} = [0 0 10].

Define the cell array containing the coefficients of the C polynomials.

C = cell(2,1);
C{1,1} = [1 0.01]; 
C{2,1} = [1 0.1 0.02];

C describes the polynomials that give the dependence of the outputs $y_{1}$ and $y_{2}$ on the noise terms $e_{1}$ and $e_{2}$ . The entries of C can be read from the equations similarly to those of A and B.

Create an idpoly model with the specified coefficients.

sys = idpoly(A,B,C)

sys =
Discrete-time ARMAX model:                                                      
  Model for output number 1: A(z)y_1(t) = - A_i(z)y_i(t) + B(z)u(t) + C(z)e_1(t)
    A(z) = 1 + 0.5 z^-1                                                         
                                                                                
    A_2(z) = 0.9 z^-1 + 0.1 z^-2                                                
                                                                                
    B(z) = 1 + 5 z^-1 + 2 z^-2                                                  
                                                                                
    C(z) = 1 + 0.01 z^-1                                                        
                                                                                
  Model for output number 2: A(z)y_2(t) = B(z)u(t) + C(z)e_2(t)
    A(z) = 1 + 0.05 z^-1 + 0.3 z^-2                            
                                                               
    B(z) = 10 z^-2                                             
                                                               
    C(z) = 1 + 0.1 z^-1 + 0.02 z^-2                            
                                                               
Sample time: unspecified
  
Parameterization:
   Polynomial orders:   na=[1 2;0 2]   nb=[3;1]   nc=[1;2]   nk=[0;2]
   Number of free coefficients: 12
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

The display shows all the polynomials and allows you to verify them. The display also states that there are 12 free coefficients. Leading terms of diagonal entries in A are always fixed to 1. Leading terms of all other entries in A are always fixed to 0.

You can use sys to specify an initial parameterization for estimation with commands such as polyest or armax.

Convert Transfer Function Model into Polynomial Model

Open Live Script

Model a dynamic system using a transfer function. Then use idpoly to convert the transfer-function model into polynomial form.

Using idtf, construct the continuous-time, single-input, single-output (SISO) transfer function model described by the following equation:

$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 polynomial form.

sys = idpoly(G)

sys =
Continuous-time OE model: y(t) = [B(s)/F(s)]u(t) + e(t)
  B(s) = s + 4                                         
                                                       
  F(s) = s^2 + 20 s + 5                                
                                                       
Parameterization:
   Polynomial orders:   nb=2   nf=2   nk=0
   Number of free coefficients: 4
   Use "polydata", "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

The display shows the polynomial form and the polynomial coefficients.

Version History

Introduced before R2006a

idpoly

Description

Creation

Syntax

Description

Create Input-Output Polynomial Model

Create Time-Series Model

Convert Dynamic System Model to Polynomial Model

Input Arguments

sys0 — Dynamic system dynamic system model

Properties

A,B,C,D,F — Values of polynomial coefficients [] | 1 | row vectors | array of row vectors

Variable — Polynomial model display variable 's' (default) | 'p' | 'z^-1' | 'q^-1'

IODelay — Transport delays 0 (default) | scalar | numeric array

IntegrateNoise — Presence of integration on noise channels logical vector of zeros (default) | logical vector

Structure — Information about the estimable parameters structure property values

NoiseVariance — Variance of model innovations positive scalar | matrix

Report — Summary report report field values

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

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

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

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

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

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

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

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

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

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

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

Notes — Text to associate with system 0-by-1 string (default) | string | string array | character vector

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

SamplingGrid — Sampling grid [] (default) | structure

Object Functions

Transformation and Manipulation

Analysis and Simulation

Information Extraction and Interpretation

Conversion to Other Model Structures

Examples

Create Polynomial Model

Create Polynomial Time-Series Model

Multi-Output ARMAX Model

Convert Transfer Function Model into Polynomial Model

Version History

See Also

Topics

`sys0` — Dynamic system
dynamic system model

`A,B,C,D,F` — Values of polynomial coefficients
`[]` | `1` | row vectors | array of row vectors

`Variable` — Polynomial model display variable
`'s'` (default) | `'p'` | `'z^-1'` | `'q^-1'`

`IODelay` — Transport delays
`0` (default) | scalar | numeric array

`IntegrateNoise` — Presence of integration on noise channels
logical vector of zeros (default) | logical vector

`Structure` — Information about the estimable parameters
structure property values

`NoiseVariance` — Variance of model innovations
positive scalar | matrix

`Report` — Summary report
report field values

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

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

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

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

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

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

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

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

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

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

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

`Notes` — Text to associate with system
`0`-by-`1` string (default) | string | string array | character vector

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

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