idnlarx

Nonlinear ARX model

collapse all in page

Syntax

sys = idnlarx(Orders)
sys = idnlarx(Orders,Nonlinearity)
sys = idnlarx(Orders,Nonlinearity,Name,Value)
sys = idnlarx(LinModel)
sys = idnlarx(LinModel,Nonlinearity)
sys = idnlarx(LinModel,Nonlinearity,Name,Value)

Description

sys = idnlarx(Orders) creates a nonlinear ARX model with the specified orders using a default wavelet network nonlinearity estimator.

sys = idnlarx(Orders,Nonlinearity) specifies a nonlinearity estimator for the model.

sys = idnlarx(Orders,Nonlinearity,Name,Value) specifies additional attributes of the idnlarx model structure using one or more Name,Value pair arguments.

sys = idnlarx(LinModel) uses a linear ARX model LinModel to specify the model orders and the initial values of the linear coefficients of the model.

sys = idnlarx(LinModel,Nonlinearity) specifies a nonlinearity estimator for the model.

sys = idnlarx(LinModel,Nonlinearity,Name,Value) specifies additional attributes of the idnlarx model structure using one or more Name,Value pair arguments.

Object Description

idnlarx represents a nonlinear ARX model, which is an extension of the linear ARX structure and contains linear and nonlinear functions. For more information, see Nonlinear ARX Model Extends the Linear ARX Structure.

Use the nlarx command to both construct an idnlarx object and estimate the model parameters.

You can also use the idnlarx constructor to create the nonlinear ARX model and then estimate the model parameters using nlarx or pem.

For idnlarx object properties, see Properties.

Examples

collapse all

Open Live Script
m = idnlarx([2 2 1]);
Open Live Script

Create a nonlinear ARX model with specific orders.

M = idnlarx([3 2 1]);

Configure the model with the following property settings:

  • Sigmoid network nonlinearity with default settings

  • Use inputs only as nonlinear regressors

M.Nonlinearity = 'sigmoidnet';
M.NonlinearRegressors = 'input';
Open Live Script
m = idnlarx([2 3 1],sigmoidnet('NumberOfUnits',15));
Open Live Script
m = idnlarx([2 2 1],[]);
Open Live Script

Specify two custom regressors.

C = {'y1(t-1)^2','y1(t-2)*u1(t-3)'};

Create a nonlinear ARX model with custom regressors and no standard regressors.

sys = idnlarx([0 0 0],'wavenet','CustomRegressors',C);
Open Live Script

Construct a linear ARX model.

A = [1 -1.2 0.5];
B = [0.8 1];
LinearModel = idpoly(A, B, 'Ts', 0.1);

Construct nonlinear ARX model using the linear ARX model.

m1 = idnlarx(LinearModel);

Input Arguments

collapse all

Model orders and delays for defining the regressor configuration, specified as a 1-by-3 vector, [na nb nk].

For a model with ny output channels and nu input channels:

  • na is an ny-by-ny matrix, where na(i,j) specifies the number of regressors from the jth output used to predict the ith output.

  • nb is an ny-by-nu matrix, where nb(i,j) specifies the number of regressors from the jth input used to predict the ith output.

  • nk is an ny-by-nu matrix, where nk(i,j) specifies the lag in the jth input used to predict the ith output.

na = [1 2; 2 3]
nb = [1 2 3; 2 3 1];
nk = [2 0 3; 1 0 5];

The estimation data for this system has three inputs (u1, u2, u3) and two outputs (y1, y2). Consider the regressors used to predict output, y2(t):

  • Since na(2,:) is [2 3], the contributing regressors from the outputs are:

    • y1(t-1) and y1(t-2)

    • y2(t-1), y2(t-2), and y2(t-3)

  • Since nb(2,:) is [2 3 1] and nk(2,:) is [1 0 5], the contributing regressors from the inputs are:

    • u1(t-1) and u1(t-2)

    • u2(t), u2(t-1), and u2(t-2)

    • u3(t-5)

Note

