sigmoidnet

Sigmoid network function for nonlinear ARX and Hammerstein-Wiener models

Description

A sigmoidnet object implements a sigmoid 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 sigmoid unit functions that operate on a ridge combination (weighted linear sum) of inputs.

Mathematically, a sigmoidnet network 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+{({\rm X}(t)-\overline{X})}^{T}PL+S({\rm X}(t))$$

Here:

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

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

• S(X) is a sum of dilated and translated sigmoid functions. The total number of sigmoid functions is referred to as the number of units n of the network.

For the definition of the sigmoid function term S(X) , see More About.

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

sys = nlarx(data,regressors,sigmoidnet)

When nlarx estimates the model, it essentially estimates the parameters of the sigmoidnet function.

You can configure the sigmoidnet 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

S = sigmoidnet

S = sigmoidnet(numUnits)

S = sigmoidnet(numUnits,UseLinearFcn)

S = sigmoidnet(numUnits,UseLinearFcn,UseOffset)

Description

S = sigmoidnet creates a sigmoidnet object S that uses 10 units. The number of inputs is determined during model estimation and the number of outputs is 1.

S = sigmoidnet(numUnits) specifies the number of sigmoid functions numUnits.

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

S = sigmoidnet(numUnits,UseLinearFcn,UseOffset) specifies whether the function uses an offset term y₀ parameter.

Input Arguments

numUnits — Number of units

10 (default) | positive integer

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

This argument sets the S.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 S.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 S.Offset.Use property.

Properties

Input — Input signal information

signal property values

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 — Output signal information

signal property 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 a 2-by-1 numeric array that contains the minimum and maximum values

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 sigmoid 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 sigmoidnet inputs (see Input.Name) that are used as inputs to the linear function, specified as an 1-by-n_r integer vector, where n_r is the number of inputs. For nonlinear ARX models, the RegressorUsage property determines these indices. For Hammerstein-Wiener models, SelectedInputIndex is always 1.

Offset — Parameters of offset term

offset property values

Parameters of the offset term, specified as follows:

• Use — Option to use the offset in the sigmoid 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.

NonlinearFcn — Parameters of nonlinear function

nonlinear function property values

Parameters of the nonlinear function, specified as follows:

• NumberOfUnits — Number of units, specified as a positive integer. NumberOfUnits determines the number of sigmoid functions.

• Parameters — Parameters of sigmoidnet, 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-\overline{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	Sigmoid 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 sigmoidnet 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 sigmoidnet inputs (see Input.Name) that are used as inputs to the nonlinear function, specified as an 1-by-n_r integer vector, where n_r is the number of inputs. For nonlinear ARX models, the RegressorUsage property determines these indices. For Hammerstein-Wiener models, SelectedInputIndex is always 1.

Examples

Estimate Nonlinear ARX Model with sigmoidnet as Output Function

Load the data z7 and create a subset to use as estimation data.

load iddata7 z7
ze = z7(1:300);

Create and configure a sigmoidnet mapping object. Fix the offset to 0.2 and the number of units to 15.

S = sigmoidnet;
S.Offset.Value = 0.2;
S.Offset.Free = false;
S.NonlinearFcn.NumberOfUnits = 15;

Create linear and polynomial model regressors. Use the input and output variable names from z7 as the variable names for the regressors.

var_names = [z7.OutputName;z7.InputName]

var_names = 3×1 cell
    {'y1'}
    {'u1'}
    {'u2'}

Reg1 = linearRegressor(var_names,{1:4,0:4,1});
Reg2 = polynomialRegressor(var_names,{1:2,0:2,0},2);

Set the estimation options.

opt = nlarxOptions('SearchMethod','fmincon');
opt.SearchOptions.MaxIterations = 40;

Estimate the nonlinear ARX model.

sys = nlarx(ze,[Reg1;Reg2],S,opt)

sys = 
Nonlinear ARX model with 1 output and 2 inputs
  Inputs: u1, u2
  Outputs: y1

Regressors:
  1. Linear regressors in variables y1, u1, u2
  2. Order 2 regressors in variables y1, u1, u2
  List of all regressors

Output function: Sigmoid Network with 15 units

Sample time: 1 seconds

Status:                                          
Estimated using NLARX on time domain data "ze".  
Fit to estimation data: 72.23% (prediction focus)
FPE: 7.115, MSE: 0.7625

Estimate Hammerstein-Wiener Model that Uses sigmoidnet

Estimate a Hammerstein-Wiener model that uses sigmoidnet as the output nonlinearity.

Load the data

load throttledata

Create a sigmoidnet mapping object that has 15 units and that has no input nonlinearity or offset.

S = sigmoidnet(15,false,false)

S = 
Sigmoid Network

 Nonlinear Function: Sigmoid network with 15 units.
 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.RidgenetFcn]
          Offset: [1×1 nlident.internal.ChooseableOffset]

Estimate a Hammerstein-Wiener model.

sys = nlhw(ThrottleData,[4 4 1],[],S)

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: Sigmoid Network with 15 units
Sample time: 0.01 seconds

Status:                                                 
Estimated using NLHW on time domain data "ThrottleData".
Fit to estimation data: 72.91%                          
FPE: 114.9, MSE: 80.96

More About

Sigmoid Nonlinear Function S(X)

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

$$S(X)={\displaystyle \sum _{i=1}^n{s}_i}f({(X-\overline{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)=\frac{1}{e^{-z}+1}.$$ is the sigmoid function, also called a unit function of the sigmoid network. Here, z is a scalar of the form b_i$$(X-\overline{X})$$^TQ + c_i.

Algorithms

sigmoidnet uses an iterative search technique for estimating parameters.

Compatibility Considerations

Use of previous nonlinearity estimator properties is not recommended

Not recommended starting in R2021a

Starting in R2021a, the properties of the mapping objects, previously known as nonlinearity estimators, have been reorganized. These objects are wavenet (W), sigmoidnet (S), treepartition (T), customnet (C), and linear (L). The property changes do not apply to neuralnet. 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