idgrey

Linear ODE (grey-box model) with identifiable parameters

Description

An idgrey model represents a linear system as a continuous-time or discrete-time state-space model with identifiable (estimable) coefficients. Use an idgrey model when you want to capture complex relationships, constraints, and prior knowledge that structured state-space (idss) models cannot encapsulate. To create an idgrey model, you must know explicitly the system of equations (ordinary differential or difference equations) that govern the system dynamics.

An idgrey model allows you to incorporate conditions such as the following:

Parameter constraints that the idss/ssest framework cannot handle, such as linear or equality constraints on parameters, or prior knowledge about the variance of the states, inputs, outputs, or any combination of the three, that you want to include as known information
A linear model of an arbitrary form, such as a transfer function or polynomial model, with parameter constraints such as a known DC gain, limits on pole locations, a shared denominator across multiple inputs, or nonzero input/output delays in MIMO models
Differential or difference equations with known and unknown coefficients

In these and similar cases, you can create an ODE (ordinary differential or difference equation) function in MATLAB^® that implements a state-space realization of the linear model and that specifies constraints and prior knowledge.

A simple example of creating an ODE for idgrey uses the following equations to describe motor dynamics.

$\begin{array}{l} \dot{x} (t) = [\begin{matrix} 0 & 1 \\ 0 & - \frac{1}{τ} \end{matrix}] x (t) + [\begin{matrix} 0 \\ \frac{G}{τ} \end{matrix}] u (t) \\ y (t) = [\begin{matrix} 1 & 0 \\ 0 & 1 \end{matrix}] x (t) \end{array}$

In these equations, τ is the single estimable parameter and G represents the known static gain.

These equations fit the state-space form:

$\begin{array}{l} \dot{x} (t) = A x (t) + B u (t) \\ y (t) = C x (t) \end{array}$

For this case, both the A and B matrices contain the estimable parameter τ, and B also includes the known gain G. You can write a MATLAB function that accepts τ and G as input arguments and returns the state-space matrices A, B, and C as its output arguments. For example, you can code a function motorFcn as follows.

function [A,B,C] = motorFcn(tau,G)
% ODE function for computing state-space matrices as functions of parameters
A = [0 1; 0 -1/tau];
B = [0; G/tau];
C = eye(2);

After creating a function such as motorFcn, create an idgrey model by specifying that function as the value of its odefun input argument, as the following command shows.

sys = idgrey(@motorFcn,tau0,'c',G)

Here, tau0 is the initial guess for the parameter τ and G specifies the fixed constant. Additionally, 'c' indicates to idgrey that odefun returns matrices corresponding to a continuous-time system. For more information, see function_type.

For an executable example that creates an idgrey model from these motor dynamics equations, see Create Grey-Box Model with Estimable Parameters.

More generally, the following equations describe state-space forms for continuous-time and discrete-time systems.

A state-space model of a system with input vector u, output vector y, and disturbance e, takes the following form in continuous time:

$\begin{array}{l} \dot{x} (t) = A x (t) + B u (t) + K e (t) \\ y (t) = C x (t) + D u (t) + e (t) \\ x (0) = x 0 \end{array}$

In discrete time, the state-space model takes the form:

$\begin{array}{l} x [k + 1] = A x [k] + B u [k] + K e [k] \\ y [k] = C x [k] + D u [k] + e [k] \\ x [1] = x 0 \end{array}$

Your MATLAB ODE function incorporates the user-defined parameters into the A, B, C, and D matrices that the function returns. The associated idgrey model references this function, and the estimation functions greyest and pem use these matrix definitions when estimating the parameters.

For more information on creating an ODE function for idgrey, see Estimate Linear Grey-Box Models.

Creation

Create an idgrey model using the idgrey command. To do so, write a MATLAB function that returns the A, B, C, and D matrices for given values of the estimable parameters and sample time. You can pass additional input arguments, such as a time constant or gain, that are not parameters but that the ODE uses in the expressions for the output arguments.

In addition to the A, B, C, and D matrices, your MATLAB function can return the K matrix if you want the K values to be functions of your input parameters. Your function can also return the initial state vector x0. However, the alternative and recommended approach for parameterizing x0 is to use the InitialState estimation option of greyestOptions.

Note that you can write your ODE function to represent either the continuous time dynamics or the discrete-time dynamics regardless of the nature of the idgrey model itself. For example, you can specify a discrete-time idgrey model (sys.Ts>0) that uses a continuous-time parameterization of the ODE function. Similarly, you can specify a discrete-time parameterization of the ODE function and use it with a continuous-time idgrey model (sys.Ts=0). The idgrey input argument fcn_type informs the idgrey model what type of parameterization the ODE function uses. For more information, see Estimate Linear Grey-Box Models.

