Documentation

# nlgreyest

Estimate nonlinear grey-box model parameters

## Syntax

``sys= nlgreyest(data,init_sys)``
``sys= nlgreyest(data,init_sys,options)``

## Description

example

````sys= nlgreyest(data,init_sys)` estimates the parameters of a nonlinear grey-box model, `init_sys`, using time-domain data, `data`.```

example

````sys= nlgreyest(data,init_sys,options)` specifies additional model estimation options.```

## Examples

collapse all

```load(fullfile(matlabroot,'toolbox','ident','iddemos','data','twotankdata')); z = iddata(y,u,0.2,'Name','Two tanks');```

The data contains 3000 input-output data samples of a two tank system. The input is the voltage applied to a pump, and the output is the liquid level of the lower tank.

Specify file describing the model structure for a two-tank system. The file specifies the state derivatives and model outputs as a function of time, states, inputs, and model parameters.

`FileName = 'twotanks_c';`

Specify model orders [ny nu nx].

`Order = [1 1 2];`

Specify initial parameters (Np = 6).

```Parameters = {0.5;0.0035;0.019; ... 9.81;0.25;0.016};```

Specify initial initial states.

`InitialStates = [0;0.1];`

Specify as continuous system.

`Ts = 0;`

Create `idnlgrey` model object.

```nlgr = idnlgrey(FileName,Order,Parameters,InitialStates,Ts, ... 'Name','Two tanks');```

Set some parameters as constant.

```nlgr.Parameters(1).Fixed = true; nlgr.Parameters(4).Fixed = true; nlgr.Parameters(5).Fixed = true;```

Estimate the model parameters.

`nlgr = nlgreyest(z,nlgr);`

Create estimation option set for `nlgreyest` to view estimation progress, and to set the maximum iteration steps to 50.

```opt = nlgreyestOptions; opt.Display = 'on'; opt.SearchOptions.MaxIterations = 50;```

```load(fullfile(matlabroot,'toolbox','ident','iddemos','data','dcmotordata')); z = iddata(y,u,0.1,'Name','DC-motor');```

The data is from a linear DC motor with one input (voltage), and two outputs (angular position and angular velocity). The structure of the model is specified by `dcmotor_m.m` file.

Create a nonlinear grey-box model.

```file_name = 'dcmotor_m'; Order = [2 1 2]; Parameters = [1;0.28]; InitialStates = [0;0]; init_sys = idnlgrey(file_name,Order,Parameters,InitialStates,0, ... 'Name','DC-motor');```

Estimate the model parameters using the estimation options.

`sys = nlgreyest(z,init_sys,opt);`

## Input Arguments

collapse all

Time-domain estimation data, specified as an `iddata` object. `data` has the same input and output dimensions as `init_sys`.

If you specify the `InterSample` property of `data` as `'bl'`(band-limited) and the model is continuous-time, the software treats data as first-order-hold (foh) interpolated for estimation.

Constructed nonlinear grey-box model that configures the initial parameterization of `sys`, specified as an `idnlgrey` object. `init_sys` has the same input and output dimensions as `data`. Create `init_sys` using `idnlgrey`.

Estimation options for nonlinear grey-box model identification, specified as an `nlgreyestOptions` option set.

## Output Arguments

collapse all

Nonlinear grey-box model with the same structure as `init_sys`, returned as an `idnlgrey` object. The parameters of `sys` are estimated such that the response of `sys` matches the output signal in the estimation data.

Information about the estimation results and options used is stored in the `Report` property of the model. `Report` has the following fields:

Report FieldDescription
`Status`

Summary of the model status, which indicates whether the model was created by construction or obtained by estimation.

`Method`

Name of the simulation solver and the search method used during estimation.

`Fit`

Quantitative assessment of the estimation, returned as a structure. See Loss Function and Model Quality Metrics for more information on these quality metrics. The structure has the following fields:

FieldDescription
`FitPercent`

Normalized root mean squared error (NRMSE) measure of how well the response of the model fits the estimation data, expressed as a percentage.

`LossFcn`

Value of the loss function when the estimation completes.

`MSE`

Mean squared error (MSE) measure of how well the response of the model fits the estimation data.

`FPE`

Final prediction error for the model.

`AIC`

Raw Akaike Information Criteria (AIC) measure of model quality.

`AICc`

Small sample-size corrected AIC.

`nAIC`

Normalized AIC.

`BIC`

Bayesian Information Criteria (BIC).

`Parameters`

Estimated values of the model parameters. Structure with the following fields:

FieldDescription
`InitialValues`Structure with values of parameters and initial states before estimation.
`ParVector`Value of parameters after estimation.
`Free`

Logical vector specifying the fixed or free status of parameters during estimation

`FreeParCovariance`Covariance of the free parameters.
`X0`Value of initial states after estimation.
`X0Covariance`Covariance of the initial states.

`OptionsUsed`

Option set used for estimation. If no custom options were configured, this is a set of default options. See `nlgreyestOptions` for more information.

`RandState`

State of the random number stream at the start of estimation. Empty, `[]`, if randomization was not used during estimation. For more information, see `rng` in the MATLAB® documentation.

`DataUsed`

Attributes of the data used for estimation — Structure with the following fields:

FieldDescription
`Name`

Name of the data set.

`Type`

Data type — For `idnlgrey` models, this is set to `'Time domain data'`.

`Length`

Number of data samples.

`Ts`

Sample time. This is equivalent to `data.Ts`.

`InterSample`

Input intersample behavior. One of the following values:

• `'zoh'` — Zero-order hold maintains a piecewise-constant input signal between samples.

• `'foh'` — First-order hold maintains a piecewise-linear input signal between samples.

• `'bl'` — Band-limited behavior specifies that the continuous-time input signal has zero power above the Nyquist frequency.

The value of `Intersample` has no effect on estimation results for discrete-time models.

`InputOffset`

Empty, `[]`, for nonlinear estimation methods.

`OutputOffset`

Empty, `[]`, for nonlinear estimation methods.

`Termination`

Termination conditions for the iterative search used for prediction error minimization. Structure with the following fields:

FieldDescription
`WhyStop`

Reason for terminating the numerical search.

`Iterations`

Number of search iterations performed by the estimation algorithm.

`FirstOrderOptimality`

$\infty$-norm of the gradient search vector when the search algorithm terminates.

`FcnCount`

Number of times the objective function was called.

`UpdateNorm`

Norm of the gradient search vector in the last iteration. Omitted when the search method is `'lsqnonlin'` or `'fmincon'`.

`LastImprovement`

Criterion improvement in the last iteration, expressed as a percentage. Omitted when the search method is `'lsqnonlin'` or `'fmincon'`.

`Algorithm`

Algorithm used by `'lsqnonlin'` or `'fmincon'` search method. Omitted when other search methods are used.

For estimation methods that do not require numerical search optimization, the `Termination` field is omitted.