Accelerating the pace of engineering and science

# idnlhw

Hammerstein-Wiener model

## Syntax

m = idnlhw([nb nf nk])
m = idnlhw([nb nf nk],InputNL,OutputNL)
m = idnlhw([nb nf nk],InputNL,OutputNL,'Name',Value)
m = idnlhw(LinModel)
m = idnlhw(LinModel,InputNL,OutputNL)
m = idnlhw(LinModel,InputNL,OutputNL,'PropertyName',PropertyValue)

## Description

Represents Hammerstein-Wiener models. The Hammerstein-Wiener structure represents a linear model with input-output nonlinearities.

Typically, you use the nlhw command to both construct the idnlhw object and estimate the model parameters. You can configure the model properties directly in the nlhw syntax. For information about the Hammerstein-Wiener model structure, see Structure of Hammerstein-Wiener Models.

You can also use the idnlhw constructor to create the Hammerstein-Wiener model structure and then estimate the parameters of this model using pem.

For idnlhw object properties, see:

## Construction

m = idnlhw([nb nf nk]) creates an idnlhw object using default piecewise linear functions for the input and output nonlinearity estimators. nb, nf, and nk are positive integers that specify model orders and delays. nb is the number of zeros plus 1, nf is the number of poles, and nk is the input delay.

m = idnlhw([nb nf nk],InputNL,OutputNL) specifies input nonlinearity InputNL and output nonlinearity OutputNL, as a nonlinearity estimator object or string representing the nonlinearity estimator type.

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

m = idnlhw(LinModel) uses a linear model (in place of [nb nf nk]) and default piecewise linear functions for the input and output nonlinearity estimators. LinModel is a discrete time input-output polynomial model of Output-Error (OE) structure (idpoly), state-space model with no disturbance component (idss with K = 0), or transfer function model (idtf). LinModel sets the model orders, input delay, B and F polynomial values, input-output names and units, sampling time, and time units of m.

m = idnlhw(LinModel,InputNL,OutputNL) specifies input nonlinearity InputNL and output nonlinearity OutputNL.

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

## Input Arguments

 nb, nf, nk Model orders and input delay, where nb is the number of zeros plus 1, nf is the number of poles, and nk is the input delay. For nu inputs and ny outputs, nb, nf, and, nk are ny-by-nu matrices whose i-jth entry specifies the orders and delay of the transfer function from the jth input to the ith output.

InputNL, OutputNL

Input and output nonlinearity estimators, respectively, specified as a nonlinearity estimator object or string representing the nonlinearity estimator type.

 'pwlinear' or pwlinear object (default) Piecewise linear function 'sigmoidnet' or sigmoidnet object Sigmoid network 'wavenet' or wavenet object Wavelet network 'saturation' or saturation object Saturation 'deadzone' or deadzone object Dead zone 'poly1d' or poly1d object One-dimensional polynomial 'unitgain' or unitgain object Unit gain 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 InputNL or OutputNL to an ny-by-1 cell array or object array of nonlinearity estimators. To specify the same nonlinearity for all outputs, specify a single input and output nonlinearity estimator.

 LinModel Discrete time linear model, specified as one of the following: Input-output polynomial model of Output-Error (OE) structure (idpoly)State-space model with no disturbance component (idss with K = 0)Transfer function model (idtf) Typically, you estimate the model using oe, n4sid or tfest.

## idnlhw Model Properties

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

```% Get the model B parameters
get(m,'b')
% Get value of InputNonlinearity property
m.InputNonlinearity```

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

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

The following table summarizes idnlhw 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 idnlhw Algorithm Properties.

b

B polynomial as a cell array of Ny-by-Nu elements, where Ny is the number of outputs and Nu is the number of inputs. An element b{i,j} is a row vector representing the numerator polynomial for the jth input to ith output transfer function. It contains as many leading zeros as there are input delays.

f

F polynomial as a cell array of Ny-by-Nu elements, where Ny is the number of outputs and Nu is the number of inputs. An element f{i,j} is a row vector representing the denominator polynomial for the j:th input to ith output transfer function.

LinearModel

(Read only) The linear model in the linear block, represented as an idpoly object.

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.

WhyStop

Reason for terminating parameter estimation iterations.

UpdateNorm

Norm of the search vector (gn-vector) 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 random number type and seed at the last randomization of the initial parameter vector.

EstimationTime

Duration of the estimation.

InputNonlinearity

Nonlinearity estimator object. Assignable values include pwlinear (default), deadzone, wavenet, saturation, customnet, sigmoidnet, poly1d, and unitgain. For more information, see the corresponding reference pages.

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.

OutputNonlinearity

Same as InputNonlinearity.

nb
nf
nk

Model orders and input delays, where nb is the number of zeros plus 1, nf is the number of poles, and nk is the delay from input to output in terms of the number of samples.

For nu inputs and ny outputs, nb, nf and, nk are ny-by-nu matrices whose i-jth entry specifies the orders and delay of the transfer function from the jth input to the ith output.

## idnlhw Algorithm Properties

The following table summarizes the fields of the Algorithm idnlhw 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:   This does not apply when 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:   This does not apply when 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)
Implicitly set to perform iterative estimation. Changing this setting does not impact the algorithm.
Default: 'On'.

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' — Gauss-Newton method.

• 'gna' — Adaptive Gauss-Newton method.

• 'lm' — Levenberg-Marquardt method.

• 'lsqnonlin' — Nonlinear least-squares method (requires the Optimization Toolbox™ product). This method handles only 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

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.

## Examples

Create default Hammerstein-Wiener model structure:

```  m = idnlhw([2 2 1]) % na=nb=2 and nk=1
% m has piecewise linear input and output nonlinearity```

Create nonlinear ARX model structure with sigmoid network nonlinearity:

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

Create Hammerstein-Wiener model with specific input-output nonlinearities:

```  m=idnlhw([2 2 1],'sigmoidnet','deadzone')
% Equivalent to m=idnlhw([2 2 1],'sig','dead')
% Nonlinearities have default configuration
```

Create Hammerstein-Wiener model and configure the nonlinearity objects:

`m=idnlhw([2 2 1],sigmoidnet('num',5),deadzone([-1,2]))`

Create a Hammerstein model (no output nonlinearity):

```m=idnlhw([2 2 1],'saturation',[])
% [] specifies unitgain output nonlinearity```

Configure the Hammerstein-Wiener model and estimate models parameters:

```m0 = idnlhw([nb,nf,nk],[sigmoidnet;pwlinear],[]);
m = pem(data,m0); % equivalent to m=nlhw(data,m0)```

Construct default Hammerstein-Wiener model using an input-output polynomial model of Output-Error structure:

```% Construct an input-output polynomial model of OE structure.
B = [0.8 1];
F = [1 -1.2 0.5];
LinearModel = idpoly(1, B, 1,1, F, 'Ts', 0.1);

% Construct Hammerstein-Wiener model using OE model
% as its linear component.
m1 = idnlhw(LinearModel, 'saturation', [])
```

expand all

### Hammerstein-Wiener Model Structure

This block diagram represents the structure of a Hammerstein-Wiener model:

where:

• w(t) = f(u(t)) is a nonlinear function transforming input data u(t). w(t) has the same dimension as u(t).

• x(t) = (B/F)w(t) is a linear transfer function. x(t) has the same dimension as y(t).

where B and F are similar to polynomials in the linear Output-Error model, as described in What Are Polynomial Models?.

For ny outputs and nu inputs, the linear block is a transfer function matrix containing entries:

$\frac{{B}_{j,i}\left(q\right)}{{F}_{j,i}\left(q\right)}$

where j = 1,2,...,ny and i = 1,2,...,nu.

• y(t) = h(x(t)) is a nonlinear function that maps the output of the linear block to the system output.

w(t) and x(t) are internal variables that define the input and output of the linear block, respectively.

Because f acts on the input port of the linear block, this function is called the input nonlinearity. Similarly, because h acts on the output port of the linear block, this function is called the output nonlinearity. If system contains several inputs and outputs, you must define the functions f and h for each input and output signal.

You do not have to include both the input and the output nonlinearity in the model structure. When a model contains only the input nonlinearity f, it is called a Hammerstein model. Similarly, when the model contains only the output nonlinearity h), it is called a Wiener model.

The nonlinearities f and h are scalar functions, one nonlinear function for each input and output channel.

The Hammerstein-Wiener model computes the output y in three stages:

1. Computes w(t) = f(u(t)) from the input data.

w(t) is an input to the linear transfer function B/F.

The input nonlinearity is a static (memoryless) function, where the value of the output a given time t depends only on the input value at time t.

You can configure the input nonlinearity as a sigmoid network, wavelet network, saturation, dead zone, piecewise linear function, one-dimensional polynomial, or a custom network. You can also remove the input nonlinearity.

2. Computes the output of the linear block using w(t) and initial conditions: x(t) = (B/F)w(t).

You can configure the linear block by specifying the numerator B and denominator F orders.

3. Compute the model output by transforming the output of the linear block x(t) using the nonlinear function h: y(t) = h(x(t)).

Similar to the input nonlinearity, the output nonlinearity is a static function. Configure the output nonlinearity in the same way as the input nonlinearity. You can also remove the output nonlinearity, such that y(t) = x(t).

Resulting models are idnlhw objects that store all model data, including model parameters and nonlinearity estimator. See the idnlhw reference page for more information.

### idnlhw States

The toolbox requires states for simulation and prediction using sim(idnlhw), predict, and compare. States are also necessary for linearization of nonlinear ARX models using linearize. The 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 the Hammerstein-Wiener model correspond to the states of the linear block in the Hammerstein-Wiener model structure:

The linear block contains all the dynamic elements of the model. If this linear model is not a state-space structure, the states are defined as those of model Mss, where Mss = idss(Model.LinearModel) and Model is the idnlhw object.