Use the estimating functions pem or greyest to obtain estimated values for the unknown parameters of an idgrey model. Unlike other estimation functions such as ssest, which can create a new model object, greyest can estimate parameters only for an idgrey model that already exists and is specified as an input argument. You can access estimated parameters using sys.Structures.Parameters, where sys is an idgrey model.

You can convert an idgrey model into other dynamic systems, such as idpoly, idss, tf, or ss. You cannot convert a dynamic system into an idgrey model.

Syntax

sys = idgrey(odefun,parameters,fcn_type)

sys = idgrey(odefun,parameters,fcn_type,extra_args)

sys = idgrey(odefun,parameters,fcn_type,extra_args,Ts)

sys = idgrey(odefun,parameters,fcn_type,extra_args,Ts,Name,Value)

Description

sys = idgrey(odefun,parameters,fcn_type) creates a linear grey-box model sys with identifiable parameters. odefun specifies the user-defined function that relates the model parameters parameters to their state-space representation. fcn_type specifies whether the model is parameterized in continuous-time, discrete-time, or both.

example

sys = idgrey(odefun,parameters,fcn_type,extra_args) specifies additional arguments extra_args that odefun requires.

example

sys = idgrey(odefun,parameters,fcn_type,extra_args,Ts) specifies the sample time Ts.

example

sys = idgrey(odefun,parameters,fcn_type,extra_args,Ts,Name,Value) incorporates additional options specified by one or more name-value arguments.

example

Input Arguments

expand all

`odefun` — MATLAB function
function handle | character array | string

MATLAB function (.m, .p, or .mex* file) that relates the model parameters parameters to their state-space representation, specified as a function handle or as a character array or string that contains the name of the function. As an option, odefun can also relate the model parameters to the disturbance matrix and initial states. For information about creating the ODE function, see Estimate Linear Grey-Box Models. The parameters that the ODE function defines are the same parameters that you specify in the parameters input argument to idgrey.

If odefun is not on the MATLAB path, then specify the full file name, including the path.

If odefun does not return the disturbance matrix K and the initial state values x0, then these values are not estimable parameters in the idgrey object. Instead, during estimation, the software determines these values using the DisturbanceModel and InitialState estimation options, respectively. You can fix the value of K to zero by setting the DisturbanceModel option to 'none'. Doing so generally provides the best match between the simulation results and the measured data. For more information about the K values, see K. For more information about the estimation options, see greyestOptions.

The idgrey model stores the ODE function name or handle in the sys.Structures.Function property.

For more information on creating an ODE function, see Estimate Linear Grey-Box Models.

`parameters` — Initial values of parameters
cell array | matrix

Initial values of the parameters required by odefun, specified as a cell array or a matrix:

If your model requires multiple parameters, parameters must be a cell array.
If your model requires only a single parameter, which itself might be a vector or a matrix, parameters can be a matrix.

You can also specify parameter names using an N-by-2 cell array, where N is the number of parameters. The first column specifies the names, and the second column specifies the values of the parameters.

For instance, the following command specifies parameters named 'mass', 'stiffness', and 'damping'.

parameters = {'mass',par1;'stiffness',par2;'damping',par3}

For an example of configuring parameters, see Configure Estimable Parameter of Grey-Box Model.

The idgrey model stores the estimated parameters in the sys.Structures.Parameters property.

`fcn_type` — Function type
`'c'` | `'d'` | `'cd'`

Function type that indicates whether the model is parameterized in continuous-time, discrete-time, or both, specified as a character array or string that contains one of the following values:

'c' — odefun returns matrices corresponding to a continuous-time system, regardless of the value of Ts.
'd' — odefun returns matrices corresponding to a discrete-time system, whose values might or might not depend on the value of Ts.
'cd' — odefun returns matrices corresponding to a continuous-time system if Ts = 0 or a discrete time system if Ts > 0.
If Ts > 0, select 'cd' rather than 'd' when you want the software to sample your model using the values returned by odefun rather using the software’s internal sample time conversion routines.

For an example of setting this argument, see Create Grey-Box Model with Estimable Parameters.

The idgrey model stores the function type in the sys.Structures.FunctionType property.

`extra_args` — Extra arguments
`{}` (default) | cell array

