# greyest

Estimate ODE parameters of linear grey-box model

## Syntax

``sys = greyest(data,init_sys)``
``sys = greyest(data,init_sys,opt)``
``[sys,x0] = greyest(___)``

## Description

example

````sys = greyest(data,init_sys)` estimates a linear grey-box model `sys` using the time-domain or frequency-domain data `data` and the initial model `init_sys`. The dimensions of the inputs and outputs of `data` and `init_sys` must match. `sys` is an identified `idgrey` model that has the same structure as `init_sys`.```

example

````sys = greyest(data,init_sys,opt)` incorporates a `greyestOptions` option set `opt` that specifies options such as handling of initial states and regularization options.```
````[sys,x0] = greyest(___)` returns the value of the initial states computed during estimation. You can use this syntax with any of the previous input-argument combinations.```

## Examples

collapse all

Estimate the parameters of a DC motor using the linear grey-box framework.

```load('dcmotordata'); data = iddata(y, u, 0.1, 'Name', 'DC-motor'); data.InputName = 'Voltage'; data.InputUnit = 'V'; data.OutputName = {'Angular position', 'Angular velocity'}; data.OutputUnit = {'rad', 'rad/s'}; data.Tstart = 0; data.TimeUnit = 's';```

`data` is an `iddata` object containing the measured data for the outputs, the angular position, the angular velocity. It also contains the input, the driving voltage.

Create a grey-box model representing the system dynamics.

For the DC motor, choose the angular position (rad) and the angular velocity (rad/s) as the outputs and the driving voltage (V) as the input. Set up a linear state-space structure of the following form:

`$\underset{}{\overset{˙}{x}}\left(t\right)=\left[\begin{array}{cc}0& 1\\ 0& -\frac{1}{\tau }\end{array}\right]x\left(t\right)+\left[\begin{array}{c}0\\ \frac{G}{\tau }\end{array}\right]u\left(t\right)$`

`$y\left(t\right)=\left[\begin{array}{cc}1& 0\\ 0& 1\end{array}\right]x\left(t\right).$`

$\tau$ is the time constant of the motor in seconds, and $G$ is the static gain from the input to the angular velocity in rad/(V*s).

```G = 0.25; tau = 1; init_sys = idgrey('motorDynamics',tau,'cd',G,0);```

The governing equations in state-space form are represented in the MATLAB® file `motorDynamics.m`. To view the contents of this file, enter `edit motorDynamics.m` at the MATLAB command prompt.

$G$ is a known quantity that is provided to `motorDynamics.m` as an optional argument.

$\tau$ is a free estimation parameter.

`init_sys` is an `idgrey` model associated with `motor.m`.

Estimate $\tau$.

`sys = greyest(data,init_sys);`

`sys` is an `idgrey` model containing the estimated value of $\tau$.

To obtain the estimated parameter values associated with `sys`, use `getpvec(sys)`.

Analyze the result.

```opt = compareOptions('InitialCondition','zero'); compare(data,sys,Inf,opt)```

`sys` provides a 98.35% fit for the angular position and an 84.42% fit for the angular velocity.

Estimate the parameters of a DC motor by incorporating prior information about the parameters when using regularization constants.

The model is parameterized by static gain `G` and time constant $\tau$. From prior knowledge, it is known that `G` is about 4 and $\tau$ is about 1. Also, you have more confidence in the value of $\tau$ than `G` and would like to guide the estimation to remain close to the initial guess.

`load regularizationExampleData.mat motorData`

The data contains measurements of motor's angular position and velocity at given input voltages.

Create an `idgrey` model for DC motor dynamics. Use the function `DCMotorODE` that represents the structure of the grey-box model.

```mi = idgrey(@DCMotorODE,{'G', 4; 'Tau', 1},'cd',{}, 0); mi = setpar(mi, 'label', 'default');```

If you want to view the `DCMotorODE` function, type:

`type DCMotorODE.m`
```function [A,B,C,D] = DCMotorODE(G,Tau,Ts) %DCMOTORODE ODE file representing the dynamics of a DC motor parameterized %by gain G and time constant Tau. % % [A,B,C,D,K,X0] = DCMOTORODE(G,Tau,Ts) returns the state space matrices % of the DC-motor with time-constant Tau and static gain G. The sample % time is Ts. % % This file returns continuous-time representation if input argument Ts % is zero. If Ts>0, a discrete-time representation is returned. % % See also IDGREY, GREYEST. % Copyright 2013 The MathWorks, Inc. A = [0 1;0 -1/Tau]; B = [0; G/Tau]; C = eye(2); D = [0;0]; if Ts>0 % Sample the model with sample time Ts s = expm([[A B]*Ts; zeros(1,3)]); A = s(1:2,1:2); B = s(1:2,3); end ```

Specify regularization options Lambda.

```opt = greyestOptions; opt.Regularization.Lambda = 100;```

Specify regularization options R.

`opt.Regularization.R = [1, 1000];`

You specify more weighting on the second parameter because you have more confidence in the value of $\tau$ than `G`.

Specify the initial values of the parameters as regularization option $\theta$*.

`opt.Regularization.Nominal = 'model';`

Estimate the regularized grey-box model.

`sys = greyest(motorData, mi, opt);`

## Input Arguments

collapse all

Uniformly sampled estimation data, specified as a timetable, a comma-separated matrix pair, or a time-domain or frequency-domain data object, as the following sections describe.

`data` has the same input and output dimensions as `init_sys`.

By default, the software sets the sample time of the model to the sample time of the estimation data.

#### Timetable

