# nlhw

Estimate a Hammerstein-Wiener model

## Syntax

• `sys = nlhw(Data,Orders)` example
• `sys = nlhw(Data,Orders,InputNL,OutputNL)` example
• `sys = nlhw(Data,LinModel)` example
• `sys = nlhw(Data,LinModel,InputNL,OutputNL)` example
• `sys = nlhw(Data,sys0)` example
• `sys = nlhw(___,Options)` example

## Description

example

````sys = nlhw(Data,Orders)` creates and estimates a Hammerstein-Wiener model using the estimation data, model orders and delays, and default piecewise linear functions as input and output nonlinearity estimators.```

example

````sys = nlhw(Data,Orders,InputNL,OutputNL)` specifies `InputNL` and `OutputNL` as the input and output nonlinearity estimators, respectively.```

example

````sys = nlhw(Data,LinModel)` uses a linear model to specify the model orders and delays, and default piecewise linear functions for the input and output nonlinearity estimators.```

example

````sys = nlhw(Data,LinModel,InputNL,OutputNL)` specifies `InputNL` and `OutputNL` as the input and output nonlinearity estimators, respectively.```

example

````sys = nlhw(Data,sys0)` refines or estimates the parameters of a Hammerstein-Wiener model, `sys0`, using the estimation data. Use this syntax to:Update the parameters of a previously estimated model to improve the fit to the estimation data. In this case, the estimation algorithm uses the parameters of `sys0` as initial guesses.Estimate the parameters of a model previously created using the `idnlhw` constructor. Prior to estimation, you can configure the model properties using dot notation.```

example

````sys = nlhw(___,Options)` specifies additional model estimation options. Use `Options` with any of the previous syntaxes.```

## Examples

collapse all

### Estimate a Hammerstein-Wiener Model

```load iddata3 m1=nlhw(z3,[4 2 1]); ```

### Estimate a Hammerstein Model with Saturation

```load twotankdata; z = iddata(y,u,0.2,'Name','Two tank system'); z1 = z(1:1000); ```

Create a saturation object with lower limit of 0, and upper limit of 5.

```InputNL = saturation('LinearInterval',[0 5]); ```

Estimate model with no output nonlinearity.

```m = nlhw(z1,[2 3 0],InputNL,[]); ```

### Estimate a Hammerstein-Wiener Model with a Custom Network Nonlinearity

Define custom unit function and save it as `gaussunit.m`.

```function [f, g, a] = GAUSSUNIT(x) [f, g, a] = gaussunit(x) f = exp(-x.*x); if nargout>1 g = - 2*x.*f; a = 0.2; end```

```load twotankdata; z = iddata(y, u, 0.2,'Name','Two tank system'); z1 = z(1:1000); ```

Estimate Hammerstein-Wiener model using the custom Gauss unit function.

```H = @gaussunit; CNetw = customnet(H); m = nlhw(z1,[5 1 3],CNetw,[]);```

### Estimate Default Hammerstein-Wiener Model Using an Input-Output Polynomial Model of OE Structure

Estimate linear OE model.

```load throttledata.mat Tr = getTrend(ThrottleData); Tr.OutputOffset = 15; DetrendedData = detrend(ThrottleData, Tr); opt = oeOptions('Focus','simulation'); LinearModel = oe(DetrendedData,[1 2 1],opt); ```

Estimate Hammerstein-Wiener model using OE model as its linear component and saturation as its output nonlinearity.

```sys = nlhw(ThrottleData,LinearModel,[],'saturation'); ```

### Estimate a Hammerstein-Wiener Model Using `idnlhw` to First Define the Model Properties

`load iddata1;`

Construct a Hammerstein-Winer model using `idnlhw` to define the model properties `'b'` and `'f'`.

```sys0 = idnlhw([2,2,0],[],'wavenet'); sys0.b{1} = [0.8,1]; sys0.f{1} = [1,-1.2,0.5];```

Estimate the model.

`sys = nlhw(z1,sys0);`

Estimate a Hammerstein-Winer model using `nlhw` to define the model properties `'b'` and `'f'`/

`sys2 = nlhw(z1,[2,2,0],[],'wavenet','b',{[0.8,1]},'f',{[1,-1.2,0.5]});`

Compare the two estimated models to see that they are equivalent.

`compare(z1, sys,'g',sys2,'r--');`

### Refine a Hammerstein-Wiener Model Using Successive Calls of `nlhw`

Estimate a Hammerstein-Wiener Model.

```load iddata3 sys = nlhw(z3,[4 2 1],'sigmoidnet','wavenet'); ```

Refine the model, `sys`.

```sys = nlhw(z3,sys); ```

### Estimate Hammerstein-Wiener Model Using an Estimation Option Set

Create estimation option set for `nlhw` to view estimation progress and to set the maximum iteration steps to 50.

```opt = nlhwOptions; opt.Display = 'on'; opt.SearchOption.MaxIter = 50; ```

Load data and estimate the model.

```load iddata3 sys = nlhw(z3,[4 2 1],'sigmoidnet','deadzone',opt); ```

## Input Arguments

collapse all

### `Data` — Time domain data`iddata` object

Time-domain estimation data, specified as an `iddata`

### `Orders` — Order and delays of the linear subsystem transfer function `[nb nf nk]` vector of positive integers | `[nb nf nk]` vector of matrices

Order and delays of the linear subsystem transfer function, specified as a `[nb nf nk]` vector.

Dimensions of `Orders`:

