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(t₁),x₂(t),…,x_m(t)]^T to a scalar output y(t) using the following relationship:

$y (t) = y_{0} + Χ {(t)}^{T} P L + C (Χ (t))$

Here:

X(t) is an m-by-1 vector of inputs, or regressors.
y₀ 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

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.

example

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.

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

example

Input Arguments

expand all

`H` — Function handle
function handle

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.

`numUnits` — Number of units
`10` (default) | positive integer

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

This argument sets the C.NonlinearFcn.NumberOfUnits property.

`UseLinearFcn` — Option to use linear function
`true` (default) | `false`

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

`UseOffset` — Option to use offset term
`true` (default) | `false`

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

`Inputs` — Input signal names
cell array

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.

`Outputs` — Output signal name
cell array

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

`LinearFcn` — Parameters of linear function
linear function property values (default)

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} (t) = Χ {(t)}^{T} P L$ .

`Offset` — Parameters of offset term
offset property values

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.

`NonlinearFcn` — Parameters of nonlinear function
nonlinear function property values

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 Name	Description	Default

`InputProjection`	Projection matrix Q, specified as an m-by-q matrix. Q transforms the detrended input vector $(X - \bar{X})$ 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 s_i, specified as an n-by-1 vector.	`[]`
`Translation`	Translation matrix, specified as an n-by-q matrix of translation row vectors c_i.	`[]`
`Dilation`	Dilation coefficients b_i, 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

Estimate Nonlinear ARX Model with `idCustomNetwork` as Output Function

Open Live Script

Load the data.

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
  List of all regressors

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.58% (prediction focus)
FPE: 4.519, MSE: 1.157                           

Model Properties

Estimate Hammerstein-Wiener Model with `idCustomNetwork` as Output Nonlinearity

Open Live Script

Load the data.

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                                  

Model Properties

More About

expand all

Custom Nonlinear Function C(X)

The custom nonlinear function is a sum of the dilated and translated unit functions, and is described by the following equation:

$C (X) = \sum_{i = 1}^{n} s_{i} f (X^{T} Q b_{i} + c_{i})$

Here:

Q is an m-by-q projection matrix, where m ≥ q.
s₁, s₂, …, s_n are scalar weights called output coefficients.
b₁, b₂, …, b_n are q-by-1 vectors called dilation coefficients.
c₁, c₂, …, c_n are scalars called translations.
f(z) is a function, also called a unit function, that takes a scalar input and returns a scalar output. Here, z is a scalar of the form b_iX^TQ + c_i.

Algorithms

idCustomNetwork uses an iterative search technique for estimating parameters.

Version History

Introduced in R2007a

expand all

R2022a: Previous `idnlarx` data normalization information moved from mapping object properties to `idnlarx` `Normalization` property

Information related to data normalization was moved from the idCustomNetwork mapping object level to the model level. The Normalization property of the idnlarx model contains the data centering and scaling information that the estimation process computes. In addition, the regressor-selection process for the mapping objects has also moved to the model level. The model now passes the actual regressor names rather than the selection indices to the mapping object, eliminating the need for an index property at the mapping object level.

The following table summarizes the mapping object subproperties that were eliminated. For more information, see the Normalization property of idnlarx.

Main Properties / Subproperties	`Input`	`Output`	`LinearMdl`	`Offset`	`NonlinearMdl`
`Mean`	X	X
`Range`	X	X
`Minimum`			X	X	X
`Maximum`			X	X	X
`SelectedInputIndex`			X		X

R2021b: Use of previous `idnlarx` and `idnlhw` mapping object names is not recommended.

Starting in R2021b, the mapping objects (also known as nonlinearities) used in the nonlinear components of the idnlarx and idnlhw objects have been renamed. The following table lists the name changes.

Pre-R2021b Name	R2021b Name
`wavenet`	`idWaveletNetwork`
`sigmoidnet`	`idSigmoidNetwork`
`treepartition`	`idTreePartition`
`customnet`	`idCustomNetwork`
`saturation`	`idSaturation`
`deadzone`	`idDeadZone`
`pwlinear`	`idPiecewiseLinear`
`poly1d`	`idPolynomial1D`
`unitgain`	`idUnitGain`
`linear`	`idLinear`
`neuralnet`	`idFeedforwardNetwork`

