# idCustomNetwork

Custom network function for nonlinear ARX and Hammerstein-Wiener models

## Description

An `idCustomNetwork` object implements a custom network function, and is a nonlinear mapping function for estimating nonlinear ARX and Nonlinear Hammerstein-Wiener models. The mapping function, which is also referred to as a nonlinearity, uses a combination of linear weights, an offset and a nonlinear function to compute its output. The nonlinear function contains custom unit functions that operate on a ridge combination (weighted linear sum) of inputs.

Mathematically, `idCustomNetwork` is a function that maps m inputs X(t) = [x(t1),x2(t),…,xm(t)]T to a scalar output y(t) using the following relationship:

`$y\left(t\right)={y}_{0}+Χ{\left(t\right)}^{T}PL+C\left(Χ\left(t\right)\right)$`

Here:

• X(t) is an m-by-1 vector of inputs, or regressors.

• y0 is the output offset, a scalar.

• P is an m-by-p projection matrix, where m is the number of regressors and is p is the number of linear weights. m must be greater than or equal to p.

• L is a p-by-1 vector of weights.

• C(X) is a sum of dilated and translated custom unit functions. The total number of unit functions is referred to as the number of units n of the network.

For the definition of the unit function term C(X), see More About.

Use `idCustomNetwork` as the value of the `OutputFcn` property of an `idnlarx` model or the `InputNonlinearity` and `OutputLinearity` properties of an `idnlhw` object. For example, specify `idCustomNetwork` when you estimate an `idnlarx` model with the following command.

`sys = nlarx(data,regressors,idCustomNetwork)`
When `nlarx` estimates the model, it essentially estimates the parameters of the `idCustomNetwork` function.

You can configure the `idCustomNetwork` function to disable components and fix parameters. To omit the linear component, set `LinearFcn.Use` to `false`. To omit the offset, set `Offset.Use` to `false`. To specify known values for the linear function and the offset, set their `Value` attributes directly and set the corresponding `Free` attributes to `False`. Use `evaluate` to compute the output of the function for a given vector of inputs.

## Creation

### Syntax

``C = idCustomNetwork(H)``
``C = idCustomNetwork(H,numUnits)``
``C = idCustomNetwork(H,numUnits,UseLinearFcn)``
``C = idCustomNetwork(H,numUnits,UseLinearFcn,UseOffset)``

### Description

example

````C = idCustomNetwork(H)` creates a nonlinear mapping object with a user-defined unit function using the function handle `H`. `H` must point to a function of the form `[f,g,a] = function_name(x)`, where `f` is the value of the function, `g = df/dx`, and `a` indicates the unit function active range `[-a a]` where `g` is significantly nonzero. Hammerstein-Wiener models require that your custom function have only one input and one output.```
````C = idCustomNetwork(H,numUnits)` specifies the number of unit functions `numUnits`.```
````C = idCustomNetwork(H,numUnits,UseLinearFcn)` specifies whether the function uses a linear function as a subcomponent.```

example

````C = idCustomNetwork(H,numUnits,UseLinearFcn,UseOffset)` specifies whether the function uses an offset term y0 parameter.```

### Input Arguments

expand all

Function handle that points to a custom function of the form ```[f,g,a] = function_name(x)```, specified as a function handle. The function that `H` points to must be vectorized. That is, for a vector or matrix x, the output arguments f and g must have the same size as x when computed element by element.

This argument sets the `C.NonlinearFcn.UnitFcn` property.

Number of units, specified as a positive integer. `numUnits` determines the number of custom unit functions.

This argument sets the `C.NonlinearFcn.NumberOfUnits` property.

Option to use the linear function subcomponent, specified as `true` or `false`. This argument sets the value of the `C.LinearFcn.Use` property.

Option to use an offset term, specified as `true` or `false`. This argument sets the value of the `C.Offset.Use` property.

## Properties

expand all

Input signal names for the inputs to the mapping object, specified as a 1-by-m cell array, where m is the number of input signals. This property is determined during estimation.

Output signal name for the output of the mapping object, specified as a 1-by-1 cell array. This property is determined during estimation.

Parameters of the linear function, specified as follows:

• `Use` — Option to use the linear function in the custom network, specified as a scalar logical. The default value is `true`.

• `Value` — Linear weights that compose L', specified as a 1-by-p vector.

• `InputProjection` — Input projection matrix P, specified as an m-by-p matrix, that transforms the detrended input vector of length m into a vector of length p. For Hammerstein-Wiener models, `InputProjection` is equal to `1`.

• `Free` — Option to update entries of `Value` during estimation, specified as a 1-by-p logical vector. The software honors the `Free` specification only if the starting value of `Value` is finite. The default value is `true`.

