Documentation Center

  • 評価版
  • 製品アップデート

idnlgrey

Nonlinear ODE (grey-box model) with unknown parameters

Syntax

m = idnlgrey('filename',Order,Parameters)
m = idnlgrey('filename',Order,Parameters,InitialStates)
m = idnlgrey('filename',Order,Parameters,InitialStates,Ts)
m = idnlgrey('filename',Order,Parameters,InitialStates,Ts,P1,V1,...,PN,VN)

Description

idnlgrey is an object that represents the nonlinear grey-box model.

For information about the nonlinear grey-box models, see Estimating Nonlinear Grey-Box Models.

The information in these reference pages summarizes the idnlgrey model constructor and properties. It discusses the following topics:

idnlgrey Constructor

After you create the function or MEX-file with your model structure, you must define an idnlgrey object.

Use the following syntax to define the idnlgrey model object:

m = idnlgrey('filename',Order,Parameters)

m = idnlgrey('filename',Order,Parameters,InitialStates)

m = idnlgrey('filename',Order,Parameters,InitialStates,Ts)

m = idnlgrey('filename',Order,Parameters,InitialStates,Ts,P1,V1,...,PN,VN)

The idnlgrey arguments are defined as follows:

  • 'filename' — Name of the function or MEX-file storing the model structure (ODE file).

  • Order — Vector with three entries [Ny Nu Nx], specifying the number of model outputs Ny, the number of inputs Nu, and the number of states Nx.

  • Parameters — Parameters, specified as struct arrays, cell arrays, or double arrays.

  • InitialStates — Specified in a same way as parameters. Must be fourth input to the idnlgrey constructor.

  • The command

    m = idnlgrey('filename',Order,Parameters,...
                  InitialStates,Ts,P1,V1,...,PN,VN)

    specifies idnlgrey property-value pairs. See information on properties of idnlgrey objects below.

Estimate the unknown parameters and initial states of this object using pem. The input-output dimensions of the data must be compatible with the input and output orders you specified for the idnlgrey model. You can pass additional property-value pairs to pem to specify the properties of the model or estimation algorithm, such as MaxIter and Tolerance.

idnlgrey Properties

After creating the object, you can use get or dot notation to access the object property values.

You can include property-value pairs in the model estimator or constructor to specify the model structure and estimation algorithm properties.

Use set or dot notation to set a property of an existing object.

After creating the object, you can use get or dot notation to access the object property values. For example:

% Get the model time unit
get(m,'TimeUnit')
m.TimeUnit

The following table summarizes idnlgrey model properties. The general idnlmodel properties also apply to this nonlinear model object (see the corresponding reference pages).

Property NameDescription
Algorithm

A structure that specifies the estimation algorithm options, as described in idnlgrey Algorithm Properties.

CovarianceMatrix

Covariance matrix of the estimated Parameters.
Assignable values:

  • 'None' to omit computing uncertainties and save time during parameter estimation.

  • 'Estimate' to estimation covariance. Symmetric and positive Np-by-Np matrix (or []) where Np is the number of free model parameters.

EstimationInfo

A read-only structure that stores estimation settings and results, as described in idnlgrey EstimationInfo Properties.

FileArgument

Contains auxiliary variables passed to the ODE file (function or MEX-file) specified in FileName. These variables may be used as extra inputs for specifying the state and/or output equations. FileArgument should be specified as a cell array.
Default: {}.

FileName

File name string (without extension) or a function handle for computing the states and the outputs. If 'FileName' is a string, then it must point to a MATLAB® file, P-code file or MEX-file. For more information about the file variables, see Specifying the Nonlinear Grey-Box Model Structure.

InitialStates