The minimum lag for regressors based on output variables is always 1, while the minimum lag for regressors based on input variables is dictated by nk. Use getreg to view the complete set of regressors used by the nonlinear ARX model.

Nonlinearity estimator, specified as one of the following:

'wavenet' or wavenet objectWavelet network
'sigmoidnet' or sigmoidnet objectSigmoid network
'treepartition' or treepartition objectBinary-tree
'linear' or [] or linear objectLinear function
neuralnet objectNeural network — Requires Deep Learning Toolbox™.
customnet objectCustom network — Similar to sigmoidnet, but with a user-defined replacement for the sigmoid function.

For more information, see Available Nonlinearity Estimators for Nonlinear ARX Models.

Specifying a character vector, for example 'sigmoidnet', creates a nonlinearity estimator object with default settings. Alternatively, you can specify nonlinearity estimator settings in two ways:

  • Use the associated nonlinearity estimator function with Name-Value pair arguments.

    NL = sigmoidnet('NumberOfUnits',10);

  • Create and modify a default nonlinearity estimator object.

    NL = sigmoidnet;
NL.NumberOfUnits = 10;

For ny output channels, you can specify nonlinear estimators individually for each channel by setting Nonlinearity to an ny-by-1 array of nonlinearity estimator objects. To specify the same nonlinearity for all outputs, specify Nonlinearity as a character vector or a single nonlinearity estimator object.

Example: 'sigmoidnet' specifies a sigmoid network nonlinearity with a default configuration.

Example: treepartition('NumberOfUnits',5) specifies a binary-tree nonlinearity with 5 terms in the binary tree expansion.

Example: [wavenet('NumberOfUnits',10);sigmoidnet] specifies different nonlinearity estimators for two output channels.

Discrete time input-output polynomial model of ARX structure, specified as an idpoly model. Create this object using the idpoly constructor or estimate it using the arx command.

Name-Value Pair Arguments

Specify optional comma-separated pairs of Name,Value arguments. Name is the argument name and Value is the corresponding value. Name must appear inside quotes. You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN.

Use Name,Value arguments to specify additional properties of idnlarx models during model creation. For example, m = idnlarx([2 3 1],'treepartition','InputName','Pressure','Ts',0.1) creates an idnlarx model with the input name Pressure, and a sample time of 0.1 seconds

Properties

na, nb, nk

Model orders and delays for defining the regressor configuration, specified as nonnegative integers.

For a model with ny output channels and nu input channels:

  • na is an ny-by-ny matrix, where na(i,j) specifies the number of regressors from the jth output used to predict the ith output.

  • nb is an ny-by-nu matrix, where nb(i,j) specifies the number of regressors from the jth input used to predict the ith output.

  • nk is an ny-by-nu matrix, where nk(i,j) specifies the lag in the jth input used to predict the ith output.

na = [1 2; 2 3]
nb = [1 2 3; 2 3 1];
nk = [2 0 3; 1 0 5];

The estimation data for this system has three inputs (u1, u2, u3) and two outputs (y1, y2). Consider the regressors used to predict output, y2(t):

  • Since na(2,:) is [2 3], the contributing regressors from the outputs are:

    • y1(t-1) and y1(t-2)

    • y2(t-1), y2(t-2), and y2(t-3)

  • Since nb(2,:) is [2 3 1] and nk(2,:) is [1 0 5], the contributing regressors from the inputs are:

    • u1(t-1) and u1(t-2)

    • u2(t), u2(t-1), and u2(t-2)

    • u3(t-5)

Note

The minimum lag for regressors based on output variables is always 1, while the minimum lag for regressors based on input variables is dictated by nk. Use getreg to view the complete set of regressors used by the nonlinear ARX model.

CustomRegressors

Regressors constructed from combinations of inputs and outputs, specified as one of the following:

  • Cell array of character vectors. For example:

    • {'y1(t-3)^3','y2(t-1)*u1(t-3)','sin(u3(t-2))'}

    Each character vector must represent a valid formula for a regressor contributing towards the prediction of the model output. The formula must be written using the input and output names and the time-variable name as variables.

  • Array of custom regressor objects, created using customreg or polyreg.

