# idnlarx

Nonlinear ARX model

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

`m = idnlarx([2 2 1]);`

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';```
`m = idnlarx([2 3 1],sigmoidnet('NumberOfUnits',15));`
`m = idnlarx([2 2 1],[]);`

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);`

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` object Wavelet network `'sigmoidnet'` or `sigmoidnet` object Sigmoid network `'treepartition'` or `treepartition` object Binary-tree `'linear'` or `[]` or `linear` object Linear function `neuralnet` object Neural network — Requires Deep Learning Toolbox™. `customnet` object Custom network — Similar to `sigmoidnet`, but with a user-defined replacement for the sigmoid function.

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` object Wavelet network `'sigmoidnet'` or `sigmoidnet` object Sigmoid network `'treepartition'` or `treepartition` object Binary-tree `'linear'` or `[]` or `linear` object Linear function `neuralnet` object Neural network — Requires Deep Learning Toolbox. `customnet` object Custom network — Similar to `sigmoidnet`, but with a user-defined replacement for the sigmoid function.

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.

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\left(x\right)={L}^{T}\left(x-r\right)+d+g\left(Q\left(x-r\right)\right)$`

Here, x is a vector of the regressors, and r is the mean of the regressors x. ${L}^{T}\left(x\right)+d$ is the output of the linear function block and is affine when d ≠ 0. d is a scalar offset. $g\left(Q\left(x-r\right)\right)$ 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.

Introduced in R2007a

Get trial now