idnlgrey
Nonlinear greybox model
Description
The idnlgrey
object represents a nonlinear greybox model.
For more information about nonlinear greybox models, see Estimate Nonlinear GreyBox Models. Use the idnlgrey
constructor to create a nonlinear greybox 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 greybox 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
Description
creates the nonlinear greybox model sys
= idnlgrey(FileName
,Order
,Parameters
)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.
also specifies the initial states of the model and sets the
sys
= idnlgrey(FileName
,Order
,Parameters
,InitialStates
)InitialStates
property of sys
accordingly.
also specifies the sample time of a discretetime model and sets the
sys
= idnlgrey(FileName
,Order
,Parameters
,InitialStates
,Ts
)Ts
property of sys
accordingly.
sets any sys
= idnlgrey(___,Name=Value
)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 continuoustime 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 continuoustime
systems, the output argument xp
contains the state derivatives with
respect to time, while for discretetime 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, Pcode file, or MEX file.
For more information about creating model files, see Creating IDNLGREY Model Files and Estimate Nonlinear GreyBox 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 outputsNy
, inputsNu
, and statesNx
Structure with fields
Ny
,Nu
, andNx
For time series, Nu
is set to 0
, and for
static model structures, Nx
is set to 0
.
This property is readonly. 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
by1 structure array, whereNp
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'
, wherei
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
Twodimensional 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
by1 vector of real finite initial values,InParameters
.The data is converted into a structure with default values for the fields
Name
,Unit
,Minimum
,Maximum
, andFixed
. TheValue
field of thei
th structure array element is assigned the valueInParameters(i)
, wherei
is an integer in [1,Np
].Np
by1 cell array containing finite real scalars, finite real vectors, or finite real twodimensional matrices of initial values.The data is converted into a structure with default values for the fields
Name
,Unit
,Minimum
,Maximum
, andFixed
. TheValue
field of thei
th structure array element is assigned the valueInParameters{i}
, wherei
is an integer in [1,Np
].
Use dot notation to access the subfields of the i
th parameter.
For example, for an idnlgrey
model M
, you can
access the i
th 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
by1 structure array, whereNx
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'
, wherei
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 1by
Ne
vector, whereNe
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 1by
Ne
vector of the same size asValue
.Minimum
>=Value
for all components.Inf(size(Value))
Maximum
Maximum value of the parameters, specified as a real scalar or 1by
Ne
vector of the same size asValue
.Value
<=Maximum
for all components.Inf(size(Value))
Fixed
Whether initial states are fixed to their initial values, specified as logical scalar or 1by Ne
vector of the same size asValue
.true(size(Value))
This means that no initial state is estimated.
[]
or{}
(this is equivalent to leaving theInitialStates
input argument unspecified).A structure is created with default values for the fields
Name
,Unit
,Minimum
,Maximum
, andFixed
.Value
is assigned the value0
.A real finite
Nx
byNe
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
andUnit
. TheValue
field of thei
th structure array element is assigned toInitStates(i,Ne)
, a row vector withNe
elements.Minimum
,Maximum
, andFixed
are assigned to row vectors of the same size asInitStates(i,Ne)
, with default values ofInf
,Inf
andtrue
.A Cell array containing finite real vectors of size 1by
Ne
. This array is converted into a structure in the same way as a real finiteNx
byNe
, as specified in the previous item in this list.
Use dot notation to access the subfields of the i
th initial
state. For example, for an idnlgrey
model M
, you
can access the i
th 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.  1e6 
FixedStep  Step size used by the solver. Applicable to: Fixedstep timecontinuous solvers. Assignable values:


InitialStep  Specifies the initial step at which the ODE solver starts. Applicable to: Variablestep, timecontinuous solvers. Assignable values:


MaxOrder  Specifies the order of the numerical differentiation formulas (NDF). Applicable to: numerical differentiation formulas
( Assignable values: 1, 2, 3, 4, or 5.  5 
MaxStep  Specifies the largest time step of the ODE solver. Applicable to: Variablestep, timecontinuous solvers. Assignable values:


MinStep  Specifies the smallest time step of the ODE solver. Applicable to: Variablestep, timecontinuous solvers. Assignable values:


RelTol  Relative error tolerance that applies to all components of the state
vector. The estimated error in each integration step satisfies Applicable to: Variablestep, timecontinuous solvers. Assignable value: A positive real value. 
(0.1% accuracy) 
Solver  ODE (Ordinary differential/difference equation) solver for solving state space equations.


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
byny
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 singleinput 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 multiinput models. For
example, if sys
is a twoinput 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 singleinput 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 fiveinput 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 singleoutput 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 multioutput models. For
example, if sys
is a twooutput 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 singleoutput 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 fouroutput 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 readonly.
Summary report that contains information about the estimation options and results
for a statespace 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 greybox model parameters 
sim  Simulate response of identified model 
predict  Predict identified model Kstepahead 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)  Statespace model 
Examples
Create a Nonlinear GreyBox Model
Load data.
load('dcmotordata'); z = iddata(y,u,0.1,'Name','DCmotor');
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 greybox 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','DCmotor');
Selectively Estimate Parameters of Nonlinear GreyBox Model
Load data.
load twotankdata z = iddata(y,u,0.2,'Name','Two tanks');
The data contains 3000 inputoutput 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 twotank 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 = Continuoustime nonlinear greybox model defined by 'twotanks_c' (MEXfile): 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.425e05, MSE: 2.42e05
Version History
Introduced in R2007a
Open Example
You have a modified version of this example. Do you want to open this example with your edits?
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)