nlgreyest

Estimate nonlinear grey-box model parameters

Syntax

sys= nlgreyest(data,init_sys)

sys= nlgreyest(data,init_sys,options)

Description

sys= nlgreyest(data,init_sys) estimates the parameters of a nonlinear grey-box model, init_sys, using time-domain data data. data can be in the form of a timetable, a comma-separated pair of numeric matrices, or a time-domain iddata object.

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

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, u(t), x(t), p1, ..., p6)
    y(t) = H(t, u(t), x(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';

init_sys — Constructed nonlinear grey-box model

idnlgrey object

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.

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 the following fields: Field Description 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: Field Description 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.
DataUsed	Attributes of the data used for estimation — Structure with the following fields: Field Description 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, returned as a structure with the following fields: Field Description 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.

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