An Nx-by-1 structure array with fields as follows. Here, Nx is the number of states of the model.

  • Name: Name of the state (a string). Default value is 'x#i', where #i is an integer in [1, Nx].

  • Unit: Unit of the state (a string). Default value is ''.

  • Value: Initial value of the initial state(s). Assignable values are:

    • A finite real scalar

    • A finite real 1-by-Ne vector, where Ne is the number of experiments in the data set to be used for estimation

  • Minimum: Minimum value of the initial state(s). Must be a real scalar/1-by-Ne vector of the same size as Value and such that Minimum <= Value for all components. Default value: -Inf(size(Value)).

  • Maximum: Maximum value of the initial state(s). Must be a real scalar/1-by-Ne vector of the same size as Value and such that Value <= Maximum for all components. Default value: Inf(size(Value)).

  • Fixed: Specifies which component(s) of the initial state(s) are fixed to their known values. Must be a Boolean scalar/1-by-Ne vector of the same size as Value. Default value: true(size(Value)) (that is, do not estimate the initial states).

For an idnlgrey model M, the ith initial state is accessed through M.InitialStates(i) and its subfields as M.InitialStates(i).FIELDNAME.

Order

Structure with following fields:

  • ny — Number of outputs of the model structure.

  • nu — Number of inputs of the model structure.

  • nx — Number of states of the model structure.

For time series, nu is 0. For static model structures, nx is 0.
Parameters

Np-by-1 structure array with information about the model parameters containing the following fields:

  • Name: Name of the parameter (a string). Default value is 'p#i', where #i is an integer in [1, Np].

  • Unit: Unit of the parameter (a string). Default value is ''.

  • Value: Initial value of the parameter(s). Assignable values are:

    • A finite real scalar

    • A finite real column vector

    • A 2-dimensional real matrix

  • Minimum: Minimum value of the parameter(s). Must be a real scalar/column vector/matrix of the same size as Value and such that Minimum <= Value for all components. Default value: -Inf(size(Value)).

  • Maximum: Maximum value of the parameter(s). Must be a real scalar/column vector/matrix of the same size as Value and such that Value <= Maximum for all components. Default value: Inf(size(Value)).

  • Fixed: Specifies which component(s) of the parameter(s) are fixed to their known values. Must be a Boolean scalar/column vector/matrix of the same size as Value. Default value: false(size(Value)), (estimate all parameter components).

For an idnlgrey model M, the ith parameter is accessed through M.Parameters(i) and its subfields as M.Parameters(i).FIELDNAME.

idnlgrey Algorithm Properties

The following table summarizes the fields of the Algorithm idnlgrey model properties. Algorithm is a structure that specifies the estimation-algorithm options.

Property NameDescription
Advanced

A structure that specifies additional estimation algorithm options, as described in idnlgrey Advanced Algorithm Properties.

Criterion

