# idgrey

Linear ODE (grey-box model) with identifiable parameters

## Syntax

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

## Description

sys = idgrey(odefun,parameters,fcn_type) creates a linear grey-box model with identifiable parameters, sys. odefun specifies the user-defined function that relates the model parameters, parameters, to its state-space representation.

sys = idgrey(odefun,parameters,fcn_type,optional_args) creates a linear grey-box model with identifiable parameters using the optional arguments required by odefun.

sys = idgrey(odefun,parameters,fcn_type,optional_args,Ts) creates a linear grey-box model with identifiable parameters with the specified sample time, Ts.

sys = idgrey(odefun,parameters,fcn_type,optional_args,Ts,Name,Value) creates a linear grey-box model with identifiable parameters with additional options specified by one or more Name,Value pair arguments.

## Object Description

An idgrey model represents a system as a continuous-time or discrete-time state-space model with identifiable (estimable) coefficients.

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}\stackrel{˙}{x}\left(t\right)=Ax\left(t\right)+Bu\left(t\right)+Ke\left(t\right)\\ y\left(t\right)=Cx\left(t\right)+Du\left(t\right)+e\left(t\right)\end{array}$

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

$\begin{array}{l}x\left[k+1\right]=Ax\left[k\right]+Bu\left[k\right]+Ke\left[k\right]\\ y\left[k\right]=Cx\left[k\right]+Du\left[k\right]+e\left[k\right]\end{array}$

For idgrey models, the state-space matrices A, B, C, and D are expressed as a function of user-defined parameters using a MATLAB® function. You access estimated parameters using sys.Structures.Parameters, where sys is an idgrey model.

Use an idgrey model when you know the system of equations governing the system dynamics explicitly. You should be able to express these dynamics in the form of ordinary differential or difference equations. You specify complex relationships and constraints among the parameters that cannot be done through structured state-space models (idss).

You can 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. The MATLAB function can also return the K matrix and accept optional input arguments. The matrices returned may represent a continuous-time or discrete-time model, as indicated by the sample time.

Use the estimating functions pem or greyest to obtain estimated values for the unknown parameters of an idgrey model.

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

## Examples

collapse all

Create an idgrey model to represent a DC motor. Specify the motor time-constant as an estimable parameter and that the ODE function can return continuous- or discrete-time state-space matrices.

Create the idgrey model.

odefun = 'motorDynamics';
parameters = 1;
fcn_type = 'cd';
optional_args = 0.25;
Ts = 0;
sys = idgrey(odefun,parameters,fcn_type,optional_args,Ts);

sys is an idgrey model that is configured to use the shipped file motorDynamics.m to return the $A$, $B$, $C$, $D$, and $K$ matrices. motorDynamics.m also returns the initial conditions, $X0$. The motor constant, $\tau$, is defined in motorDynamics.m as an estimable parameter, and parameters = 1 specifies its initial value as 1.

You can use pem or greyest to refine the estimate for $\tau$.

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.

Create a grey-box model with identifiable parameters. Name the input and output channels of the model, and specify seconds for the model time units.

Use Name,Value pair arguments to specify additional model properties on model creation.

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

To change or specify more attributes of an existing model, you can use dot notation. For example:

sys.TimeUnit = 'seconds';

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

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

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

sysarr = stack(1,sys1,sys2);

stack creates a 2-by-1 array of idgrey models, sysarr.

## Input Arguments

 odefun MATLAB function that relates the model parameters to its state-space representation. odefun specifies the name of a MATLAB function (.m, .p, a function handle or .mex* file). This function establishes the relationship between the model parameters, parameters, and its state-space representation. The function may optionally relate the model parameters to the disturbance matrix and initial states. If the function is not on the MATLAB path, then specify the full file name, including the path. The syntax for odefun must be as follows: [A,B,C,D] = odefun(par1,par2,...,parN,Ts,optional_arg1,optional_arg2,...) The function outputs describe the model in the following linear state-space innovations form: $\begin{array}{c}xn\left(t\right)=Ax\left(t\right)+Bu\left(t\right)+Ke\left(t\right);x\left(0\right)={x}_{0}\\ y\left(t\right)=Cx\left(t\right)+Du\left(t\right)+e\left(t\right)\end{array}$ In discrete time xn(t)=x(t+Ts) and in continuous time, $xn\left(t\right)=\stackrel{˙}{x}\left(t\right)$. par1,par2,...,parN are model parameters. Each entry may be a scalar, vector or matrix. Ts is the sample time. optional_arg1,optional_arg2,... are the optional inputs that odefun may require. The values of the optional input arguments are unchanged through the estimation process. However, the values of par1,par2,...,parN are updated during estimation to fit the data. Use optional input arguments to vary the constants and coefficients used by your model without editing odefun. The disturbance matrix, K, and the initial state values, x0, are not parametrized. Instead, these values are determined separately, using the DisturbanceModel and InitialState estimation options, respectively. For more information regarding the estimation options, see greyestOptions. A good choice for achieving the best simulation results is to set the DisturbanceModel option to 'none', which fixes K to zero. (Optional) Parameterizing Disturbance: odefun can also return the disturbance component, K, using the syntax: [A,B,C,D,K] = odefun(par1,par2,...,parN,Ts,optional_arg1,optional_arg2,...) If odefun returns a value for K that contains NaN values, then the estimating function assumes that K is not parameterized. In this case, the value of the DisturbanceModel estimation option determines how K is handled. (Optional) Parameterizing Initial State Values: To make the model initial states, X0, dependent on the model parameters, use the following syntax for odefun: [A,B,C,D,K,X0] = odefun(par1,par2,...,parN,Ts,optional_arg1,optional_arg2,...) If odefun returns a value for X0 that contains NaN values, then the estimating function assumes that X0 is not parameterized. In this case, X0 may be fixed to zero or estimated separately, using the InitialStates estimation option. parameters Initial values of the parameters required by odefun. Specify parameters as a cell array containing the parameter initial values. If your model requires only one parameter, which may itself be a vector or a matrix, you may specify parameters as a matrix. You may 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 example: parameters = {'mass',par1;'stiffness',par2;'damping',par3} fcn_type Indicates whether the model is parameterized in continuous-time, discrete-time, or both. fcn_type requires 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 may or may not depend on the value of Ts.'cd' — odefun returns matrices corresponding to a continuous-time system, if Ts=0. Otherwise, if Ts>0, odefun returns matrices corresponding to a discrete-time system. Select this option to sample your model using the values returned by odefun, rather than using the software’s internal sample time conversion routines. optional_args Optional input arguments required by odefun. Specify optional_args as a cell array. If odefun does not require optional input arguments, specify optional_args as {}. Ts Model sample time. If Ts is unspecified, it is assumed to be: -1 — If fcn_type is 'd' or 'cd'.Ts = -1 indicates a discrete-time model with unknown sample time.0 — If fcn_type is 'c'.Ts = 0 indicates a continuous-time model. Name,Value Specify optional comma-separated pairs of Name,Value arguments, where Name is the argument name and Value is the corresponding value. Name must appear inside single quotes (' '). You can specify several name and value pair arguments in any order as Name1,Value1,...,NameN,ValueN. Use Name,Value arguments to specify additional properties of idgrey models during model creation. For example, idgrey(odefun,parameters,fcn_type,'InputName','Voltage') creates an idgrey model with the InputName property set to Voltage.

## Properties

idgrey object properties include: