System Identification Toolbox™

idnlarx - Class representing nonlinear ARX models

Syntax

m=idnlarx([na nb nk]) m=idnlarx([na nb nk],Nonlinearity) m=idnlarx([na nb nk],Nonlinearity,P1,V1,...,PN,VN)

Description

idnlarx is an object that stores nonlinear ARX model properties, including model parameters.

Typically, you use the nlarx command to both specify the nonlinear ARX model properties and estimate the model. You can specify the model properties directly in the nlarx syntax.

For information about the nonlinear ARX model structure, see Definition of the Nonlinear ARX Model.

The information in these reference pages summarizes the idnlarx model constructor and properties. It discusses the following topics:

idnlarx Constructor

Typically, you use the nlarx estimator command to specify the model properties and estimate the nonlinear ARX model. However, you can also use the idnlarx constructor to create the nonlinear ARX model object in advance, and then estimate the parameters of this object using pem.

m=idnlarx([na nb nk]) creates an idnlarx object with the specified number of output terms na, input terms nb, and input delays nk. It uses sigmoidnet as the nonlinearity estimator.

m=idnlarx([na nb nk],Nonlinearity) creates an idnlarx object with the specified nonlinearity estimator.

m=idnlarx([na nb nk],Nonlinearity,P1,V1,...,PN,VN) creates an idnlarx object and specifies idnlarx property-value pairs. For more information about idnlarx properties, see idnlarx Properties.

The constructor arguments have the following specifications:

[na nb nk]

na is the number of output terms, nb is the number of input terms, and nk is the input delays from each input to output.

For ny outputs and nu inputs, [na nb nk] has as many rows as there are outputs. In this case, 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.

These orders specify the regressors and the predicted output is a nonlinear function of these regressors:

Nonlinearity

Specifies the nonlinearity estimator object (formula for F above) as one of the following: sigmoidnet (default), wavenet, treepartition, customnet, neuralnet, and linear. The nonlinearity estimator objects have properties that you can set in the constructor, as follows:

m=idnlarx([2 3 1],sigmoidnet('Num',15))

For ny outputs, Nonlinearity is an ny-by-1 array, such as [sigmoidnet;wavenet]. However, if you specify a scalar object, this nonlinearity object applies to all outputs.

To use default nonlinearity properties, you may also specify the nonlinearity object name as a string. For example:

m=idnlarx([3 2 1],'sigmoidnet')

% Abbreviated.   
m=idnlarx([3 2 1],'sig')

% The estimator 'linear' or [] denotes the 
% absence of nonlinearity
m=idnlarx([2 2 1], []) % m contains no nonlinearity

For more information about nonlinearity properties, see the corresponding reference pages.

idnlarx Properties

You can include property-value pairs in the model estimator or constructor to specify the model structure and estimation algorithm 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

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

Property Name Description

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. These objects can be created using commands such as customreg and polyreg. For more information about this object, see the corresponding reference pages.

EstimationInfo

A read-only structure that stores estimation settings and results, as described in idnlarx EstimationInfo Properties.

Focus

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

'Prediction' — The estimation algorithm minimizes , where is the 1–step ahead predicted output.
'Simulation' — The estimation algorithm minimizes the output error fit. That is, when computing , y in the regressors in F are replaced by values simulated from the input only.

Note You cannot use 'Simulation' when the model contains custom regressors that use output variables, or if the model contains treepartition or neuralnet as a nonlinearity estimator.

NonlinearRegressors

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

'all' — All regressors enter the nonlinear block.
'input' — Input regressors only.
'output' — Output regressors only.
'standard' — Standard regressors only.
'custom' — Custom regressors only.
'search' — Specifies that the estimation algorithm perform an exhaustive search of the best regressor combination.
'[]' — 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 the getreg function.

Nonlinearity

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

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

na
nb
nk

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

Advanced

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

Criterion