Specifies criterion used during minimization. Criterion can have the following values:

  • 'Det': Minimize det(E'*E) where E represents the prediction error. This is the optimal choice in a statistical sense and leads to the maximum likelihood estimates in case nothing is known about the variance of the noise. It uses the inverse of the estimated noise variance as the weighting function. This is the default criterion used for all models, except idnlgrey which uses 'Trace' by default.

  • 'Trace': Minimize the trace of the weighted prediction error matrix trace(E'*E*W), where E is the matrix of prediction errors, with one column for each output, and W is a positive semi-definite symmetric matrix of size equal to the number of outputs. By default, W is an identity matrix of size equal to the number of model outputs (so the minimization criterion becomes trace(E'*E), or the traditional least-sum-of-squared-errors criterion. You can specify the relative weighting of prediction errors for each output using the Weighting field of the Algorithm property.

Display

Toggles displaying or hiding estimation progress information in the MATLAB Command Window.
Default: 'Off'.
Assignable values:

  • 'Off' — Hide estimation information.

  • 'On' — Display estimation information.

GradientOptions

A structure that specifies the options related to calculation of gradient of the cost, idnlgrey Gradient Options.

LimitError

Robustification criterion that limits the influence of large residuals, specified as a positive real value. Residual values that are larger than 'LimitError' times the estimated residual standard deviation have a linear cost instead of the usual quadratic cost.
Default: 0 (no robustification).

MaxIter

Maximum number of iterations for the estimation algorithm, specified as a positive integer.
Default: 20.

Regularization

Options for regularized estimation of model parameters. For more information on regularization, see Regularized Estimates of Model Parameters.

Structure with the following fields:

  • Lambda — Constant that determines the bias versus variance tradeoff.

    Specify a positive scalar to add the regularization term to the estimation cost.

    The default value of zero implies no regularization.

    Default: 0

  • R — Weighting matrix.

    Specify a vector of nonnegative numbers or a square positive semi-definite matrix. The length must be equal to the number of free parameters of the model.

    For black-box models, using the default value is recommended. For structured and grey-box models, you can also specify a vector of np positive numbers such that each entry denotes the confidence in the value of the associated parameter.

    The default value of 1 implies a value of eye(npfree), where npfree is the number of free parameters.

    Default: 1

  • Nominal — The nominal value towards which the free parameters are pulled during estimation.

    The default value of zero implies that the parameter values are pulled towards zero. If you are refining a model, you can set the value to 'model' to pull the parameters towards the parameter values of the initial model. The initial parameter values must be finite for this setting to work.

    Default: 0

SearchMethod

Method used by the iterative search algorithm.
Assignable values:

  • 'Auto' — Automatically chooses from the following methods.

  • 'gn' — Gauss-Newton method.

  • 'gna' — Adaptive Gauss-Newton method.

  • 'grad' — A gradient method.

  • 'lm' — Levenberg-Marquardt method.

  • 'lsqnonlin' — Nonlinear least-squares method (requires the Optimization Toolbox™ product). This method handles only the 'Trace' criterion.

SimulationOptions

A structure that specifies the simulation method and related options, as described in idnlgrey Simulation Options.

Tolerance

Specifies to terminate the iterative search when the expected improvement of the parameter values is less than Tolerance, specified as a positive real value in %.
Default: 0.01.

Weighting

Positive semi-definite matrix W used for weighted trace minimization. When Criterion = 'Trace', trace(E'*E*W) is minimized. Weighting can be used to specify relative importance of outputs in multiple-input multiple-output models (or reliability of corresponding data) when W is a diagonal matrix of nonnegative values. Weighting is not useful in single-output models. By default, Weighting is an identity matrix of size equal to the number of outputs.

    Note:   The Criterion property setting is meaningful in multiple-output cases only. In single-output models, the two criteria are equivalent. Both the Det and Trace criteria are derived from a general requirement of minimizing a weighted sum of least squares of prediction errors. The Det criterion can be interpreted as estimating the covariance matrix of the noise source and using the inverse of that matrix as the weighting. You should specify the weighting when using the Trace criterion.

    If you want to achieve better accuracy for a particular channel in multiple-input multiple-output models, you should use Trace with weighting that favors that channel. Otherwise it is natural to use Det. When using Det you can check cond(model.NoiseVariance) after estimation. If the matrix is ill-conditioned, it may be more robust to use the Trace criterion. You can also use compare on validation data to check whether the relative error for different channels corresponds to your needs or expectations. Use the Trace criterion if you need to modify the relative errors, and check model.NoiseVariance to determine what weighting modifications to specify.

    The search method of lsqnonlin supports the Trace criterion only.

idnlgrey Advanced Algorithm Properties

The following table summarizes the fields of the Algorithm.Advanced model properties. The fields in the Algorithm.Advanced structure specify additional estimation-algorithm options.

Property NameDescription
GnPinvConst

When the search direction is computed, the algorithm discards the singular values of the Jacobian that are smaller than GnPinvConst*max(size(J))*norm(J)*eps. Singular values that are closer to 0 are included when GnPinvConst is decreased.
Default: 1e4.
Assign a positive, real value.

LMStartValue

(For Levenberg-Marquardt search algorithm) The starting level of regularization when using the Levenberg-Marquardt search method (Algorithm.SearchMethod='lm').
Default: 0.001.
Assign a positive real value.

LMStep

(For Levenberg-Marquardt search algorithm) Try this next level of regularization to get a lower value of the criterion function. The level of regularization is LMStep times the previous level. At the start of a new iteration, the level of regularization is computed as 1/LMStep times the value from the previous iteration.
Default: 10.
Assign a real value >1.

MaxBisections

Maximum number of bisections performed by the line search algorithm along the search direction (number of rotations of search vector for 'lm'). Used by 'gn', 'lm', 'gna' and 'grad' search methods (Algorithm.SearchMethod property)
Default: 25.
Assign a positive integer value.

MaxFunEvals

The iterations are stopped if the number of calls to the model file exceeds this value.
Default: Inf.
Assign a positive integer value.

MinParChange

The smallest parameter update allowed per iteration.
Default: 1e-16.
Assign a positive, real value.

RelImprovement

The iterations are stopped if the relative improvement of the criterion function is less than RelImprovement.
Default: 0.
Assign a positive real value.

    Note:   Does not apply to Algorithm.SearchMethod='lsqnonlin'

StepReduction

(For line search algorithm) The suggested parameter update is reduced by the factor 'StepReduction' after each try until either 'MaxBisections' tries are completed or a lower value of the criterion function is obtained.
Default: 2.
Assign a positive, real value >1.

    Note:   Does not apply to Algorithm.SearchMethod='lsqnonlin'

idnlgrey Simulation Options

The following table summarizes the fields of Algorithm.SimulationOptions model properties.

Property NameDescription
AbsTol

Absolute error tolerance. This scalar applies to all components of the state vector. AbsTol applies only to the variable step solvers.
Default: 1e-6.
Assignable value: A positive real value.

FixedStep

(For fixed-step time-continuous solvers) Step size used by the solver.
Default: 'Auto'.
Assignable values:

  • 'Auto' — Automatically chooses the initial step.

  • A real value such that 0<FixedStep<=1.

InitialStep

(For variable-step time-continuous solvers) Specifies the initial step at which the ODE solver starts.
Default: 'Auto'.
Assignable values:

  • 'Auto' — Automatically chooses the initial step.

  • A positive real value such that MinStep<=InitialStep<=MaxStep.

MaxOrder

(For ode15s) Specifies the order of the Numerical Differentiation Formulas (NDF).
Default: 5.
Assignable values: 1, 2, 3, 4 or 5.

MaxStep

(For variable-step time-continuous solvers) Specifies the largest time step of the ODE solver.
Default: 'Auto' — 1/15 of the simulation interval.
Assignable values:

  • 'Auto' — Automatically chooses the time step.

  • A positive real value > MinStep.

MinStep

(For variable-step time-continuous solvers) Specifies the smallest time step of the ODE solver.
Default: 'Auto'.
Assignable values:

  • 'Auto' — Automatically chooses the time step.

  • A positive real value < MaxStep.

RelTol

(For variable-step time-continuous solvers) Relative error tolerance that applies to all components of the state vector. The estimated error in each integration step satisfies |e(i)| <= max(RelTol*abs(x(i)), AbsTol(i)).
Default: 1e-3 (0.1% accuracy).
Assignable value: A positive real value.

Solver

ODE (Ordinary Differential/Difference Equation) solver for solving state space equations.
A. Variable-step solvers for time-continuous idnlgrey models:

  • 'ode45' — Runge-Kutta (4,5) solver for nonstiff problems.

  • 'ode23' — Runge-Kutta (2,3) solver for nonstiff problems.

  • 'ode113' — Adams-Bashforth-Moulton solver for nonstiff problems.

  • 'ode15s' — Numerical Differential Formula solver for stiff problems.

  • 'ode23s' — Modified Rosenbrock solver for stiff problems.

  • 'ode23t' — Trapezoidal solver for moderately stiff problems.

  • 'ode23tb' — Implicit Runge-Kutta solver for stiff problems.

B. Fixed-step solvers for time-continuous idnlgrey models:

  • 'ode5' — Dormand-Prince solver.

  • 'ode4' — Fourth-order Runge-Kutta solver.

  • 'ode3' — Bogacki-Shampine solver.

  • 'ode2' — Heun or improved Euler solver.

  • 'ode1' — Euler solver.

C. Fixed-step solvers for time-discrete idnlgrey models: 'FixedStepDiscrete'

D. General: 'Auto' — Automatically chooses one of the previous solvers (default).

idnlgrey Gradient Options

The following table summarizes the fields of the Algorithm.GradientOptions model properties. Algorithm is a structure that specifies the estimation-algorithm options.

Property NameDescription
DiffMaxChange

Largest allowed parameter perturbation when computing numerical derivatives.
Default: Inf.
Assignable value: A positive real value >'DiffMinChange'.

DiffMinChange

Smallest allowed parameter perturbation when computing numerical derivatives.
Default: 0.01*sqrt(eps).
Assignable value: A positive real value <'DiffMaxChange'.

DiffScheme

Method for computing numerical derivatives with respect to the components of the parameters and/or the initial state(s) to form the Jacobian.
Default: 'Auto'
Assignable values:

  • 'Auto' - Automatically chooses from the following methods.

  • 'Central approximation'

  • 'Forward approximation'

  • 'Backward approximation'

GradientType

Method used when computing derivatives (Jacobian) of the parameters or the initial states to be estimated.
Default: 'Auto'.
Assignable values:

  • 'Auto' — Automatically chooses from the following methods.

  • 'Basic' — Individually computes all numerical derivatives required to form each column of the Jacobian.

  • 'Refined' — Simultaneously computes all numerical derivatives required to form each column of the Jacobian.

idnlgrey EstimationInfo Properties

The following table summarizes the fields of the EstimationInfo model properties. The read-only fields of the EstimationInfo structure store estimation settings and results.

Property NameDescription
Status

Shows whether the model parameters were estimated.

Method

Names of the solver and the optimizer used during estimation.

LossFcn

Value of the loss function, equal to det(E'*E/N), where E is the residual error matrix (one column for each output) and N is the total number of samples. Provides a quantitative description of the model quality.

FPE

Value of Akaike's Final Prediction Error (see fpe).

DataName

Name of the data from which the model is estimated.

DataLength

Length of the estimation data.

DataTs

Sampling interval of the estimation data.

DataDomain

'Time' means time domain data. 'Frequency' is not supported.

DataInterSample

Intersample behavior of the input estimation data used for interpolation:

  • 'zoh' means zero-order-hold, or piecewise constant.

  • 'foh' means first-order-hold, or piecewise linear.

EstimationTime

Duration of the estimation.

InitialGuess

Structure with the fields InitialStates and Parameters, specifying the values of these quantities before the last estimation.

Iterations

Number of iterations performed by the estimation algorithm.

LastImprovement

Criterion improvement in the last iteration, shown in %. Empty when SearchMethod='lsqnonlin' is the search method.

UpdateNorm

Norm of the search vector (Gauss-Newton vector) at the last iteration. Empty when 'lsqnonlin' is the search method.

Warning

Any warnings encountered during parameter estimation.

WhyStop

Reason for terminating parameter estimation iterations.

Definition of idnlgrey States

The states of an idnlgrey model are defined explicitly by the user in the function or MEX-file (as specified in the FileName property of the model) storing the model structure . The concept of states is useful for functions such as sim, predict, compare, and findstates.

    Note:   The initial values of the states are configured by the InitialStates property of the idnlgrey model.

See Also

| | | | | | |

Was this topic helpful?