Extra input arguments that are required by odefun, specified as a cell array. If odefun does not require extra input arguments, specify extra_args as {}.

For an example of using this argument, see Create Grey-Box Model with Estimable Parameters.

Properties

expand all

`A,B,C,D` — Values of state-space matrices
matrices

This property is read-only.

Values of the state-space matrices that the ODE function represented by odefun returns, specified as the following:

A — State matrix A, an Nx-by-Nx matrix, where Nx is the number of states.
B — Input-to-state matrix B, an Nx-by-Nu matrix, where Nu is the number of inputs.
C — State-to-output matrix C, an Ny-by-Nx matrix, where Ny is the number of outputs.
D — Feedthrough matrix D, an Ny-by-Nu matrix.

For an example of this property, see Create Grey-Box Model with Estimable Parameters.

`K` — Value of state disturbance matrix K
matrix

Values of the state disturbance matrix K, specified as an Nx-by-Ny matrix, where Nx is the number of states and Ny is the number of outputs.

If odefun parameterizes the K matrix, then K has the value returned by odefun. odefun parameterizes the K matrix if it returns at least five outputs and the value of the fifth output does not contain NaN values.
If odefun does not parameterize the K matrix, then K is a zero matrix. The zero value is treated as a fixed value of the K matrix during estimation. To make the value of K estimable, use the DisturbanceModel estimation option.
Regardless of whether the K matrix is parameterized by odefun or not, you can set the values of the K property explicitly. The specified value is treated as a fixed value of the K matrix during estimation. To make the value estimable, use the DisturbanceModel estimation option.

To create an estimation option set for idgrey models, use greyestOptions.

`StateName` — State names
`{''}` (default) | character vector | cell array of character vectors | string | string array

State names, specified as:

A character vector or string — For first-order models
A cell array of character vectors or string array — For models with two or more states
'' — For unnamed states

If you specify StateName using a string, such as "velocity", the state name is stored as a character vector, 'velocity'.

Example: 'velocity'

Example: {'x1','x2'}

`StateUnit` — State units
`{''}` (default) | character vector | cell array of character vectors or stings | string | string array

State units, specified as:

A character vector or string — For first-order models
A cell array of character vectors or string array — For models with two or more states
'' — For states without specified units

Use StateUnit to keep track of the units each state is expressed in. StateUnit has no effect on system behavior.

If you specify StateUnit using a string, such as "mph", the state units are stored as a character vector, 'mph'.

Example: 'mph'

Example: {'rpm','rad/s'}

`Structure` — Information about estimable parameters
`LinearODE` structure

Information about the estimable parameters of the idgrey model, specified as a LinearODE structure.

Structure.Function — Name or function handle of the MATLAB function used to create the idgrey model.
Structure.FunctionType — Indicates whether the model is parameterized in continuous-time, discrete-time, or both.
Structure.Parameters — Information about the estimated parameters. Structure.Parameters contains the following fields:
- Value — Parameter values. For example, sys.Structure.Parameters(2).Value contains the initial or estimated values of the second parameter.
  NaN represents unknown parameter values.
- Minimum — Minimum value that the parameter can assume during estimation. For example, sys.Structure.Parameters(1).Minimum = 0 constrains the first parameter to be greater than or equal to zero.
- Maximum — Maximum value that the parameter can assume during estimation.
- Free — Boolean value specifying whether the parameter is estimable. If you want to fix the value of a parameter during estimation, set Free = false for the corresponding entry.
- Scale — Scale of the parameter’s value. Scale is not used in estimation.
- Info — Structure array for storing parameter units and labels. The structure has Label and Unit fields.
  Specify parameter units and labels as character vectors. For example, 'Time'.
Structure.ExtraArguments — Extra input arguments the ODE function requires.
Structure.StateName — Names of the model states.
Structure.StateUnit — Units of the model states.

`Noise Variance` — Noise variance of model innovations
scalar | matrix

Noise variance of the model innovations e, specified as a scalar or a covariance matrix. For SISO models, NoiseVariance is a scalar. For MIMO models, NoiseVariance is an Ny-by-Ny matrix, where Ny is the number of outputs in the system.

An identified model includes a white, Gaussian noise component, e(t). NoiseVariance is the variance of this noise component. Typically, the model estimation function (such as greyest or pem) determines this variance.

`Report` — Summary report
report field values

This property is read-only.

Summary report that contains information about the estimation options and results when the grey-box model is obtained using the greyest estimation command. Use Report to query a model for how it was estimated, including its:

