idnlgrey

Nonlinear grey-box model

Description

The idnlgrey object represents a nonlinear grey-box model. For more information about nonlinear grey-box models, see Estimate Nonlinear Grey-Box Models. Use the idnlgrey constructor to create a nonlinear grey-box model and then estimate the model parameters using nlgreyest.

The states of an idnlgrey model are defined explicitly in the function or MEX file that defines the model structure. States are required for simulation and prediction of nonlinear grey-box models. The initial values of the states are configured by the InitialStates property of the idnlgrey model. Use findstates to search for state values for simulation and prediction with sim, predict, and compare.

Creation

Syntax

sys = idnlgrey(FileName,Order,Parameters)

sys = idnlgrey(FileName,Order,Parameters,InitialStates)

sys = idnlgrey(FileName,Order,Parameters,InitialStates,Ts)

sys = idnlgrey(___,Name=Value)

Description

sys = idnlgrey(FileName,Order,Parameters) creates the nonlinear grey-box model sys using the model structure specified in FileName, with the number of outputs, inputs, and states specified in Order, and the parameters specified in Parameters. This syntax sets the FileName, Order and Parameters properties of sys to the respective input arguments.

sys = idnlgrey(FileName,Order,Parameters,InitialStates) also specifies the initial states of the model and sets the InitialStates property of sys accordingly.

sys = idnlgrey(FileName,Order,Parameters,InitialStates,Ts) also specifies the sample time of a discrete-time model and sets the Ts property of sys accordingly.

sys = idnlgrey(___,Name=Value) sets any sys property except Order using one or more Name=Value arguments. Use this syntax in combination with any of the input argument combinations in the previous syntaxes.

Properties

FileName — Name of the function or MEX file that stores the model structure

string | character vector | function handle

Name of the function or MEX file storing the model structure, specified as a string, character vector (without the file extension) or function handle. This function computes the updated states (or, for continuous-time models, their derivatives with respect to time) and the outputs. When implemented as a MATLAB^® file, the function must have the following signature.

[xp,y] = mySystem(t,x,u,aux1, ... ,auxN)

Here, the input arguments t, x, and u contain the current time, state and input, respectively. The optional input arguments aux1 to auxN contain auxiliary variables that might be necessary for your calculations. For continuous-time systems, the output argument xp contains the state derivatives with respect to time, while for discrete-time systems it contains the next state.

If FileName is a string or character vector, for example 'twotanks_c', then it must point to a MATLAB file, P-code file, or MEX file.

For more information about creating model files, see Creating IDNLGREY Model Files and Estimate Nonlinear Grey-Box Models.

Example: "dc_motor"

Order — Number of outputs, inputs, and states of the model

vector | structure

Number of outputs, inputs, and states of the model, specified as one of the following:

• Vector [Ny Nu Nx], specifying the number of model outputs Ny, inputs Nu, and states Nx

• Structure with fields Ny, Nu, and Nx

For time series, Nu is set to 0, and for static model structures, Nx is set to 0.

This property is read-only. It cannot be changed after sys is created.

Example: [2 1 2]

Parameters — Parameters of the model

structure | vector | cell array

Parameters of the model, specified as one of the following:

• Np-by-1 structure array, where Np is the number of parameters. The structure contains the following fields:

  Field	Description	Default
  Name	Name of the parameter, specified as a character vector. For example, 'pressure'.	'pi', where i is an integer in [1,Np]
  Unit	Unit of the parameter, specified as a character vector.	''
  Value	Initial value of the parameter, specified as a: Finite real scalar Finite real column vector Two-dimensional real matrix
  Minimum	Minimum value of the parameter, specified as a real scalar, column vector, or matrix of the same size as Value. Minimum >= Value for all components.	-Inf(size(Value))
  Maximum	Maximum value of the parameter, specified as a real scalar, column vector, or matrix of the same size as Value. Value <= Maximum for all components.	Inf(size(Value))
  Fixed	Whether the parameter is fixed to their initial values, specified as a logical scalar, column vector, or matrix of the same size as Value.	false(size(Value)) This means that all parameters are estimated.

• Np-by-1 vector of real finite initial values, InParameters.

  The data is converted into a structure with default values for the fields Name, Unit, Minimum, Maximum, and Fixed. The Value field of the ith structure array element is assigned the value InParameters(i), where i is an integer in [1,Np].

