function obj = greyestOptions(varargin)
%GREYESTOPTIONS  Creates option set for the GREYEST command.
%
%   OPT = greyestOptions returns the default options for GREYEST. 
%
%   OPT = greyestOptions('Option1',Value1,'Option2',Value2,...) uses
%   name/value pairs to override the default values for 'Option1','Option2',...
%
%   The supported options are:
%
%   InitialState   Handling of initial states (X0) during estimation.
%                  Specify as one of the following:
%                   'model': X0 values are parameterized by the
%                            ODE file used by the IDGREY model. The ODE
%                            file must return 6 or more output arguments.
%                    'zero': X0 is fixed to zero values. Any values
%                            returned by the ODE file are ignored. 
%                'estimate': Initial states are treated as independent
%                            parameters whose values are estimated together
%                            with user-designated parameters of the IDGREY
%                            model.
%                'backcast': X0 is estimated as best least-squares fit.
%                    'auto': Default. Automatic choice of handling scheme.
%                            Interpreted as 'model' if the ODE file returns
%                            6 or more output arguments and the returned
%                            value of X0 is finite. Otherwise, an automatic
%                            choice between 'estimate', 'zero' and
%                            'backcast' is made during estimation based on
%                            the nature of estimation data.
%             Double vector: Specify a column vector of length equal to
%                            number of states. For multi-experiment data,
%                            use a matrix with Ne columns, where Ne =
%                            number of experiments. Specified value is
%                            treated as fixed value.
%
%   DisturbanceModel Handling of disturbance component (K) of model during
%                    estimation. Specify as one of the following:
%                   'model': K values are parameterized by the ODE file
%                            used by the IDGREY model. The ODE file must
%                            return 5 or more output arguments.
%                   'fixed': The value of the "k" property of IDGREY
%                            model is considered fixed to its original
%                            value.
%                   'none' : K is fixed to zero value. Any values
%                            returned by the ODE file are ignored.
%                'estimate': K is treated as an independent parameter and
%                            its entries are estimated together with
%                            user-designated parameters of the IDGREY
%                            model.
%                    'auto': Default. Automatic switching between 'model'
%                            'fixed'. Means 'model' if the ODE file
%                            returns 5 or more output arguments with
%                            finite value for K. Means 'fixed' otherwise.
%                  Note: DisturbanceModel is ignored for frequency domain
%                    estimations (K is fixed to zero).
%
%
%   Focus      Choose between 1-step prediction vs. simulation error
%              minimization. Specify as one of:
%              'prediction': Focus on producing good predictors. Default.
%              'simulation': Focus on making a good fit for simulation (with
%                            the current input).
%  
%   WeightingFilter   Weighting prefilter for estimation. Specify as one of:
%                     []: No weighting prefilter applied. Default.
%              Passbands: Row vector or matrix containing frequency values
%                         that define desired passbands. For example:
%                         [wl,wh]
%                         [w1l,w1h ; w2l,w2h ; w3l,w3h ; ...]
%                         where wl and wh represent lower and upper limits
%                         of a passband. For a matrix with several rows
%                         defining frequency passbands, the algorithm uses
%                         union of frequency ranges to define the
%                         estimation passband. Passbands are expressed in
%                         rad/TimeUnit for time domain data and in
%                         frequency units of the data for frequency domain
%                         data.
%            SISO Filter: Any SISO linear filter specified as one of:
%                         * A SISO linear system.
%                         * {A,B,C,D}, which specifies the state-space
%                           matrices of a discrete-time filter.  
%                         * {numerator, denominator}, which specifies the
%                           numerator and denominator of the filter
%                           expressed as a discrete-time transfer function.
%                 Vector: For frequency-domain data only. Specify as a column
%                         vector of weights. This vector must have the same
%                         size as length of the frequency vector of the
%                         data set (= length(Data.Frequency)).
%  
%   EnforceStability  Force the resulting model to be stable. Default: false.
%
%   EstimateCovariance  Specify whether to estimate parameter covariance (true)
%                       or not (false). Default: true.
%
%   Display       View estimation progress ('on'/'off'/'full'). 
%                 'full' displays parameter values over iterations in
%                 addition to objective function related updates.
%                 You can terminate a running estimation by pressing the
%                 STOP button on the progress viewer window. Default: 'off'.
%   
%   InputInterSample  Intersample behavior of the input signals, which
%                     influences the estimation, simulation and prediction
%                     of continuous-time models. Specify as 'auto' (default),
%                     'zoh','foh','bl'.
%
%   InputOffset   Specifies the offset levels present in the input signals
%                 of the estimation data. Specify as an Nu-element column
%                 vector, where Nu is the number of inputs. For estimations
%                 using multi-experiment data, specify as Nu-by-Ne matrix,
%                 where Ne is the number of experiments. The offset value
%                 InputOffset(i,j) is subtracted from the i:th input signal
%                 of the j:th experiment. Default is [] which implies no
%                 offsets. Available for estimations using time-domain data
%                 only.
%
%   OutputOffset  Specifies the output signal offset levels. Similar
%                 interpretation as InputOffset. The specified values are
%                 subtracted from the output signals before use for
%                 estimation.
%
%   OutputWeight  Weighting of prediction errors in multioutput
%                 estimations. Irrelevant is single output case. Specify as:  
%                 'noise': Optimal weighting is automatically computed as
%                          the inverse of the estimated noise variance.
%                          This amounts to minimizing det(E'*E/N) where E
%                          is the matrix of prediction errors and N is
%                          number of samples.
%                  Matrix: Use a positive semi-definite matrix of size
%                          equal to number of outputs. This amounts to
%                          minimizing trace(E'*E*W/N), where W is the
%                          specified matrix.
%                      []: Default. An automatic choice between 'noise' and
%                          eye(Ny) is made depending upon the nature of
%                          data, where Ny = number of outputs.
%
%   Regularization Options for regularized estimation of model parameters.
%                 Structure with fields:
%                 Lambda:  Constant that determines the bias vs. variance
%                          tradeoff. Specify as nonnegative scalar. Zero
%                          value means no regularization. Default: 0
%                      R:  Weighting matrix. Specify as 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.
%                          Default is 1 which implies a value of
%                          eye(npfree), where npfree = number of free
%                          parameters.
%                Nominal:  The nominal value towards which the free parameters
%                          are pulled during estimation. Specify as "zero"
%                          (pull parameters towards zero) or "model" (pull
%                          parameters towards preexisting values in the
%                          initial idgrey model). Default: "zero"
%
%   SearchMethod  The numerical search method to be used for iterative
%                 refinement. One of:
%                    'gn': Subspace Gauss-Newton least squares search
%                    'lm': Levenberg-Marquardt least squares search
%                   'gna': Subspace Gauss-Newton search with an adaptive
%                          cut-off of singular values. 
%                  'grad': Steepest descent least squares search
%                  'auto': A combination of the above schemes is tried at
%                          each iteration and the descent direction leading
%                          to the most reduction in estimation cost is used.
%                          Default.
%             'lsqnonlin': The trust region reflective algorithm provided
%                          by the Optimization Toolbox. 
%              'fmincon':  Constrained nonlinear solvers. Use
%                          SearchOptions.Algorithm to pick a solver (default
%                          solver: 'sqp').
%
%   SearchOptions Options associated with the search algorithm. The
%                 option set is dependent on the choice of SearchMethod.
%                 Commonly used options:
%                 Tolerance: Search termination tolerance. Specify as a
%                            positive number. Default: 0.01. Not available
%                            for 'lsqnonlin', 'fmincon' (use 'FunctionTolerance' instead).
%             MaxIterations: Maximum number of iterations allowed. Default:
%                            100 for 'fmincon', 20 for others.
%         FunctionTolerance: Similar to Tolerance. Available for
%                            'lsqnonlin' (default 1e-5) and 'fmincon'
%                            (default: 1e-6).
%             StepTolerance: Termination tolerance on parameter value
%                            change. Available for 'lsqnonlin' and 'fmincon'.
%                            Default: 1e-6.
%                 Algorithm: Available for 'fmincon' only. Set to one of:
%                            - 'sqp' (default)
%                            - 'trust-region-reflective'
%                            - 'interior-point' (requires Optimization Toolbox)
%                            - 'active-set' (requires Optimization Toolbox)          
%                 Refer to the "greyestOptions" documentation for
%                 information on all available search options.
%
%   Advanced      Structure with fields ErrorThreshold, MaxSize,
%                 StabilityThreshold, AutoInitThreshold. Type "doc
%                 greyestOptions" for more information.                        
%
% See also GREYEST, IDFILT.

%   Author(s): Rajiv Singh
%   Copyright 2011-2017 The MathWorks, Inc.

try
   obj = initOptions(idoptions.greyest,varargin);
catch E
   throw(E);
end
