# customnet

Custom network function for nonlinear ARX and Hammerstein-Wiener models

## Description

A `customnet` object implements a custom network function, and is a nonlinear mapping function for estimating nonlinear ARX and Nonlinear Hammerstein-Weiner 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, a customnet network 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(Χ\left(t\right)-\overline{X}\right)}^{T}PL+S\left(Χ\left(t\right)\right)$`

Here:

• X(t) is an m-by-1 vector of inputs, or regressors, with mean $\overline{Χ}$.

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

• S(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 S(X) , see More About.

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

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

You can configure the `customnet` 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 = customnet(H)``
``S = customnet(H,numUnits)``
``S = customnet(H,numUnits,UseLinearFcn)``
``S = customnet(H,numUnits,UseLinearFcn,UseOffset)``

### Description

example

````C = customnet(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.```
````S = customnet(H,numUnits)` specifies the number of unit functions `numUnits`.```
````S = customnet(H,numUnits,UseLinearFcn)` specifies whether the function uses a linear function as a subcomponent.```

example

````S = customnet(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 information for signals used for estimation, specified as vectors of m property-specific values, where m is the number of input signals. The `Input` properties for each input signal are as follows:

• `Name` — Names of the input signals, specified as a 1-by-m string or character array, where m is the number of inputs

• `Mean` — Mean of the input signals, specified as a numeric scalar

• `Range` — Ranges of the input signals, specified as a 2-by-m numeric array that contains the minimum and maximum values

Output signal information, specified as property-specific values. The `Output` properties are as follows:

• `Name` — Name of the output signal, specified as a string or a character array

• `Mean` — Mean of the output signal, specified as a numeric scalar

• `Range` — Range of the output signal, specified as 2-by-1 numeric array that contains the minimum and maximum values.

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

• `Minimum` — Minimum bound on `Value`, specified as a 1-by-p vector. If `Minimum` is specified with a finite value and the starting value of `Value` is finite, then the software enforces that minimum bound during model estimation.

• `Maximum` — Maximum bound on `Value`, specified as a 1-by-p vector. If `Maximum` is specified with a finite value and the starting value of `Value` is finite, then the software enforces that maximum bound during model estimation.

• `SelectedInputIndex` — Indices of `customnet` inputs (see `Input.Name`) that are used as inputs to the linear function, specified as an 1-by-nr integer vector, where nr is the number of inputs. For nonlinear ARX models, the `RegressorUsage` property determines these indices. For Hammerstein-Wiener models, `SelectedInputIndex` is always `1`.

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

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

• `Minimum` — Minimum bound on `Value`, specified as a numeric scalar or `–Inf`. If `Minimum` is specified with a finite value and the value of `Value` is finite, then the software enforces that minimum bound during model estimation. The default value is `-Inf`.

• `Maximum` — Maximum bound on `Value`, specified as a numeric scalar or `Inf`. If `Maximum` is specified with a finite value and the starting value of `Value` is finite, then the software enforces that maximum bound during model estimation. The default value is `Inf`.

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

• `SelectedInputIndex` — Indices of `customnet` inputs (see `Input.Name`) that are used as inputs to the nonlinear function, specified as an 1-by-nr integer vector, where nr is the number of inputs. For nonlinear ARX models, the `RegressorUsage` property determines these indices. For Hammerstein-Wiener models, `SelectedInputIndex` is always `1`.

## Examples

collapse all

`load iddata1 z1`

Create a `customnet` object that uses `gaussunit` as the unit function.

```H = @gaussunit; C = customnet(@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 = customnet with properties: UnitFcn: @gaussunit NonlinearFcn: [1×1 nlident.internal.RidgenetFcn] Input: [1×1 idpack.Channel] Output: [1×1 idpack.Channel] LinearFcn: [1×1 nlident.internal.UseProjectedLinearFcn] Offset: [1×1 nlident.internal.ChooseableOffset] ```

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 Standard regressors corresponding to the orders: na = 4, nb = 5, nk = 0 Sample time: 0.1 seconds Status: Estimated using NLARX on time domain data "z1". Fit to estimation data: 0.06041% (prediction focus) FPE: 75.67, MSE: 19.38 ```

`load throttledata`

Create a `customnet` 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 = customnet(@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 Input: [1×1 idpack.Channel] Output: [1×1 idpack.Channel] LinearFcn: [1×1 nlident.internal.UseProjectedLinearFcn] NonlinearFcn: [1×1 nlident.internal.CustomNLFcn] Offset: [1×1 nlident.internal.ChooseableOffset] ```

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: absent Output nonlinearity: Custom Network with 10 units Sample time: 0.01 seconds Status: Estimated using NLHW on time domain data "ThrottleData". Fit to estimation data: 72.35% FPE: 108.1, MSE: 84.36 ```

expand all

## Algorithms

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

## Compatibility Considerations

expand all

Not recommended starting in R2021a

Introduced in R2007a

## Support 평가판 신청