Estimation method
Estimation options
Search termination conditions
Estimation data fit and other quality metrics

The contents of Report are irrelevant if the model was created by construction.

odefun = 'motorDynamics';
m = idgrey(odefun,1,'cd',0.25,0);
m.Report.OptionsUsed

ans =

     []

If you obtain the grey-box model using estimation commands, the fields of Report contain information on the estimation data, options, and results.

load(fullfile(matlabroot,'toolbox','ident','iddemos','data','dcmotordata'));
data = iddata(y,u,0.1,'Name','DC-motor');
odefun = 'motorDynamics';
init_sys = idgrey('motorDynamics',1,'cd',0.25,0);
m = greyest(data,init_sys);
m.Report.OptionsUsed

InitialState: 'auto'
    DisturbanceModel: 'auto'
               Focus: 'prediction'
  EstimateCovariance: 1
             Display: 'off'
         InputOffset: []
        OutputOffset: []
      Regularization: [1x1 struct]
        OutputWeight: []
        SearchMethod: 'auto'
       SearchOptions: [1x1 idoptions.search.identsolver]
            Advanced: [1x1 struct]

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.

`InputDelay` — Delay at inputs
0 (default) | scalar | vector

Delay at each input, specified as a scalar or a vector. For a system with Nu inputs, set InputDelay to an Nu-by-1 vector. Each entry of this vector is a numerical value that represents the input delay for the corresponding input channel. For continuous-time models, specify input delays in the time unit stored in the TimeUnit property of the model object. For discrete-time models, specify input delays in integer multiples of the sample time Ts. For example, InputDelay = 3 means a delay of three sample times.

Set InputDelay to a scalar value to apply the same delay to all channels.

`OutputDelay` — Output delays
0 (default)

For identified systems like idgrey, OutputDelay is fixed to zero.

`Ts` — Sample time
`0` | `-1` | positive scalar

Sample time, specified as one of the following.

Continuous-time model — 0
Discrete-time model with a specified sampling time — Positive scalar representing the sampling period expressed in the unit specified by the TimeUnit property of the model
Discrete-time model with unspecified sample time — -1

For idgrey models, Ts has no unique default value. Ts depends on the value of fcn_type.

Changing this property does not discretize or resample the model. Use c2d and d2c to convert between continuous- and discrete-time representations. Use d2d to change the sample time of a discrete-time system.

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

`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])

`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'

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

`SamplingGrid` — Sampling grid for model arrays
structure with no fields (default) | structure

Sampling grid for model arrays, specified as a structure. For arrays of identified linear (IDLTI) models that are derived by sampling one or more independent variables, this property tracks the variable values associated with each model. This information appears when you display or plot the model array. Use this information to trace results back to the independent variables.

Set the field names of the data structure to the names of the sampling variables. Set the field values to the sampled variable values associated with each model in the array. All sampling variables should be numeric and scalar valued, and all arrays of sampled values should match the dimensions of the model array.

For example, if you collect data at various operating points of a system, you can identify a model for each operating point separately and then stack the results together into a single system array. You can tag the individual models in the array with information regarding the operating point:

nominal_engine_rpm = [1000 5000 10000];
sys.SamplingGrid = struct('rpm', nominal_engine_rpm)

where sys is an array containing three identified models obtained at rpms 1000, 5000 and 10000, respectively.

For model arrays generated by linearizing a Simulink^® model at multiple parameter values or operating points, the software populates SamplingGrid automatically with the variable values that correspond to each entry in the array. For example, the Simulink Control Design™ commands linearize (Simulink Control Design) and slLinearizer (Simulink Control Design) populate SamplingGrid in this way.

Object Functions

For information about functions that are applicable to an idgrey object, see Linear Grey-Box Models.

Examples

collapse all

Create Grey-Box Model with Estimable Parameters

Open Live Script

Create and configure an idgrey model that incorporates an ODE function with one estimable parameter.

This example uses the shipped file motorDynamics.m, which represents the linear dynamics of a DC motor in the following form:

$\begin{array}{l} \dot{x} (t) = [\begin{array}{c} 0 & 1 \\ 0 & - \frac{1}{τ} \end{array}] x (t) + [\begin{array}{c} 0 \\ \frac{G}{τ} \end{array}] u (t) \\ y (t) = [\begin{array}{c} 1 & 0 \\ 0 & 1 \end{array}] x (t) \end{array}$