• For a SISO transfer function, `Orders` is a vector of positive integers.

`nb` is the number of zeros plus 1, `nf` is the number of poles, and `nk` is the input delay.

• For a MIMO transfer function with `nu` inputs and `ny` outputs, `Orders` is a vector of matrices.

`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` — Input static nonlinearitystring | nonlinearity estimator object | array of nonlinearity estimator objects or strings

Input static nonlinearity estimator, 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 `[]` or `unitgain` object Unit gain `customnet` object Custom network

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

```InputNL = wavenet; InputNL.NumberOfUnits = 10;```

Alternatively, use the associated input nonlinearity estimator function with Name-Value pair arguments.

`InputNL = wavenet('NumberOfUnits',10);`

For `nu` input channels, you can specify nonlinear estimators individually for each input channel by setting `InputNL` to an `nu`-by-1 array of nonlinearity estimators.

`InputNL = [sigmoidnet('NumberofUnits',5); deadzone([-1,2])]`
To specify the same nonlinearity for all inputs, specify a single input nonlinearity estimator.

### `OutputNL` — Output static nonlinearitystring | nonlinearity estimator object | array of nonlinearity estimator objects

Output static nonlinearity estimator, 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 `[]` or `unitgain` object Unit gain `customnet` object Custom network

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

```OutputNL = sigmoidnet; OutputNL.NumberOfUnits = 10;```

Alternatively, use the associated input nonlinearity estimator function with Name-Value pair arguments.

`OutputNL = sigmoidnet('NumberOfUnits',10);`

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

### `LinModel` — Discrete time linear model`idpoly` | `idss` with `K` = `0` | `idtf`

Discrete-time linear model used to specify the linear subsytem, 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`.

### `sys0` — Hammerstein-Wiener model`idnlhw` object

Hammerstein-Wiener model, specified as an `idnlhw` object. `sys0` can be:

• A model previously created using `idnlhw` to specify model properties.

• A model previously estimated using `nlhw`, that you want to update using a new estimation data set.

You can also refine `sys0` using the original estimation data set. If the previous estimation stopped when the numerical search was stuck at a local minima of the cost function, use `init` to first randomize the parameters of `sys0`. See `sys0.Report.Termination` for search stopping conditions. Using `init` does not guarantee a better solution on further refinement.

### `Options` — Estimation options`nlhwOptions` option set

Estimation options for Hammerstein-Wiener model identification, specified as an `nlhwOptions` option set.

## Output Arguments

collapse all

### `sys` — Estimated Hammerstein-Wiener model`idnlhw` object

Estimated Hammerstein-Wiener model, , returned as an `idnlhw` object. The model is estimated using the specified model orders and delays, input and output nonlinearity estimators, and estimation options.

Information about the estimation results and options used is stored in the model's `Report` property. The contents of `Report` contain the following fields:

Report FieldDescription
`Status`

Summary of the model status, which indicates whether the model was created by construction or obtained by estimation.

`Method`

Estimation command used.

`Fit`

Quantitative assessment of the estimation — Structure with the following fields:

FieldDescription
`FitPercent`

Normalized root mean squared error (NRMSE) measure of how well the response of the model fits the estimation data, expressed as a percentage. See `goodnessOfFit` for more information.

`FPE`

Final prediction error for the model. See `fpe` for more information.

`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.

`MSE`

Mean squared error (MSE) measure of how well the response of the model fits the estimation data. See `goodnessOfFit` for more information.

`Parameters`

Estimated values of the model parameters.

`OptionsUsed`

Option set used for estimation. If no custom options were configured, this is a set of default options. See `nlhwOptions` for more information.

`RandState`

State of the random number stream at the start of estimation. Empty, `[]`, if randomization was not used during estimation.

`DataUsed`

Attributes of the data used for estimation — Structure with the following fields:

FieldDescription
`Name`

Name of the data set.

`Type`

Data type — For `idnlhw` models, this is set to `'Time domain data'`.

`Length`

Number of data samples.

`Ts`

Sample time. This is equivalent to `Data.Ts`.

`InterSample`

Input intersample behavior. One of the following values:

• `'zoh'` — Zero-order hold maintains a piecewise-constant input signal between samples.

• `'foh'` — First-order hold maintains a piecewise-linear input signal between samples.

• `'bl'` — Band-limited behavior specifies that the continuous-time input signal has zero power above the Nyquist frequency.

The value of `Intersample` has no effect on estimation results for discrete-time models.

`InputOffset`

Empty, `[]`, for nonlinear estimation methods.

`OutputOffset`

Empty, `[]`, for nonlinear estimation methods.

`Termination`

Termination conditions for the iterative search used for prediction error minimization — Structure with the following fields:

FieldDescription
`WhyStop`

Reason for terminating the numerical search.

`Iterations`

Number of search iterations performed by the estimation algorithm.

`FirstOrderOptimality`

$\infty$-norm of the gradient search vector when the search algorithm terminates.

`FcnCount`

Number of times the objective function was called.

`UpdateNorm`

Norm of the gradient search vector in the last iteration. The field is omitted when `'lsqnonlin'` is the search method.

`LastImprovement`

Criterion improvement in the last iteration, expressed as a percentage. Omitted when `'lsqnonlin'` is the search method.

`Algorithm`

Algorithm used for `'lsqnonlin'` search method. Omitted when other search methods are used.

For estimation methods that do not require numerical search optimization, the `Termination` field is omitted.