Specifies criterion used during minimization. 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 since the estimations are performed independently for each output.

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.

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.
'grad' — A gradient method.
'lm' — Levenberg-Marquardt method.
'lsqnonlin' — Nonlinear least-squares method (requires theOptimization 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.

Trace

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

'Off' — Hide estimation information.
'On' — Display estimation information.

Weighting

Positive semi-definite matrix W used for weighted trace minimization. When Criterion = 'Trace', trace(E'*E*W) is minimized. Weighting can be used to specify relative importance of outputs in multiple-input multiple-output models (or reliability of corresponding data) when W is a diagonal matrix of nonnegative values. Weighting is not useful in single-output models. By default, Weighting is an identity matrix of size equal to the number of outputs.

Note The Criterion property setting is meaningful in multiple-output cases only. In single-output models, the two criteria are equivalent. Both the Det and Trace criteria are derived from a general requirement of minimizing a weighted sum of least squares of prediction errors. The Det criterion 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 multiple-input multiple-output models, you should use Trace with weighting that favors that channel. Otherwise it is natural to use Det. When using Det you can check cond(model.NoiseVariance) after estimation. If the matrix is ill-conditioned, it may be more robust to use the Trace criterion. You can also use compare on validation data to check whether the relative error for different channels corresponds you 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.

The search method of lsqnonlin supports the Trace criterion only.

idnlarx Advanced Algorithm Properties

The following table summarizes the fields of the Algorithm.Advanced model properties. The fields in the Algorithm.Advanced structure specify additional estimation-algorithm options.

Property Name Description

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 as1/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'

idnlarx EstimationInfo Properties

The following table summarizes the fields of the EstimationInfo model properties. The read-only fields of the EstimationInfo structure store estimation settings and results.

Property Name	Description
`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.
`DataDomain`	`'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.
`WhyStop`	Reason for terminating parameter estimation iterations.
`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.
`Iterations`	Number of iterations performed by the estimation algorithm.
`Warning`	Any warnings encountered during parameter estimation.
`InitRandState`	The value of `randn('state')` at the last randomization of the initial parameter vector.
`EstimationTime`	Duration of the estimation.

Definition of idnlarx States

The states of an idnlarx object are defined by the set of delayed input and output variables that define the structure of the model. The concept of states is useful for functions such as sim, predict, compare, findstates, data2state, findop, and linearize. A nonlinear ARX model consists of two essential elements — regressors and nonlinearities. The regressors represent the dynamic element of the model while the nonlinearities are static. The regressors include delayed samples of input and output variables (standard regressors) and user-defined transformations of delayed input and output variables (custom regressors). To determine the states of an idnlarx model, you must determine 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: p(t-1), p(t-2), ..., p(t-D).

For example, if you have a single-input, single-output idnlarx model defined as:

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

You can use the function getreg to show that m has the following 6 regressors:

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

From the list of regressors, it can be seen that the maximum delay in output variable y1 is 10 samples, while the maximum delay in input u1 is 2 samples. Therefore there are 12 states in this model composed of 10 delayed sampled of output y1 and 2 delayed samples of input u1:

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

Note The states vector contains the output variables first, followed by the input variables.

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

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

You can use getreg to find that the model has following 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. Variable y2 does not appear in the regressor set since the maximum delay in y2 is zero. The maximum delays in the three input variables are 2, 5 and 0 respectively. Summarizing this information as before, 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)]

You can see that the variables y2 and u3 do not contribute to the state vector, because the maximum delay in these variables is zero. The above analysis of determining states from an inspection of regressors can be automated using the getDelayInfo(idnlarx) command. This function 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 the input and output variables in the order (y1, y2, u1, u2, u3). The total number of model states is sum(maxDel) = 9.

Note The set of states for an idnlarx model is not minimal.

idnlarx - Class representing nonlinear ARX models

Syntax

Description

idnlarx Constructor

idnlarx Properties

idnlarx Algorithm Properties

idnlarx Advanced Algorithm Properties

idnlarx EstimationInfo Properties

Definition of idnlarx States

See Also