motorDynamics returns the $A$ , $B$ , $C$ , and $D$ matrices and explicitly sets the elements of the $K$ matrix and the initial conditions $X0$ to 0. motorDynamics defines the motor time constant $τ$ as the single estimable parameter. The model also includes an auxiliary argument $G$ that represents the known static gain. If you want to view the code for this model, enter edit motorDynamics at the command line.

Initialize $τ$ to 1 by setting the value of the parameters single-element matrix to 1. Set fcn_type to 'cd' to specify that odefun can return either continuous-time (Ts=0) or discrete-time representation (Ts>0). Set extra_args, which represents $G$ , to 0.25. Set the sample time Ts to 0.

odefun = 'motorDynamics';
parameters = 1;
fcn_type = 'cd';
extra_args = 0.25; 
Ts = 0;

Create the idgrey model sys.

sys = idgrey(odefun,parameters,fcn_type,extra_args,Ts)

sys =
  Continuous-time linear grey box model defined by "motorDynamics" function:
      dx/dt = A x(t) + B u(t) + K e(t)
       y(t) = C x(t) + D u(t) + e(t)
 
  A = 
       x1  x2
   x1   0   1
   x2   0  -1
 
  B = 
         u1
   x1     0
   x2  0.25
 
  C = 
       x1  x2
   y1   1   0
   y2   0   1
 
  D = 
       u1
   y1   0
   y2   0
 
  K = 
       y1  y2
   x1   0   0
   x2   0   0
 
  Model parameters:
   Par1 = 1
 
Parameterization:
   ODE Function: motorDynamics
   (parametrizes both continuous- and discrete-time equations)
   Disturbance component: parameterized by the ODE function
   Initial state: parameterized by the ODE function
   Number of free coefficients: 1
   Use "getpvec", "getcov" for parameters and their uncertainties.

Status:                                                         
Created by direct construction or transformation. Not estimated.

To refine the estimate for $τ$ , use pem or greyest.

Configure Estimable Parameter of Grey-Box Model

Open Script

Specify the known parameters of a grey-box model as fixed for estimation. Also specify a minimum bound for an estimable parameter.

Create an ODE file that relates the pendulum model coefficients to its state-space representation. Save this function as LinearPendulum.m such that it is in the MATLAB® search path.

function [A,B,C,D] = LinearPendulum(m,g,l,b,Ts)
A = [0 1; -g/l, -b/m/l^2];
B = zeros(2,0);
C = [1 0];
D = zeros(1,0);
end

In this function:

m is the pendulum mass.
g is the gravitational acceleration.
l is the pendulum length.
b is the viscous friction coefficient.
Ts is the model sample time.

Create a linear grey-box model associated with the ODE function.

odefun = 'LinearPendulum';

m = 1;
g = 9.81;
l = 1;
b = 0.2;
parameters = {'mass',m;'gravity',g;'length',l;'friction',b};

fcn_type = 'c';

sys = idgrey(odefun,parameters,fcn_type);

sys has four parameters.

Specify the known parameters, m, g, and l, as fixed for estimation.

sys.Structure.Parameters(1).Free = false;
sys.Structure.Parameters(2).Free = false;
sys.Structure.Parameters(3).Free = false;

m, g, and l are the first three parameters of sys.

Specify a zero lower bound for b, the fourth parameter of sys.

sys.Structure.Parameters(4).Minimum = 0;

Similarly, to specify an upper bound for an estimable parameter, use the Maximum field of the parameter.

Specify Additional Attributes of Grey-Box Model

Open Live Script

Create a grey-box model with identifiable parameters and properties that you specify. Then, specify an additional property.

Use name-value arguments to specify names for the input and output channels.

odefun = 'motorDynamics';
parameters = 1;
fcn_type = 'cd';
extra_args = 0.25; 
Ts = 0;
sys = idgrey(odefun,parameters,fcn_type,extra_args,Ts,'InputName','Voltage',...
            'OutputName',{'Angular Position','Angular Velocity'});

Specify TimeUnit using dot notation.

sys.TimeUnit = 'seconds';

Create Array of Grey-Box Models

Open Live Script

Use the stack command to create an array of linear grey-box models.

Specify odefun1 using the function handle @motordynamics. Set the static gain to 1, using extra_args1.

odefun1 = @motorDynamics;
parameters1 = [1 2];
fcn_type = 'cd';
extra_args1 = 1;
sys1 = idgrey(odefun1,parameters1,fcn_type,extra_args1);
size(sys1)

Grey-box model with 2 outputs, 1 inputs, 2 states and 2 free parameters.