The software computes the output of `LinearFcn` as ${F}_{L}\left(t\right)=Χ{\left(t\right)}^{T}PL$.

Parameters of the offset term, specified as follows:

• `Use` — Option to use the offset in the custom network, specified as a scalar logical. The default value is `true`.

• `Value` — Offset value, specified as a scalar.

• `Free` — Option to update `Value` during estimation, specified as a scalar logical. The software honors the `Free` specification of `false` only if the value of `Value` is finite. The default value is `true`.

Parameters of the nonlinear function, specified as follows:

• `UnitFcn` — Function handle that points to a custom function of the form `[f,g,a] = function_name(x)`. The function that `UnitFcn` points to must be vectorized. That is, for a vector or matrix x, the output arguments f and g must have the same size as x when computed element by element.

• `NumberOfUnits` — Number of units, specified as a positive integer. `NumberOfUnits` determines the number n of custom functions.

• `Parameters` — Parameters of `idCustomNetwork`, specified as in the following table:

Field NameDescriptionDefault

`InputProjection `

Projection matrix Q, specified as an m-by-q matrix. Q transforms the detrended input vector $\left(X-\overline{X}\right)$ of length m into a vector of length q. Typically, Q has the same dimensions as the linear projection matrix P. In this case, q is equal to p, which is the number of linear weights.

For Hammerstein-Wiener models, `InputProjection ` is equal to `1`.

`[]`
`OutputCoefficient`

custom function output coefficients si, specified as an n-by-1 vector.

`[]`
`Translation`

Translation matrix, specified as an n-by-q matrix of translation row vectors ci.

`[]`
`Dilation`

Dilation coefficients bi, specified as an n-by-1 vector.

`[]`

• `Free` — Option to estimate parameters, specified as a logical scalar. If all the parameters have finite values, such as when the `idCustomNetwork` object corresponds to a previously estimated model, then setting `Free` to `false` causes the parameters of the nonlinear function S(X) to remain unchanged during estimation. The default value is `true`.

## Examples

collapse all

`load iddata1 z1`

Create an `idCustomNetwork` object that uses `gaussunit` as the unit function.

```H = @gaussunit; C = idCustomNetwork(@gaussunit);```

Set properties of `C` using dot notation. Fix the value of the offset to 0.2 and set the number of unit functions to 15.

```C.Offset.Value = 0.2; C.Offset.Free = false; C.NonlinearFcn.NumberOfUnits = 15```
```C = Custom Network Nonlinear Function: Custom Network with 15 units and "gaussunit" unit function Linear Function: uninitialized Output Offset: fixed to 0.2 NonlinearFcn: '<Custom units and their parameters>' LinearFcn: '<Linear function parameters>' Offset: '<Offset parameters>' ```

Create model regressors.

`Reg = linearRegressor([z1.OutputName z1.InputName],{1:4 0:4});`

Estimate the nonlinear ARX model.

`sys = nlarx(z1,Reg,C)`
```sys = Nonlinear ARX model with 1 output and 1 input Inputs: u1 Outputs: y1 Regressors: Linear regressors in variables y1, u1 Output function: Custom Network with 15 units and "gaussunit" unit function Sample time: 0.1 seconds Status: Estimated using NLARX on time domain data "z1". Fit to estimation data: 75.54% (prediction focus) FPE: 4.531, MSE: 1.16 ```

`load throttledata`

Create an `idCustomNetwork` object `C` that uses `gaussunit` as the unit function. Include input arguments that specify 10 units and exclude the linear function and the offset.

```H = @gaussunit; C = idCustomNetwork(@gaussunit,10,false,false)```
```C = Custom Network Nonlinear Function: Custom Network with 10 units and "gaussunit" unit function Linear Function: not in use Output Offset: not in use NonlinearFcn: '<Custom units and their parameters>' LinearFcn: '<Linear function parameters>' Offset: '<Offset parameters>' ```

Estimate the Hammerstein-Wiener Model using orders `[4 4 1]`, no input nonlinearity, and `C` as the output nonlinearity.

`sys = nlhw(ThrottleData,[4 4 1],[],C)`
```sys = Hammerstein-Wiener model with 1 output and 1 input Linear transfer function corresponding to the orders nb = 4, nf = 4, nk = 1 Input nonlinearity: None Output nonlinearity: Custom Network with 10 units and "gaussunit" unit function Sample time: 0.01 seconds Status: Estimated using NLHW on time domain data "ThrottleData". Fit to estimation data: 57.07% FPE: 260.5, MSE: 203.3 ```

expand all

## Algorithms

`idCustomNetwork` uses an iterative search technique for estimating parameters.

## Version History

Introduced in R2007a

expand all