Scripts with the old names still run normally, although they will produce a warning. Consider using the new names for continuing compatibility with newly developed features and algorithms. There are no plans to exclude the use of these object names at this time.

R2021a: Use of previous nonlinearity estimator properties is not recommended

Starting in R2021a, the properties of the mapping objects, previously known as nonlinearity estimators, have been reorganized. These objects, which were renamed in R2021b, are idWaveletNetwork (W), idSigmoidNetwork (S), idTreePartition (T), idCustomNetwork (C), and idLinear (L). The property changes do not apply to idFeedforwardNetwork. The use of the pre-R2021a properties in the following table is discouraged. However, the software still accepts commands that set these properties. There are no plans to exclude such commands at this time.

Pre-R2021a Property	R2021a Property	Applicable Mapping Objects
`NumberOfUnits`	`NonlinearFcn.NumberOfUnits`	W,S,T,C
`LinearTerm`	`LinearFcn.Use`, `Offset.Use`	W,S,C
`Parameters`	Split into three pieces: `LinearFcn.Value` `Offset.Value` `NonlinearFcn.Parameters`	W,S,T,C,L `linear` (L) excludes `NonlinearFcn.Parameters`.
`Options`	`NonlinearFcn.Structure`	W,T

idCustomNetwork

Description

Creation

Syntax

Description

Input Arguments

`H` — Function handle
function handle

`numUnits` — Number of units
`10` (default) | positive integer

`UseLinearFcn` — Option to use linear function
`true` (default) | `false`

`UseOffset` — Option to use offset term
`true` (default) | `false`

Properties

`Inputs` — Input signal names
cell array

`Outputs` — Output signal name
cell array

`LinearFcn` — Parameters of linear function
linear function property values (default)

`Offset` — Parameters of offset term
offset property values

`NonlinearFcn` — Parameters of nonlinear function
nonlinear function property values

Examples

Estimate Nonlinear ARX Model with `idCustomNetwork` as Output Function

Estimate Hammerstein-Wiener Model with `idCustomNetwork` as Output Nonlinearity

More About

Custom Nonlinear Function C(X)

Algorithms

Version History

R2022a: Previous `idnlarx` data normalization information moved from mapping object properties to `idnlarx` `Normalization` property

R2021b: Use of previous `idnlarx` and `idnlhw` mapping object names is not recommended.

R2021a: Use of previous nonlinearity estimator properties is not recommended

See Also

Topics

idCustomNetwork

Description

Creation

Syntax

Description

Input Arguments

H — Function handle function handle

numUnits — Number of units 10 (default) | positive integer

UseLinearFcn — Option to use linear function true (default) | false

UseOffset — Option to use offset term true (default) | false

Properties

Inputs — Input signal names cell array

Outputs — Output signal name cell array

LinearFcn — Parameters of linear function linear function property values (default)

Offset — Parameters of offset term offset property values

NonlinearFcn — Parameters of nonlinear function nonlinear function property values

Examples

Estimate Nonlinear ARX Model with idCustomNetwork as Output Function

Estimate Hammerstein-Wiener Model with idCustomNetwork as Output Nonlinearity

More About

Custom Nonlinear Function C(X)

Algorithms

Version History

R2022a: Previous idnlarx data normalization information moved from mapping object properties to idnlarx Normalization property

R2021b: Use of previous idnlarx and idnlhw mapping object names is not recommended.

R2021a: Use of previous nonlinearity estimator properties is not recommended

See Also

Topics

`H` — Function handle
function handle

`numUnits` — Number of units
`10` (default) | positive integer

`UseLinearFcn` — Option to use linear function
`true` (default) | `false`

`UseOffset` — Option to use offset term
`true` (default) | `false`

`Inputs` — Input signal names
cell array

`Outputs` — Output signal name
cell array

`LinearFcn` — Parameters of linear function
linear function property values (default)

`Offset` — Parameters of offset term
offset property values

`NonlinearFcn` — Parameters of nonlinear function
nonlinear function property values

Estimate Nonlinear ARX Model with `idCustomNetwork` as Output Function

Estimate Hammerstein-Wiener Model with `idCustomNetwork` as Output Nonlinearity

R2022a: Previous `idnlarx` data normalization information moved from mapping object properties to `idnlarx` `Normalization` property

R2021b: Use of previous `idnlarx` and `idnlhw` mapping object names is not recommended.