# nlgreyest

Estimate nonlinear grey-box model parameters

## Description

## Examples

### Selectively Estimate Parameters of Nonlinear Grey-Box Model

Load data.

load 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 level of liquid in 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. For this example, use a MEX file.

`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 states.

InitialStates = [0; 0.1];

Specify model as continuous.

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)

nlgr = Continuous-time nonlinear grey-box model defined by 'twotanks_c' (MEX-file): dx/dt = F(t, x(t), u(t), p1, ..., p6) y(t) = H(t, x(t), u(t), p1, ..., p6) + e(t) with 1 input(s), 2 state(s), 1 output(s), and 3 free parameter(s) (out of 6). Name: Two tanks Status: Estimated using Solver: ode45; Search: lsqnonlin on time domain data "Two tanks". Fit to estimation data: 97.34% FPE: 2.425e-05, MSE: 2.42e-05

### Estimate a Nonlinear Grey-Box Model Using Specific Options

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

load 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

`data`

— Time-domain data

timetable | numeric matrix pair | `iddata`

object

Uniformly sampled estimation data, specified as a timetable, a comma-separated matrix
pair, or an `iddata`

, as the following sections describe.
`data`

has the same input and output dimensions as
`init_sys`

.

By default, the software sets the sample time of the model to the sample time of the estimation data.

#### Timetable

Specify `data`

as a `timetable`

that uses a regularly spaced time vector. `data`

contains variables representing input and output channels..

#### Comma-Separated Matrix Pair

Specify `data`

as a comma-separated pair of numeric matrices that
contain input and output time-domain signal values. Use this `data`

specification only for discrete-time systems.

#### Data Object

Specify data as a time-domain `iddata`

object containing the input and output
signal values.

For more information about working with estimation data types, see Data Domains and Data Types in System Identification Toolbox.

#### Intersample Behavior

If you specify the intersample behavior of `data`

as
`'bl'`

(band-limited) and `init_sys`

is a
continuous-time model, the software treats `data`

as first-order-hold
(`'foh'`

), interpolated for estimation. To specify intersample behavior,
use one of the following methods:

For timetables and numeric matrices, specify

`options`

to include the`InputInterSample`

option. For example, to set the intersample behavior to`'bl'`

, use the following commands:opt = nlgreyestOptions('InputInterSample','bl'); sys = nlgreyest(data,init_sys,opt)

For

`iddata`

objects, specify the intersample behavior by directly specifying`data.InterSample`

with the following command:`data.InterSample = 'bl';`

`options`

— Estimation options

`nlgreyestOptions`

option set

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

option set.

## Output Arguments

`sys`

— Estimated nonlinear grey-box model

`idnlgrey`

object

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 Field | Description | ||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|

`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 these fields. `FitPercent` — Normalized root mean squared error (NRMSE) measure of how well the response of the model fits the estimation data, expressed as the percentage*fitpercent*= 100(1-NRMSE)`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:
| ||||||||||||||||

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

`RandState` | State of the random number stream at the start of estimation. Empty,
| ||||||||||||||||

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

`Termination` | Termination conditions for the iterative search used for prediction error minimization, returned as a structure with these fields. `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 |

For more information, see Estimation Report.

## Version History

**Introduced in R2015a**

### R2022b: Time-domain estimation data is accepted in the form of timetables and matrices

Most estimation, validation, analysis, and utility functions now accept time-domain
input/output data in the form of a single timetable that contains both input and output data
or a pair of matrices that contain the input and output data separately. These functions
continue to accept `iddata`

objects as a data source as well, for
both time-domain and frequency-domain data.

### R2018a: Advanced Options are deprecated for `SearchOptions`

when `SearchMethod`

is `'lsqnonlin'`

Specification of `lsqnonlin`

- related advanced options are deprecated,
including the option to invoke parallel processing when estimating using the
`lsqnonlin`

search method, or solver, in Optimization Toolbox™.

## See Also

`idnlgrey`

| `nlgreyestOptions`

| `generateMATLABFunction`

| `pem`

| `goodnessOfFit`

| `aic`

| `fpe`

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)