Accelerating the pace of engineering and science

# Documentation Center

• Trial Software

# idnlarx

Nonlinear ARX model

## Syntax

m = idnlarx([na nb nk])
m = idnlarx([na nb nk],Nonlinearity)
m = idnlarx([na nb nk],Nonlinearity,'Name',Value)
m = idnlarx(LinModel)
m = idnlarx(LinModel,Nonlinearity)
m = idnlarx(LinModel,Nonlinearity,'PropertyName',PropertyValue)

## Description

Represents nonlinear ARX model. The nonlinear ARX structure 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.

Typically, you use the nlarx command to both construct the idnlarx object and estimate the model parameters. You can configure the model properties directly in the nlarx syntax.

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

For idnlarx object properties, see:

## Construction

m = idnlarx([na nb nk]) creates an idnlarx object using a default wavelet network as its nonlinearity estimator. na, nb, and nk are positive integers that specify model orders and delays.

m = idnlarx([na nb nk],Nonlinearity) specifies a nonlinearity estimator Nonlinearity, as a nonlinearity estimator object or string representing the nonlinearity estimator type.

m = idnlarx([na nb nk],Nonlinearity,'Name',Value) creates the object using options specified as idnlarx model property or idnlarx algorithm property name and value pairs. Specify Name inside single quotes.

m = idnlarx(LinModel) creates an idnlarx object using a linear model (in place of [na nb nk]), and a wavelet network as its nonlinearity estimator. LinModel is a discrete time input-output polynomial model of ARX structure (idpoly). LinModel sets the model orders, input delay, input-output channel names and units, sample time, and time unit of m, and the polynomials initialize the linear function of the nonlinearity estimator.

m = idnlarx(LinModel,Nonlinearity) specifies a nonlinearity estimator Nonlinearity.

m = idnlarx(LinModel,Nonlinearity,'PropertyName',PropertyValue) creates the object using options specified as idnlarx property name and value pairs.

## Input Arguments

 na nb nk Positive integers that specify the model orders and delays. For ny output channels and nu input channels, na is an ny-by-ny matrix whose i-jth entry gives the number of delayed jth outputs used to compute the ith output. nb and nk are ny-by-nu matrices, where each row defines the orders for the corresponding output.

Nonlinearity

Nonlinearity estimator, specified as a nonlinearity estimator object or string representing the nonlinearity estimator type.

 'wavenet' or wavenet object (default) 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 customnet object Custom network

Specifying a string creates a nonlinearity estimator object with default settings. Use object representation to configure the properties of a nonlinearity estimator.

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

 LinModel Discrete time input-output polynomial model of ARX structure (idpoly), typically estimated using the arx command.

## idnlarx Model Properties

After creating the object, you can use get or dot notation to access the object property values. For example:

```% Get the model time unit
get(m,'TimeUnit')
% Get value of Nonlinearity property
m.Nonlinearity```

You can specify property name-value pairs in the model estimator or constructor to configure the model structure and estimation algorithm.

Use set or dot notation to set a property of an existing object.

The following table summarizes idnlarx model properties. The general idnlmodel properties also apply to this nonlinear model object (see the corresponding reference page).

Property NameDescription
Algorithm

A structure that specifies the estimation algorithm options, as described in idnlarx Algorithm Properties.

CustomRegressors

Custom expression in terms of standard regressors.
Assignable values:

• Cell array of strings. For example:
{'y1(t-3)^3','y2(t-1)*u1(t-3)','sin(u3(t-2))'}.

• Object array of customreg objects. Create these objects using commands such as customreg and polyreg. For more information, see the corresponding reference pages.

EstimationInfo

A read-only structure that stores estimation settings and results. The structure has the following fields:

Field NameDescription
Status

Shows whether the model parameters were estimated.

Method

Shows the estimation method.

LossFcn