Specify `data` as a `timetable` that uses a regularly spaced time vector. `data` contains variables representing input and output channels.

#### Comma-Separated Matrix Pair

Specify `data` as a comma-separated pair of numeric matrices that contain input and output time-domain signal values. Use this `data` specification only for discrete-time systems.

#### Data Object

Specify data as an `iddata`, `idfrd`, or `frd` object.

• For time-domain estimation, `data` must be a time-domain `iddata` object containing the input and output signal values.

• For frequency-domain estimation, `data` can be one of the following:

• Recorded frequency response data (`frd` (Control System Toolbox) or `idfrd`)

• `iddata` object with properties specified as follows:

• `InputData` — Fourier transform of the input signal

• `OutputData` — Fourier transform of the output signal

• `Domain``'Frequency'`

For more information about working with estimation data types, see Data Domains and Data Types in System Identification Toolbox.

Initial model, specified as an `idgrey` object. `init_sys` can be a model that has previously been identified or that has been constructed directly using the `idgrey` command.

`init_sys` must have the same number of inputs and outputs as `data`.

Estimation options, specified as a `greyestOptions` option set. Options specified by `opt` include:

• Handling of initial states

• Regularization

• Numerical search method used for estimation

## Output Arguments

collapse all

Estimated grey-box model, returned as an `idgrey` model. This model is created using the specified initial system, and estimation options.

Information about the estimation results and options used is stored in the `Report` property of the model. `Report` has the following fields:

Report FieldDescription
`Status`

Summary of the model status, which indicates whether the model was created by construction or obtained by estimation

`Method`

Estimation command used

`InitialState`

Handling of initial states during estimation, returned as one of the following:

• `'model'` — The initial state is parameterized by the ODE file used by the `idgrey` model.

• `'zero'` — The initial state is set to zero.

• `'estimate'` — The initial state is treated as an independent estimation parameter.

• `'backcast'` — The initial state is estimated using the best least squares fit.

• Vector of doubles of length Nx, where Nx is the number of states. For multiexperiment data, a matrix with Ne columns, where Ne is the number of experiments.

This field is especially useful to view how the initial states were handled when the `InitialState` option in the estimation option set is `'auto'`.

`DisturbanceModel`

Handling of the disturbance component (K) during estimation, returned as one of the following values:

• `'model'`K values are parameterized by the ODE file used by the `idgrey` model.

• `'fixed'` — The value of the `K` property of the `idgrey` model is fixed to its original value.

• `'none'`K is fixed to zero.

• `'estimate'`K is treated as an independent estimation parameter.

This field is especially useful to view the how the disturbance component was handled when the `DisturbanceModel` option in the estimation option set is `'auto'`.

`Fit`

Quantitative assessment of the estimation, returned as a structure. See Loss Function and Model Quality Metrics for more information on these quality metrics. The structure has these fields.

• `FitPercent` — Normalized root mean squared error (NRMSE) measure of how well the response of the model fits the estimation data, expressed as the percentage fitpercent = 100(1-NRMSE)

• `LossFcn` — Value of the loss function when the estimation completes

• `MSE` — Mean squared error (MSE) measure of how well the response of the model fits the estimation data

• `FPE` — Final prediction error for the model

• `AIC` — Raw Akaike Information Criteria (AIC) measure of model quality

• `AICc` — Small-sample-size corrected AIC

• `nAIC` — Normalized AIC

• `BIC` — Bayesian Information Criteria (BIC)

`Parameters`

Estimated values of model parameters

`OptionsUsed`

Option set used for estimation. If no custom options were configured, this is a set of default options. See `greyestOptions` for more information.

`RandState`

State of the random number stream at the start of estimation. Empty, `[]`, if randomization was not used during estimation. For more information, see `rng`.

`DataUsed`

Attributes of the data used for estimation, returned as a structure with the following fields.

• `Name` — Name of the data set

• `Type` — Data type

• `Length` — Number of data samples

• `Ts` — Sample time

• `InterSample` — Input intersample behavior, returned as one of the following values:

• `'zoh'` — A zero-order hold maintains a piecewise-constant input signal between samples.

• `'foh'` — A first-order hold maintains a piecewise-linear input signal between samples.

• `'bl'` — Band-limited behavior specifies that the continuous-time input signal has zero power above the Nyquist frequency.

• `InputOffset` — Offset removed from time-domain input data during estimation. For nonlinear models, it is `[]`.

• `OutputOffset` — Offset removed from time-domain output data during estimation. For nonlinear models, it is `[]`.

`Termination`

Termination conditions for the iterative search used for prediction error minimization, returned as a structure with these fields.

• `WhyStop` — Reason for terminating the numerical search

• `Iterations` — Number of search iterations performed by the estimation algorithm

• `FirstOrderOptimality`$\infty$-norm of the gradient search vector when the search algorithm terminates

• `FcnCount` — Number of times the objective function was called

• `UpdateNorm` — Norm of the gradient search vector in the last iteration. Omitted when the search method is `'lsqnonlin'` or `'fmincon'`.

• `LastImprovement` — Criterion improvement in the last iteration, expressed as a percentage. Omitted when the search method is `'lsqnonlin'` or `'fmincon'`.

• `Algorithm` — Algorithm used by `'lsqnonlin'` or `'fmincon'` search method. Omitted when other search methods are used.

For estimation methods that do not require numerical search optimization, the `Termination` field is omitted.

For more information on using `Report`, see Estimation Report.

Initial states computed during the estimation, returned as a matrix containing a column vector corresponding to each experiment.

This array is also stored in the `Parameters` field of the model `Report` property.

## Version History

Introduced in R2012a

expand all