System Identification Toolbox™

customnet

Class representing nonlinearity estimator with user-defined unit function for nonlinear ARX and Hammerstein-Wiener models

Syntax

C=customnet(H) C=customnet(H,Property1,Value1,...PropertyN,ValueN)

Arguments

H

User-defined function handle of the unit function of the custom net.

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 indicates the unit function active range. g is significantly nonzero in the interval [-a a].

Description

customnet is an object that stores a custom nonlinear estimator with a user-defined unit function.

You can use the constructor to create the nonlinearity object, as follows:

C=customnet(H) creates a nonlinearity estimator object with a user-defined unit function using the function handle H.

C=customnet(H,Property1,Value1,...PropertyN,ValueN) creates a nonlinearity estimator using property-value pairs defined in customnet Properties.

Remarks

Use customnet to define a nonlinear function , 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 are 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.

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 Name	Description
`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 `b_k`. `Translation`: 1-by-`n` vector containing the values `c_k`. `OutputCoef`: `n`-by-1 vector containing the values `a_k`. `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

The following code, contained in gaussunit.m, defines a sample unit 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

You typically use custom networks in nlarx and nlhw model estimation commands. For example:

% 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));