Documentation Center 
Nonlinear ODE (greybox model) with unknown parameters
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)
idnlgrey is an object that represents the nonlinear greybox model.
For information about the nonlinear greybox models, see Estimating Nonlinear GreyBox Models.
The information in these reference pages summarizes the idnlgrey model constructor and properties. It discusses the following topics:
After you create the function or MEXfile 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 MEXfile 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 propertyvalue pairs. See information on properties of idnlgrey objects below.
Estimate the unknown parameters and initial states of this object using pem. The inputoutput dimensions of the data must be compatible with the input and output orders you specified for the idnlgrey model. You can pass additional propertyvalue pairs to pem to specify the properties of the model or estimation algorithm, such as MaxIter and Tolerance.
After creating the object, you can use get or dot notation to access the object property values.
You can include propertyvalue 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 Name  Description 

Algorithm  A structure that specifies the estimation algorithm options, as described in idnlgrey Algorithm Properties. 
CovarianceMatrix  Covariance matrix of the estimated Parameters.

EstimationInfo  A readonly structure that stores estimation settings and results, as described in idnlgrey EstimationInfo Properties. 
FileArgument  Contains auxiliary variables passed to the ODE file (function
or MEXfile) 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. 
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, Pcode file or MEXfile. For more information about the file variables, see Specifying the Nonlinear GreyBox Model Structure. 
InitialStates  An Nxby1 structure array with fields as follows. Here, Nx is the number of states of the model.
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:

Parameters  Npby1 structure array with information about the model parameters containing the following fields:
For an idnlgrey model M, the ith parameter is accessed through M.Parameters(i) and its subfields as M.Parameters(i).FIELDNAME. 
The following table summarizes the fields of the Algorithm idnlgrey model properties. Algorithm is a structure that specifies the estimationalgorithm options.
Property Name  Description 

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:

Display  Toggles displaying or hiding estimation progress information
in the MATLAB Command Window.

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. 
MaxIter  Maximum number of iterations for the estimation algorithm,
specified as a positive integer. 
Regularization  Options for regularized estimation of model parameters. For more information on regularization, see Regularized Estimates of Model Parameters. Structure with the following fields:

SearchMethod  Method used by the iterative search algorithm.

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 %. 
Weighting  Positive semidefinite 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 multipleinput multipleoutput models (or reliability of corresponding data) when W is a diagonal matrix of nonnegative values. Weighting is not useful in singleoutput models. By default, Weighting is an identity matrix of size equal to the number of outputs. 
Note: The Criterion property setting is meaningful in multipleoutput cases only. In singleoutput 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 multipleinput multipleoutput 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 illconditioned, 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. 
The following table summarizes the fields of the Algorithm.Advanced model properties. The fields in the Algorithm.Advanced structure specify additional estimationalgorithm options.
Property Name  Description 

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. 
LMStartValue  (For LevenbergMarquardt search algorithm) The starting
level of regularization when using the LevenbergMarquardt
search method (Algorithm.SearchMethod='lm'). 
LMStep  (For LevenbergMarquardt 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. 
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) 
MaxFunEvals  The iterations are stopped if the number of calls to
the model file exceeds this value. 
MinParChange  The smallest parameter update allowed per iteration. 
RelImprovement  The iterations are stopped if the relative improvement
of the criterion function is less than RelImprovement. 
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. 
The following table summarizes the fields of Algorithm.SimulationOptions model properties.
Property Name  Description 

AbsTol  Absolute error tolerance. This scalar applies to all
components of the state vector. AbsTol applies
only to the variable step solvers. 
FixedStep  (For fixedstep timecontinuous solvers) Step size used
by the solver.

InitialStep  (For variablestep timecontinuous solvers) Specifies
the initial step at which the ODE solver starts.

MaxOrder  (For ode15s) Specifies the order of the Numerical Differentiation
Formulas (NDF). 
MaxStep  (For variablestep timecontinuous solvers) Specifies
the largest time step of the ODE solver.

MinStep  (For variablestep timecontinuous solvers) Specifies
the smallest time step of the ODE solver.

RelTol  (For variablestep timecontinuous 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)). 
Solver  ODE (Ordinary Differential/Difference Equation) solver
for solving state space equations.
B. Fixedstep solvers for timecontinuous idnlgrey models:
C. Fixedstep solvers for timediscrete idnlgrey models: 'FixedStepDiscrete' D. General: 'Auto' — Automatically chooses one of the previous solvers (default). 
The following table summarizes the fields of the Algorithm.GradientOptions model properties. Algorithm is a structure that specifies the estimationalgorithm options.
Property Name  Description 

DiffMaxChange  Largest allowed parameter perturbation when computing
numerical derivatives. 
DiffMinChange  Smallest allowed parameter perturbation when computing
numerical derivatives. 
DiffScheme  Method for computing numerical derivatives with respect
to the components of the parameters and/or the initial state(s) to
form the Jacobian.

GradientType  Method used when computing derivatives (Jacobian) of
the parameters or the initial states to be estimated.

The following table summarizes the fields of the EstimationInfo model properties. The readonly fields of the EstimationInfo structure store estimation settings and results.
Property Name  Description 

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:

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 (GaussNewton 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. 
The states of an idnlgrey model are defined explicitly by the user in the function or MEXfile (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.
get  getinit  getpar  idnlmodel  pem  set  setinit  setpar