Specify odefun2 using the function name 'motorDynamics'. Set the static gain to 0.5, using extra_args2.

odefun2 = 'motorDynamics';
parameters2 = {[1 2]};
extra_args2 = 0.5;
sys2 = idgrey(odefun2,parameters2,fcn_type,extra_args2);

Use stack to create the 2-by-1 array sysarr of idgrey models.

sysarr = stack(1,sys1,sys2);
size(sysarr)

2x1 array of grey-box models.
Each model has 2 outputs, 1 inputs, 2 states and 2 free parameters.

Version History

Introduced before R2006a

idgrey

Description

Creation

Syntax

Description

Input Arguments

odefun — MATLAB function function handle | character array | string

parameters — Initial values of parameters cell array | matrix

fcn_type — Function type 'c' | 'd' | 'cd'

extra_args — Extra arguments {} (default) | cell array

Properties

A,B,C,D — Values of state-space matrices matrices

K — Value of state disturbance matrix K matrix

StateName — State names {''} (default) | character vector | cell array of character vectors | string | string array

StateUnit — State units {''} (default) | character vector | cell array of character vectors or stings | string | string array

Structure — Information about estimable parameters LinearODE structure

Noise Variance — Noise variance of model innovations scalar | matrix

Report — Summary report report field values

InputDelay — Delay at inputs 0 (default) | scalar | vector

OutputDelay — Output delays 0 (default)

Ts — Sample time 0 | -1 | positive scalar

TimeUnit — Model time units 'seconds' (default) | 'minutes' | 'milliseconds' | ...

InputName — Names of input channels {''} (default) | character vector | cell array of character vectors | string | string array

InputUnit — Units of input signals {''} (default) | character vector | cell array of character vectors | string | string array

InputGroup — Input channel groups structure with no fields (default) | structure

OutputName — Names of output channels {''} (default) | character vector | cell array of character vectors or strings | string | string array

OutputUnit — Units of output signals {''} (default) | character vector | cell array of character vectors | string | string array

OutputGroup — Output channel groups structure with no fields (default) | structure

Name — Model name '' (default) | character vector | string

Notes — Text notes about model [0×1 string] (default) | string | character vector | cell array of character vectors or strings | string array

UserData — Data associated with model [] (default) | any data type

SamplingGrid — Sampling grid for model arrays structure with no fields (default) | structure

Object Functions

Examples

Create Grey-Box Model with Estimable Parameters

Configure Estimable Parameter of Grey-Box Model

Specify Additional Attributes of Grey-Box Model

Create Array of Grey-Box Models

Version History

See Also

Topics

`odefun` — MATLAB function
function handle | character array | string

`parameters` — Initial values of parameters
cell array | matrix

`fcn_type` — Function type
`'c'` | `'d'` | `'cd'`

`extra_args` — Extra arguments
`{}` (default) | cell array

`A,B,C,D` — Values of state-space matrices
matrices

`K` — Value of state disturbance matrix K
matrix

`StateName` — State names
`{''}` (default) | character vector | cell array of character vectors | string | string array

`StateUnit` — State units
`{''}` (default) | character vector | cell array of character vectors or stings | string | string array

`Structure` — Information about estimable parameters
`LinearODE` structure

`Noise Variance` — Noise variance of model innovations
scalar | matrix

`Report` — Summary report
report field values

`InputDelay` — Delay at inputs
0 (default) | scalar | vector

`OutputDelay` — Output delays
0 (default)

`Ts` — Sample time
`0` | `-1` | positive scalar

`TimeUnit` — Model time units
`'seconds'` (default) | `'minutes'` | `'milliseconds'` | ...

`InputName` — Names of input channels
`{''}` (default) | character vector | cell array of character vectors | string | string array

`InputUnit` — Units of input signals
`{''}` (default) | character vector | cell array of character vectors | string | string array

`InputGroup` — Input channel groups
structure with no fields (default) | structure

`OutputName` — Names of output channels
`{''}` (default) | character vector | cell array of character vectors or strings | string | string array

`OutputUnit` — Units of output signals
`{''}` (default) | character vector | cell array of character vectors | string | string array

`OutputGroup` — Output channel groups
structure with no fields (default) | structure

`Name` — Model name
`''` (default) | character vector | string

`Notes` — Text notes about model
`[0×1 string]` (default) | string | character vector | cell array of character vectors or strings | string array

`UserData` — Data associated with model
`[]` (default) | any data type

`SamplingGrid` — Sampling grid for model arrays
structure with no fields (default) | structure