Documentation

# customnet

Custom nonlinearity estimator for nonlinear ARX and Hammerstein-Wiener models

## Syntax

```C=customnet(H) C=customnet(H,PropertyName,PropertyValue) ```

## Description

`customnet` is an object that stores a custom nonlinear estimator with a user-defined unit function. This custom unit function uses a weighted sum of inputs to compute a scalar output.

## Construction

`C=customnet(H)` creates a nonlinearity estimator 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. `g` is significantly nonzero in the interval `[-a a]`. Hammerstein-Wiener models require that your custom nonlinearity have only one input and one output.

`C=customnet(H,PropertyName,PropertyValue)` creates a nonlinearity estimator using property-value pairs defined in customnet Properties.

## customnet Properties

You can include property-value pairs in the constructor to specify the object.

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

```% List all property values get(C) % Get value of NumberOfUnits property C.NumberOfUnits```

You can also use the `set` function to set the value of particular properties. For example:

`set(C, 'LinearTerm', 'on')`
The first argument to `set` must be the name of a MATLAB® variable.

Property NameDescription
`NumberOfUnits`

Integer specifies the number of nonlinearity units in the expansion.
Default=`10`.

For example:

`customnet(H,'NumberOfUnits',5)`
`LinearTerm`

Can have the following values:

• `'on'`—Estimates the vector L in the expansion.

• `'off'`—Fixes the vector L to zero.

For example:

`customnet(H,'LinearTerm','on')`
`Parameters`

A structure containing the parameters in the nonlinear expansion, as follows:

• `RegressorMean`: 1-by-`m` vector containing the means of `x` in estimation data, `r`.

• `NonLinearSubspace`: `m`-by-`q` matrix containing Q.

• `LinearSubspace`: `m`-by-`p` matrix containing P.

• `LinearCoef`: `p`-by-1 vector L.

• `Dilation`: `q`-by-1 matrix containing the values bn.

• `Translation`: 1-by-`n` vector containing the values cn.

• `OutputCoef`: `n`-by-1 vector containing the values an.

• `OutputOffset`: scalar `d`.

Typically, the values of this structure are set by estimating a model with a `customnet` nonlinearity.

` UnitFcn`Stores the function handle that points to the unit function.

## Examples

Define custom unit function and save it in `gaussunit.m`:

```function [f, g, a] = GAUSSUNIT(x) % x: unit function variable % f: unit function value % g: df/dx % a: unit active range (g(x) is significantly % nonzero in the interval [-a a]) % The unit function must be "vectorized": for % a vector or matrix x, the output arguments f and g % must have the same size as x, % computed element-by-element. % GAUSSUNIT customnet unit function example [f, g, a] = gaussunit(x) f = exp(-x.*x); if nargout>1 g = - 2*x.*f; a = 0.2; end```

Use custom networks in `nlarx` and `nlhw` model estimation commands:

```% Define handle to example unit function. H = @gaussunit; % Estimate nonlinear ARX model using % Gauss unit function with 5 units. m = nlarx(Data,Orders,customnet(H,'NumberOfUnits',5));```

## Tips

Use `customnet` to define a nonlinear function $y=F\left(x\right)$, where y is scalar and x is an `m`-dimensional row vector. The unit function is based on the following function expansion with a possible linear term L:

where f is a unit function that you define using the function handle H.

P and Q are `m`-by-`p` and `m`-by-`q` projection matrices, respectively. The projection matrices P and Q are determined by principal component analysis of estimation data. Usually, `p=m`. If the components of x in the estimation data are linearly dependent, then `p<m`. The number of columns of Q, `q`, corresponds to the number of components of `x` used in the unit function.

When used to estimate nonlinear ARX models, `q` is equal to the size of the `NonlinearRegressors` property of the `idnlarx` object. When used to estimate Hammerstein-Wiener models, `m=q=1` and Q is a scalar.

r is a 1-by-`m` vector and represents the mean value of the regressor vector computed from estimation data.

d, a, and c are scalars.

L is a `p`-by-1 vector.

b represents `q`-by-1 vectors.

The function handle of the unit function of the custom net must have the form `[f,g,a] = function_name(x)`. This function must be vectorized, which means that for a vector or matrix `x`, the output arguments `f` and `g` must have the same size as `x` and be computed element-by-element.

## Algorithms

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