For a model with ny outputs, specify an ny-by-1 cell array of customreg objects arrays or an ny-by-1 cell array of cell array of character vectors.

These regressors are in addition to the standard regressors based on na, nb, and nk.

Default: {}

NonlinearRegressors

Subset of regressors that enter as inputs to the nonlinear block of the model, specified as one of the following:

  • 'all' — All regressors

  • 'output' — Regressors containing output variables

  • 'input' — Regressors containing input variables

  • 'standard' — Standard regressors

  • 'custom' — Custom regressors

  • 'search' — The estimation algorithm performs a search for the best regressor combination. This option must be applied to all output models simultaneously.

  • [] — No regressors

  • Vector of regressor indices. To determine the number and order of regressors, use getreg.

For a model with multiple outputs, specify a cell array of ny elements, where ny is the number of output channels. For each output, specify one of the preceding options. Alternatively, to apply the same regressor subset to all model outputs, specify [] or any of the character vector options alone, for example 'standard'.

Default: 'all'

Nonlinearity

Nonlinearity estimator, specified as one of the following:

'wavenet' or wavenet objectWavelet network
'sigmoidnet' or sigmoidnet objectSigmoid network
'treepartition' or treepartition objectBinary-tree
'linear' or [] or linear objectLinear function
neuralnet objectNeural network — Requires Deep Learning Toolbox.
customnet objectCustom network — Similar to sigmoidnet, but with a user-defined replacement for the sigmoid function.

For more information, see Available Nonlinearity Estimators for Nonlinear ARX Models.

Specifying a character vector, for example 'sigmoidnet', creates a nonlinearity estimator object with default settings. Alternatively, you can specify nonlinearity estimator settings in two ways:

  • Use the associated nonlinearity estimator function with Name-Value pair arguments:

    NL = sigmoidnet('NumberOfUnits',10);

  • Create and modify a default nonlinearity estimator object:

    NL = sigmoidnet;
NL.NumberOfUnits = 10;

For ny output channels, you can specify nonlinear estimators individually for each channel by setting Nonlinearity to an array of ny nonlinearity estimator objects, where ny is the number of outputs. To specify the same nonlinearity for all outputs, specify Nonlinearity as a character vector or a single nonlinearity estimator object.

Default: 'wavenet'

Report

Summary report that contains information about the estimation options and results when the model is estimated using the nlarx command. Use Report to query a model for how it was estimated, including its:

  • Estimation method

  • Estimation options

  • Search termination conditions

  • Estimation data fit

The contents of Report are irrelevant if the model was constructed.

m = idnlarx([2 2 1]);
m.Report.OptionsUsed
ans =

     []

If you use nlarx to estimate the model, the fields of Report contain information on the estimation data, options, and results.

load iddata1;
m = nlarx(z1, [2 2 1]);
m.Report.OptionsUsed
Option set for the nlarx command:

  IterativeWavenet: 'auto'
             Focus: 'prediction'
           Display: 'off'
    Regularization: [1x1 struct]
      SearchMethod: 'auto'
     SearchOptions: [1x1 idoptions.search.identsolver]
      OutputWeight: 'noise'
          Advanced: [1x1 struct]

Report is a read-only property.

For more information on this property and how to use it, see Output Arguments in the nlarx reference page and Estimation Report.

TimeVariable

Independent variable for the inputs, outputs, and—when available—internal states, specified as a character vector.

Default: 't' (time)

NoiseVariance

Noise variance (covariance matrix) of the model innovations e.
Assignable value is an ny-by-ny matrix.
Typically set automatically by the estimation algorithm.

Ts

Sample time. Ts is a positive scalar representing the sampling period. This value is expressed in the unit specified by the TimeUnit property of the model.

Default: 1

TimeUnit

