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
Description
creates the nonlinear grey-box 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 discrete-time 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 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 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 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, 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
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
, andFixed
. TheValue
field of thei
th structure array element is assigned the valueInParameters(i)
, wherei
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
, 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
-by-1 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 1-by-
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 1-by-
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 1-by-
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 1-by- 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
-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
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 of-Inf
,Inf
andtrue
.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 finiteNx
-by-Ne
, 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. | 1e-6 |
FixedStep | Step size used by the solver. Applicable to: Fixed-step time-continuous solvers. Assignable values:
|
|
InitialStep | Specifies the initial step at which the ODE solver starts. Applicable to: Variable-step, time-continuous 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: Variable-step, time-continuous solvers. Assignable values:
|
|
MinStep | Specifies the smallest time step of the ODE solver. Applicable to: Variable-step, time-continuous 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: Variable-step, time-continuous 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
-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
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)