• Np-by-1 cell array containing finite real scalars, finite real vectors, or finite real two-dimensional matrices of initial values.

  The data is converted into a structure with default values for the fields Name, Unit, Minimum, Maximum, and Fixed. The Value field of the ith structure array element is assigned the value InParameters{i}, where i is an integer in [1,Np].

Use dot notation to access the subfields of the ith parameter. For example, for an idnlgrey model M, you can access the ith parameter using M.Parameters(i) and its subfield Fixed using M.Parameters(i).Fixed.

Example: [1 0.2]

InitialStates — Initial states of the model

structure | [] | cell array | {}

Initial states of the model, specified as one of the following:

• Nx-by-1 structure array, where Nx is the number of states. The structure contains the following fields:

  Field	Description	Default
  Name	Name of the states, specified as a character vector.	'xi', where i is an integer in [1,Nx]
  Unit	Unit of the states, specified as a character vector.	''
  Value	Initial value of the initial states, specified as: A finite real scalar A finite real 1-by-Ne vector, where Ne is the number of experiments in the data set to be used for estimation.
  Minimum	Minimum value of the initial states, specified as a real scalar or 1-by-Ne vector of the same size as Value. Minimum >= Value for all components.	-Inf(size(Value))
  Maximum	Maximum value of the parameters, specified as a real scalar or 1-by-Ne vector of the same size as Value. Value <= Maximum for all components.	Inf(size(Value))
  Fixed	Whether initial states are fixed to their initial values, specified as logical scalar or 1-by-Ne vector of the same size as Value.	true(size(Value)) This means that no initial state is estimated.

• [] or {} (this is equivalent to leaving the InitialStates input argument unspecified).

  A structure is created with default values for the fields Name, Unit, Minimum, Maximum, and Fixed.

  Value is assigned the value 0.

• A real finite Nx-by-Ne matrix (InitStates). Here, Ne is the number of experiments in the data set to be used for estimation.

  The data is converted into a structure with default values for the fields Name and Unit. The Value field of the ith structure array element is assigned to InitStates(i,Ne), a row vector with Ne elements. Minimum, Maximum, and Fixed are assigned to row vectors of the same size as InitStates(i,Ne), with default values of -Inf, Inf and true.

• A Cell array containing finite real vectors of size 1-by-Ne. This array is converted into a structure in the same way as a real finite Nx-by-Ne, as specified in the previous item in this list.

Use dot notation to access the subfields of the ith initial state. For example, for an idnlgrey model M, you can access the ith initial state using M.InitialStates(i) and its subfield Fixed using M.InitialStates(i).Fixed.

Example: [0 0]'

Ts — Sample time

0 (default) | nonnegative scalar

Sample time, specified as a nonnegative scalar in units specified by the TimeUnit property. For a continuous time model, Ts is equal to 0 (default).

Changing this property does not discretize or resample the model.

Example: 0

FileArgument — Auxiliary variables for the model structure file

{} (default) | cell array

Auxiliary variables for the model structure file (function or MEX file) specified in FileName, specified as a cell array. These variables are used as extra inputs for specifying the state equations, output equations, or both.

Example: {1,2}

SimulationOptions — Simulation options

structure (default)

The simulation method and related options, specified as a structure containing the following fields:

Field	Description	Default
AbsTol	Absolute error tolerance. This scalar applies to all components of the state vector. Applicable to: Variable step solvers. Assignable value: A positive real value.	1e-6
FixedStep	Step size used by the solver. Applicable to: Fixed-step time-continuous solvers. Assignable values: 'Auto' — Automatically chooses the initial step. A real value such that 0<FixedStep<=1.	'Auto'
InitialStep	Specifies the initial step at which the ODE solver starts. Applicable to: Variable-step, time-continuous solvers. Assignable values: 'Auto' — Automatically chooses the initial step. A positive real value such that MinStep<=InitialStep<=MaxStep.	'Auto'
MaxOrder	Specifies the order of the numerical differentiation formulas (NDF). Applicable to: numerical differentiation formulas (ode15s). Assignable values: 1, 2, 3, 4, or 5.	5
MaxStep	Specifies the largest time step of the ODE solver. Applicable to: Variable-step, time-continuous solvers. Assignable values: 'Auto' — Automatically chooses the time step. A positive real value greater than MinStep.	'Auto'
MinStep	Specifies the smallest time step of the ODE solver. Applicable to: Variable-step, time-continuous solvers. Assignable values: 'Auto' — Automatically chooses the time step. A positive real value less than MaxStep.	'Auto'
RelTol	Relative error tolerance that applies to all components of the state vector. The estimated error in each integration step satisfies |e(i)| <= max(RelTol*abs(x(i)), AbsTol(i)). Applicable to: Variable-step, time-continuous solvers. Assignable value: A positive real value.	1e-3 (0.1% accuracy)
Solver	ODE (Ordinary differential/difference equation) solver for solving state space equations. Variable-step solvers for time-continuous idnlgrey models: 'ode45' — Runge-Kutta (4,5) solver for nonstiff problems 'ode23' — Runge-Kutta (2,3) solver for nonstiff problems 'ode113' — Adams-Bashforth-Moulton solver for nonstiff problems. 'ode15s' — Numerical differential formula solver for stiff problems 'ode23s' — Modified Rosenbrock solver for stiff problems 'ode23t' — Trapezoidal solver for moderately stiff problems 'ode23tb' — Implicit Runge-Kutta solver for stiff problems Fixed-step solvers for time-continuous idnlgrey models: 'ode5' — Dormand-Prince solver. 'ode4' — Fourth-order Runge-Kutta solver. 'ode3' — Bogacki-Shampine solver. 'ode2' — Heun or improved Euler solver. 'ode1' — Euler solver Fixed-step solvers for time-discrete idnlgrey models: 'FixedStepDiscrete' General: 'Auto' — Automatically chooses one of the previous solvers.	'Auto'

TimeVariable — Independent variable

't' (default) | string | character vector

Independent variable for the inputs, outputs, and—when available—internal states, specified as a character vector or string.

Example: "k"

NoiseVariance — Noise variance

identity matrix (default) | matrix

Noise variance (covariance matrix) of the model innovations e, specified as an ny-by-ny matrix. This is typically set automatically by the estimation algorithm.

Example: 0.1*eye(2)

InputName — Names of input channels

{''} (default) | character vector | cell array of character vectors | string | string array

Names of input channels, specified as:

• A character vector or string — For single-input models

• A cell array of character vectors or a string array — For models with two or more inputs

• '' — For inputs without specified names

You can use automatic vector expansion to assign input names for multi-input models. For example, if sys is a two-input model, you can specify InputName as follows.

sys.InputName = 'controls';

The input names automatically expand to {'controls(1)';'controls(2)'}.

You can use the shorthand notation u to refer to the InputName property. For example, sys.u is equivalent to sys.InputName.

Input channel names have several uses, including:

• Identifying channels on model display and plots

• Extracting subsystems of MIMO systems

• Specifying connection points when interconnecting models

If you specify InputName using a string or string array, such as "voltage", the input name is stored as a character vector, 'voltage'.

When you estimate a model using an iddata object, data, the software automatically sets InputName to data.InputName.

InputUnit — Units of input signals

{''} (default) | character vector | cell array of character vectors | string | string array

Units of input signals, specified as:

• A character vector or string — For single-input models

• A cell array of character vectors or string array — For models with two or more inputs

• '' — For inputs without specified units

Use InputUnit to keep track of the units each input signal is expressed in. InputUnit has no effect on system behavior.

If you specify InputUnit using a string, such as "voltage", the input units are stored as a character vector, 'voltage'.

Example: 'voltage'

Example: {'voltage','rpm'}

InputGroup — Input channel groups

structure with no fields (default) | structure

Input channel groups, specified as a structure where the fields are the group names and the values are the indices of the input channels belonging to the corresponding group. When you use InputGroup to assign the input channels of MIMO systems to groups, you can refer to each group by name when you need to access it. For example, suppose you have a five-input model sys, where the first three inputs are control inputs and the remaining two inputs represent noise. Assign the control and noise inputs of sys to separate groups.

sys.InputGroup.controls = [1:3];
sys.InputGroup.noise = [4 5];

Use the group name to extract the subsystem from the control inputs to all outputs.

sys(:,'controls')

Example: struct('controls',[1:3],'noise',[4 5])

OutputName — Names of output channels

{''} (default) | character vector | cell array of character vectors or strings | string | string array

Names of output channels, specified as:

• A character vector or string— For single-output models

• A cell array of character vectors or string array — For models with two or more outputs

• '' — For outputs without specified names

You can use automatic vector expansion to assign output names for multi-output models. For example, if sys is a two-output model, you can specify OutputName as follows.

