# 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(Χ\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 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

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

S = idCustomNetwork(H,numUnits) specifies the number of unit functions numUnits.

S = idCustomNetwork(H,numUnits,UseLinearFcn) specifies whether the function uses a linear function as a subcomponent.

example

S = 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 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 idCustomNetwork 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 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.

• SelectedInputIndex — Indices of idCustomNetwork 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

Create a customnet 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

Input: 'Function inputs'
Output: 'Function output'
LinearFcn: 'Linear function parameters'
NonlinearFcn: 'Custom units and their 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
List of all regressors

Output function: Custom Network with 15 units
Sample time: 0.1 seconds

Status:
Estimated using NLARX on time domain data "z1".
Fit to estimation data: 76.15% (prediction focus)
FPE: 4.311, MSE: 1.104

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 = 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

Input: 'Function inputs'
Output: 'Function output'
LinearFcn: 'Linear function parameters'
NonlinearFcn: 'Custom units and their 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: absent
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: 76.59%
FPE: 77.49, MSE: 60.47

expand all

## Algorithms

idCustomNetwork uses an iterative search technique for estimating parameters.

## Compatibility Considerations

expand all

Not recommended starting in R2021b

Not recommended starting in R2021a