Units for the time variable, the sample time Ts, and any time delays in the model, specified as one of the following values:

  • 'nanoseconds'

  • 'microseconds'

  • 'milliseconds'

  • 'seconds'

  • 'minutes'

  • 'hours'

  • 'days'

  • 'weeks'

  • 'months'

  • 'years'

Changing this property has no effect on other properties, and therefore changes the overall system behavior. Use chgTimeUnit (Control System Toolbox) to convert between time units without modifying system behavior.

Default: 'seconds'

InputName

Input channel names, specified as one of the following:

  • Character vector — For single-input models, for example, 'controls'.

  • Cell array of character vectors — For multi-input models.

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.

Input channel names have several uses, including:

  • Identifying channels on model display and plots

  • Extracting subsystems of MIMO systems

  • Specifying connection points when interconnecting models

Default: '' for all input channels

InputUnit

Input channel units, specified as one of the following:

  • Character vector — For single-input models, for example, 'seconds'.

  • Cell array of character vectors — For multi-input models.

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

Default: '' for all input channels

InputGroup

Input channel groups. The InputGroup property lets you assign the input channels of MIMO systems into groups and refer to each group by name. Specify input groups as a structure. In this structure, field names are the group names, and field values are the input channels belonging to each group. For example:

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

creates input groups named controls and noise that include input channels 1, 2 and 3, 5, respectively. You can then extract the subsystem from the controls inputs to all outputs using:

sys(:,'controls')

Default: Struct with no fields

OutputName

Output channel names, specified as one of the following:

  • Character vector — For single-output models. For example, 'measurements'.

  • Cell array of character vectors — For multi-output models.

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.

Output channel names have several uses, including:

  • Identifying channels on model display and plots

  • Extracting subsystems of MIMO systems

  • Specifying connection points when interconnecting models

Default: '' for all output channels

OutputUnit

Output channel units, specified as one of the following:

  • Character vector — For single-output models. For example, 'seconds'.

  • Cell array of character vectors — For multi-output models.

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

Default: '' for all output channels

OutputGroup

Output channel groups. The OutputGroup property lets you assign the output channels of MIMO systems into groups and refer to each group by name. Specify output groups as a structure. In this structure, field names are the group names, and field values are the output channels belonging to each group. For example:

sys.OutputGroup.temperature = [1];
sys.InputGroup.measurement = [3 5];

creates output groups named temperature and measurement that include output channels 1, and 3, 5, respectively. You can then extract the subsystem from all inputs to the measurement outputs using:

sys('measurement',:)

Default: Struct with no fields

Name

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

Default: ''

Notes

Any text that you want to associate with the system, stored 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.'

Default: [0×1 string]

UserData

Any type of data you want to associate with system, specified as any MATLAB® data type.

Default: []

Output Arguments

collapse all

Nonlinear ARX model, returned as an idnlarx object. This model is created using the specified model orders, nonlinearity estimator, and properties.

More About

collapse all

Nonlinear ARX Model Structure

A nonlinear ARX model consists of model regressors and a nonlinearity estimator. The nonlinearity estimator comprises both linear and nonlinear functions that act on the model regressors to give the model output. This block diagram represents the structure of a nonlinear ARX model in a simulation scenario.

The software computes the nonlinear ARX model output y in two stages:

  1. It computes regressor values from the current and past input values and past output data.

    In the simplest case, regressors are delayed inputs and outputs, such as u(t-1) and y(t-3). These kind of regressors are called standard regressors. You specify the standard regressors using the model orders and delay. For more information, see Nonlinear ARX Model Orders and Delay. You can also specify custom regressors, which are nonlinear functions of delayed inputs and outputs. For example, u(t-1)*y(t-3). To create a set of polynomial type regressors, use polyreg.

    By default, all regressors are inputs to both the linear and the nonlinear function blocks of the nonlinearity estimator. You can choose a subset of regressors as inputs to the nonlinear function block.

  2. It maps the regressors to the model output using the nonlinearity estimator block. The nonlinearity estimator block can include linear and nonlinear blocks in parallel. For example:

    F(x)=LT(x−r)+d+g(Q(x−r))

    Here, x is a vector of the regressors, and r is the mean of the regressors x. LT(x)+d is the output of the linear function block and is affine when d ≠ 0. d is a scalar offset. g(Q(x−r)) represents the output of the nonlinear function block. Q is a projection matrix that makes the calculations well conditioned. The exact form of F(x) depends on your choice of the nonlinearity estimator. You can select from available nonlinearity estimators, such as tree-partition networks, wavelet networks, and multilayer neural networks. You can also exclude either the linear or the nonlinear function block from the nonlinearity estimator.

    When estimating a nonlinear ARX model, the software computes the model parameter values, such as L, r, d, Q, and other parameters specifying g.