sys.OutputName = 'measurements';

The output names automatically expand to {'measurements(1)';'measurements(2)'}.

You can use the shorthand notation y to refer to the OutputName property. For example, sys.y is equivalent to sys.OutputName.

Output channel names have several uses, including:

• Identifying channels on model display and plots

• Extracting subsystems of MIMO systems

• Specifying connection points when interconnecting models

If you specify OutputName using a string, such as "rpm", the output name is stored as a character vector, 'rpm'.

When you estimate a model using an iddata object, data, the software automatically sets OutputName to data.OutputName.

OutputUnit — Units of output signals

{''} (default) | character vector | cell array of character vectors | string | string array

Units of output signals, specified as:

• A character vector or string — For single-output models

• A cell array of character vectors or string array — For models with two or more outputs

• '' — For outputs without specified units

Use OutputUnit to keep track of the units each output signal is expressed in. OutputUnit has no effect on system behavior.

If you specify OutputUnit using a string, such as "voltage", the output units are stored as a character vector, 'voltage'.

Example: 'voltage'

Example: {'voltage','rpm'}

OutputGroup — Output channel groups

structure with no fields (default) | structure

Output channel groups, specified as a structure where the fields are the group names and the values are the indices of the output channels belonging to the corresponding group. When you use OutputGroup to assign the output channels of MIMO systems to groups, you can refer to each group by name when you need to access it. For example, suppose you have a four-output model sys, where the second output is a temperature, and the rest are state measurements. Assign these outputs to separate groups.

sys.OutputGroup.temperature = [2];
sys.OutputGroup.measurements = [1 3 4];

Use the group name to extract the subsystem from all inputs to the measurement outputs.

sys('measurements',:)

Example: struct('temperature',[2],'measurement',[1 3 4])

Notes — Text notes about model

[0×1 string] (default) | string | character vector | cell array of character vectors or strings | string array

Text notes about the model, specified as a string or character vector. The property stores whichever of these two data types you provide. For instance, suppose that sys1 and sys2 are dynamic system models. You can set their Notes properties to a string and a character vector, respectively.

sys1.Notes = "sys1 has a string.";
sys2.Notes = 'sys2 has a character vector.';
sys1.Notes
sys2.Notes

ans = 

    "sys1 has a string."


ans =

    'sys2 has a character vector.'

You can also specify Notes as string array or a cell array of character vectors or strings.

UserData — Data associated with model

[] (default) | any data type

Data of any kind that you want to associate and store with the model, specified as any MATLAB data type.

Name — Model name

'' (default) | character vector | string

Model name, stored as a character vector or string. If you specify Name using a string, such as "DCmotor", the string is stored as a character vector, 'DCmotor'.

Example: 'system_1'

TimeUnit — Model time units

'seconds' (default) | 'minutes' | 'milliseconds' | ...

Model time units, specified as:

• 'nanoseconds'

• 'microseconds'

• 'milliseconds'

• 'seconds'

• 'minutes'

• 'hours'

• 'days'

• 'weeks'

• 'months'

• 'years'

If you specify TimeUnit using a string, such as "hours", the time units are stored as a character vector, 'hours'.

Model properties such as sample time Ts, InputDelay, OutputDelay, and other time delays are expressed in the units specified by TimeUnit. Changing this property has no effect on other properties, and therefore changes the overall system behavior. Use chgTimeUnit to convert between time units without modifying system behavior.

Report — Summary report

report field values

This property is read-only.

Summary report that contains information about the estimation options and results for a state-space model obtained using estimation commands. Use Report to find estimation information for the identified model, including the:

• Status (estimated or constructed)

• Estimation method

• Estimation options

• Search termination conditions

• Estimation data fit and other quality metrics

For more information on this property and how to use it, see the Output Arguments section of the corresponding estimation command reference page and Estimation Report.

Object Functions

nlgreyest	Estimate nonlinear grey-box model parameters
sim	Simulate response of identified model
predict	Predict identified model K-step-ahead output
compare	Compare identified model output with measured output
c2d	Convert model from continuous to discrete time
d2c	Convert model from discrete to continuous time
ss (Control System Toolbox)	State-space model

Examples

Create a Nonlinear Grey-Box Model

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];

sys = idnlgrey(file_name,Order,Parameters,InitialStates,0, ...
    'Name','DC-motor');

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

Version History

Introduced in R2007a