Value of the loss function, equal to det(E'*E/N), where E is the residual error matrix (one column for each output) and N is the total number of samples.

FPE

Value of Akaike's Final Prediction Error (see fpe).

DataName

Name of the data from which the model is estimated.

DataLength

Length of the estimation data.

DataTs

Sampling interval of the estimation data.

'Time' means time domain data. 'Frequency' is not supported.

DataInterSample

Intersample behavior of the input estimation data used for interpolation:

• 'zoh' means zero-order-hold, or piecewise constant.

• 'foh' means first-order-hold, or piecewise linear.

EstimationTime

Duration of the estimation.

InitRandStateRandom number generator settings at the last randomization of the model parameters using init. init specifies the value of InitRandState as the output of executing rng.
Iterations

Number of iterations performed by the estimation algorithm.

UpdateNorm

Norm of the Gauss-Newton in the last iteration. Empty when 'lsqnonlin' is the search method.

LastImprovement

Criterion improvement in the last iteration, shown in %. Empty when 'lsqnonlin' is the search method.

Warning

Any warnings encountered during parameter estimation.

WhyStop

Reason for terminating parameter estimation iterations.

Focus

Specifies 'Prediction' or 'Simulation'.
Assignable values:

• 'Prediction' (default) — The estimation algorithm minimizes , where is the 1–step ahead predicted output. This algorithm does not necessarily minimize the simulation error.

• 'Simulation' — The estimation algorithm minimizes the simulation error and optimizes the results of compare(data,model,Inf). That is, when computing , y in the regressors in F are replaced by values simulated from the input only. 'Simulation' requires that the model include only differentiable nonlinearities.

 Note:   If your model includes the treepartition or neuralnet nonlinearity, the algorithm always uses 'prediction', regardless of the Focus value. If your model includes the wavenet nonlinearity, the first estimation of this model uses 'prediction'.
NonlinearRegressors

Specifies which standard or custom regressors enter the nonlinear block. For multiple-output models, use cell array of ny elements (ny = number of model outputs). For each output, assignable values are:

• 'all' — All regressors enter the nonlinear block.

• 'search' — Specifies that the estimation algorithm searches for the best regressor combination. This is useful when you want to reduce a large number of regressors entering the nonlinear function block or the nonlinearity estimator.

• 'input' — Input regressors only.

• 'output' — Output regressors only.

• 'standard' — Standard regressors only.

• 'custom' — Custom regressors only.

• '[]' — No regressors enter the nonlinear block.

• A vector of indices: Specifies the indices of the regressors that should be used in the nonlinear estimator. To determine the order of regressors, use getreg.

Nonlinearity

Nonlinearity estimator object. Assignable values include wavenet (default), sigmoidnet, treepartition, customnet, neuralnet, and linear. If the model contains only one regressor, you can also use saturation, deadzone, pwlinear, or poly1d.

For ny outputs, Nonlinearity is an ny-by-1 array. For example, [sigmoidnet;wavenet] for a two-output model. When you specify a scalar object, this nonlinearity applies to all outputs.

na
nb
nk

Nonlinear ARX model orders and input delays, where na is the number of output terms, nb is the number of input terms, and nk is the delay from input to output in terms of the number of samples.

For ny outputs and nu inputs, na is an ny-by-ny matrix whose i-jth entry gives the number of delayed jth outputs used to compute the ith output. nb and nk are ny-by-nu matrices.

## idnlarx Algorithm Properties

The following table summarizes the fields of the Algorithm idnlarx model properties. Algorithm is a structure that specifies the estimation-algorithm options.

Property NameDescription

A structure that specifies additional estimation algorithm options. The structure has the following fields:

Field NameDescription
GnPinvConst

When the search direction is computed, the algorithm discards the singular values of the Jacobian that are smaller than GnPinvConst*max(size(J))*norm(J)*eps. Singular values that are closer to 0 are included when GnPinvConst is decreased.
Default: 1e4.
Assign a positive, real value.

LMStartValue

(For Levenberg-Marquardt search algorithm) The starting level of regularization when using the Levenberg-Marquardt search method (Algorithm.SearchMethod='lm').
Default: 0.001.
Assign a positive real value.

LMStep

(For Levenberg-Marquardt search algorithm) Try this next level of regularization to get a lower value of the criterion function. The level of regularization is LMStep times the previous level. At the start of a new iteration, the level of regularization is computed as 1/LMStep times the value from the previous iteration.
Default: 10.
Assign a real value >1.

MaxBisections

Maximum number of bisections performed by the line search algorithm along the search direction (number of rotations of search vector for 'lm'). Used by 'gn', 'lm', 'gna' and 'grad' search methods (Algorithm.SearchMethod property)
Default: 10.
Assign a positive integer value.

MaxFunEvals

The iterations are stopped if the number of calls to the model file exceeds this value.
Default: Inf.
Assign a positive integer value.

MinParChange

The smallest parameter update allowed per iteration.
Default: 1e-16.
Assign a positive, real value.

RelImprovement

The iterations are stopped if the relative improvement of the criterion function is less than RelImprovement.
Default: 0.
Assign a positive real value.

 Note:   Does not apply to Algorithm.SearchMethod='lsqnonlin'
StepReduction

(For line search algorithm) The suggested parameter update is reduced by the factor 'StepReduction' after each try until either 'MaxBisections' tries are completed or a lower value of the criterion function is obtained.
Default: 2.
Assign a positive, real value >1.

 Note:   Does not apply to Algorithm.SearchMethod='lsqnonlin'

Criterion

The search method of lsqnonlin supports the Trace criterion only.

Use for multiple-output models only. Criterion can have the following values:

• 'Det': Minimize det(E'*E), where E represents the prediction error. This is the optimal choice in a statistical sense and leads to the maximum likelihood estimates in case nothing is known about the variance of the noise. It uses the inverse of the estimated noise variance as the weighting function. This is the default criterion used for all models, except idnlgrey which uses 'Trace' by default.

• 'Trace': Minimize the trace of the weighted prediction error matrix trace(E'*E*W), where E is the matrix of prediction errors, with one column for each output, and W is a positive semi-definite symmetric matrix of size equal to the number of outputs. By default, W is an identity matrix of size equal to the number of model outputs (so the minimization criterion becomes trace(E'*E), or the traditional least-squares criterion). You can specify the relative weighting of prediction errors for each output using the Weighting field of the Algorithm property. If the model contains neuralnet or treepartition as one of its nonlinearity estimators, weighting is not applied because estimations are independent for each output.

Both the Det and Trace criteria are derived from a general requirement of minimizing a weighted sum of least squares of prediction errors. Det can be interpreted as estimating the covariance matrix of the noise source and using the inverse of that matrix as the weighting. You should specify the weighting when using the Trace criterion.

If you want to achieve better accuracy for a particular channel in MIMO models, use Trace with weighting that favors that channel. Otherwise, use Det. If you use Det, check cond(model.NoiseVariance) after estimation. If the matrix is ill-conditioned, try using the Trace criterion. You can also use compare on validation data to check whether the relative error for different channels corresponds to your needs or expectations. Use the Trace criterion if you need to modify the relative errors, and check model.NoiseVariance to determine what weighting modifications to specify.

Display

Toggles displaying or hiding estimation progress information in the MATLAB® Command Window.
Default: 'Off'.
Assignable values:

• 'Off' — Hide estimation information.

• 'On' — Display estimation information.

IterWavenet

(For wavenet nonlinear estimator only)
Toggles performing iterative or noniterative estimation.
Default: 'auto'.
Assignable values:

• 'auto' — First estimation is noniterative and subsequent estimation are iterative.

• 'On' — Perform iterative estimation only.

• 'Off' — Perform noniterative estimation only.

LimitError

Robustification criterion that limits the influence of large residuals, specified as a positive real value. Residual values that are larger than 'LimitError' times the estimated residual standard deviation have a linear cost instead of the usual quadratic cost.
Default: 0 (no robustification).

MaxIter

Maximum number of iterations for the estimation algorithm, specified as a positive integer.
Default: 20.

MaxSize

The number of elements (size) of the largest matrix to be formed by the algorithm. Computational loops are used for larger matrices. Use this value for memory/speed trade-off.MaxSize can be any positive integer.
Default: 250000.

 Note:   The original data matrix of u and y must be smaller than MaxSize.
Regularization

Options for regularized estimation of model parameters. For more information on regularization, see Regularized Estimates of Model Parameters.

Structure with the following fields:

• Lambda — Constant that determines the bias versus variance tradeoff.

Specify a positive scalar to add the regularization term to the estimation cost.

The default value of zero implies no regularization.

Default: 0

• R — Weighting matrix.

Specify a vector of nonnegative numbers or a square positive semi-definite matrix. The length must be equal to the number of free parameters of the model.

For black-box models, using the default value is recommended. For structured and grey-box models, you can also specify a vector of np positive numbers such that each entry denotes the confidence in the value of the associated parameter.

The default value of 1 implies a value of eye(npfree), where npfree is the number of free parameters.

Default: 1

• Nominal — The nominal value towards which the free parameters are pulled during estimation.

The default value of zero implies that the parameter values are pulled towards zero. If you are refining a model, you can set the value to 'model' to pull the parameters towards the parameter values of the initial model. The initial parameter values must be finite for this setting to work.

Default: 0

SearchMethod

Method used by the iterative search algorithm.
Assignable values:

• 'Auto' — Automatically chooses from the following methods.

• 'gn' — Subspace Gauss-Newton method.

• 'gna' — Adaptive Gauss-Newton method.

• 'lm' — Levenberg-Marquardt method.

• 'lsqnonlin' — Nonlinear least-squares method (requires the Optimization Toolbox™ product). This method only handles the 'Trace' criterion.

Tolerance

Specifies to terminate the iterative search when the expected improvement of the parameter values is less than Tolerance, specified as a positive real value in %.
Default: 0.01.

Weighting

(For multiple-output models only)

Specifies the relative importance of outputs in MIMO models (or reliability of corresponding data) as a positive semi-definite matrix W. Use when Criterion = 'Trace' for weighted trace minimization. By default, Weighting is an identity matrix of size equal to the number of outputs.

## Examples

Create nonlinear ARX model structure with (default) wavelet network nonlinearity:

`m = idnlarx([2 2 1]) % na=nb=2 and nk=1`

Create nonlinear ARX model structure with sigmoid network nonlinearity:

```m=idnlarx([2 3 1],sigmoidnet('Num',15))
% number of units is 15```

Create nonlinear ARX model structure with no nonlinear function in nonlinearity estimator:

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

Construct a nonlinear ARX model using a linear ARX model:

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

expand all

### Nonlinear ARX Model Structure

This block diagram represents the structure of a nonlinear ARX model in a simulation scenario:

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

1. Computes regressors 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)—called standard regressors. You can also specify custom regressors, which are nonlinear functions of delayed inputs and outputs. For example, tan(u(t-1)) or u(t-1)*y(t-3).

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. The nonlinearity estimator block maps the regressors to the model output using a combination of nonlinear and linear functions. You can select from available nonlinearity estimators, such as tree-partition networks, wavelet networks, and multi-layer neural networks. You can also exclude either the linear or the nonlinear function block from the nonlinearity estimator.

The nonlinearity estimator block can include linear and nonlinear blocks in parallel. For example:

x is a vector of the regressors. is the output of the linear function block and is affine when d≠0. d is a scalar offset. represents the output of the nonlinear function block. r is the mean of the regressors x. 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.

Estimating a nonlinear ARX model computes the model parameter values, such as L, r, d, Q, and other parameters specifying g. Resulting models are idnlarx objects that store all model data, including model regressors and parameters of the nonlinearity estimator. See the idnlarx reference page for more information.

### Definition of idnlarx States

The states of an idnlarx object are delayed input and output variables that define the structure of the model. This toolbox requires states for simulation and prediction using sim(idnlarx), predict, and compare. States are also necessary for linearization of nonlinear ARX models using linearize(idnlarx).

This toolbox provides a number of options to facilitate how you specify the initial states. For example, you can use findstates and data2state to automatically 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 are defined by 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 2 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])```

getreg lists 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 2 samples, which occurs in 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 =
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 are not required to be minimal.