Resulting nonlinear ARX models are idnlarx objects that store all model data, including model regressors and parameters of the nonlinearity estimator. For more information about these objects, see Nonlinear Model Structures.

Definition of idnlarx States

The states of an idnlarx object are an ordered list of delayed input and output variables that define the structure of the model. The toolbox uses this definition of states for creating the initial state vector that is used during simulation and prediction with sim, predict, and compare. This definition is also used for linearization of nonlinear ARX models using linearize.

This toolbox provides several options to facilitate how you specify the initial states. For example, you can use findstates and data2state to search for state values in simulation and prediction applications. For linearization, use findop. You can also specify the states manually.

The states of an idnlarx model depend on the maximum delay in each input and output variable used by the regressors. If a variable p has a maximum delay of D samples, then it contributes D elements to the state vector at time t: p(t-1), p(t-2), ..., p(t-D).

For example, if you have a single-input, single-output idnlarx model.

m = idnlarx([2 3 0],'wavenet','CustomRegressors',{'y1(t-10)*u1(t-1)'});

This model has these regressors. 

getreg(m)
Regressors:
    y1(t-1)
    y1(t-2)
    u1(t)
    u1(t-1)
    u1(t-2)
    y1(t-10)*u1(t-1)

The regressors show that the maximum delay in the output variable y1 is 10 samples and the maximum delay in the input u1 is two samples. Thus, this model has a total of 12 states:

X(t) = [y1(t-1),y2(t-2),…,y1(t-10),u1(t-1),u1(t-2)]

Note

The state vector includes the output variables first, followed by input variables.

As another example, consider the 2-output and 3-input model. 

m = idnlarx([2 0 2 2 1 1 0 0; 1 0 1 5 0 1 1 0],[wavenet; linear]);

This model has these regressors. 

getreg(m)
Regressors:
  For output 1:
    y1(t-1)
    y1(t-2)
    u1(t-1)
    u1(t-2)
    u2(t)
    u2(t-1)
    u3(t)
  For output 2:
    y1(t-1)
    u1(t-1)
    u2(t-1)
    u2(t-2)
    u2(t-3)
    u2(t-4)
    u2(t-5)

The maximum delay in output variable y1 is two samples. This delay occurs in the regressor set for output 1. The maximum delays in the three input variables are 2, 5, and 0, respectively. Thus, the state vector is: 

X(t) = [y1(t-1), y1(t-2), u1(t-1), u1(t-2), u2(t-1), 
            u2(t-2), u2(t-3), u2(t-4), u2(t-5)]

Variables y2 and u3 do not contribute to the state vector because the maximum delay in these variables is zero.

A simpler way to determine states by inspecting regressors is to use getDelayInfo, which returns the maximum delays in all I/O variables across all model outputs. For the multiple-input multiple-output model m, getDelayInfo returns: 

maxDel = getDelayInfo(m)
maxDel = 1×5

     2     0     2     5     0

maxDel contains the maximum delays for all input and output variables in the order (y1, y2, u1, u2, u3). The total number of model states is sum(maxDel) = 9.

The set of states for an idnlarx model is not required to be minimal.

See Also

| | | | | | | | | | |

Topics

Introduced in R2007a

System Identification Toolbox Documentation

Support