function obj = simOptions(varargin)
%SIMOPTIONS  Creates option set for the simulation of identified models.
%
%   OPT = SIMOPTIONS returns the default options for IDMODEL/SIM method.
%
%   OPT = SIMOPTIONS('Option1',Value1,'Option2',Value2,...) uses name/value
%   pairs to override the default values for 'Option1','Option2',... 
%
%   The supported options are:
%   
%   InitialCondition    Handling of initial conditions for simulation.
%                One of the following:
%                'z': Zero initial conditions.
%                 X0: A column vector of length equal to the order of the
%                     model (Nx). For use with multiexperiment data, use a
%                     matrix with Ne columns, where Ne = number of
%                     experiments. For state-space models (idss, idgrey,
%                     idnlgrey) only.
%           IOStruct: A structure with fields 'Input' and 'Output', each
%                     containing a history of input and output variables
%                     before the start time of Data (time < Data.Tstart).
%                     In case of a time series model, 'Input' value is
%                     empty. The number of columns must always be equal to
%                     the number of input/output channels and the number of
%                     rows must be greater than or equal to the model
%                     order. For use with multiexperiment data, use a
%                     struct array of Ne elements.
%           PASTData: Specified as a timetable object, an IDDATA object, or 
%                     a pair of numeric matrices containing input and output
%                     signal values. For multiexperiment data, use a cell
%                     array of timetables, an IDDATA object, or a pair of
%                     cell arrays of numeric matrices containing input and
%                     output signal values.
%           ICObject: An initialCondition object representing a free
%                     response model. For use with multiexperiment data,
%                     use a [1 Ne] array of objects, where Ne = number of
%                     data experiments.
%
%             For an IDNLGREY model SYS, InitialCondition can also be:
%            'model': SYS.InitialStates determines the values of the
%                     initial states to use for simulation.
%            Default: []. Interpreted as 'model' for IDNLGREY models and
%                     'z' for all others.
%
%  X0Covariance   Covariance of initial states vector X0. Use for
%                 computation of response standard deviations of
%                 state-space models (idss, idgrey, idnlgrey) when initial
%                 conditions are specified as a numerical vector. Specify
%                 as a Nx-by-Nx positive definite matrix, where Nx = model
%                 order.  For simulation using multi-experiment data,
%                 specify as an Nx-by-Nx-by-Nexp array such that
%                 X0Covariance(:,:,kexp) specifies the covariance of
%                 initial states X0(:,kexp). Default: [] (implies no
%                 uncertainty in X0 value)
%
%   InputOffset   Input signal offset level. Specify as an Nu-element column
%                 vector, where Nu is the number of inputs. For simulation
%                 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 before it is used for simulation.
%                 Default is [] which implies no offsets. For simulation
%                 using time domain data only.
%
%   OutputOffset  Output signal offset. Similar arrangement as InputOffset
%                 for model output. The specified values are added to the
%                 response of the model.
%
%   AddNoise      Specify whether noise should be added to the response of
%                 the model (TRUE/FALSE). Default is FALSE (no noise
%                 addition). 
%
%   NoiseData     Noise signal "e" in y = Gu + He, where G is the input (u)
%                 to output (y) transfer function, and H is the noise
%                 transfer function. Used only if AddNoise is TRUE. Specify
%                 as: 
%                 []: Default. A realization of noise "e" is
%                     automatically generated as a Gaussian random
%                     sequence.
%             Matrix: a double matrix of size Ns-by-Ny, where Ns is the
%                     number of input data samples and Ny is the number of
%                     outputs. The noise NoiseData(:,ky) is added to the
%                     output y(:,ky), ky = 1:Ny. The noise is scaled
%                     according to the "NoiseVariance" property of
%                     identified model sys. To obtain the right noise level
%                     consistent with the model, NoiseData should be white
%                     noise with zero mean and unit covariance matrix.
%         Cell array: If the input u is a multi-experiment dataset, you can
%                     specify NoiseData as a cell array of Ne matrices, one
%                     for each data experiment, where Ne = number of
%                     experiments.
%
%  OutputTimes    Time range or points over which the outputs must be computed. Used for
%                 idNeuralStateSpace model simulation only. 
%                 Specify as one of:
%                    - Time span [tMin, tMax], where tMin, tMax are expressed in the time units of
%                      the model. 
%                    - Time vector: A double column vector. For models with inputs, the time vector
%                      must be contained inside the time span of the simulation inputs. For the
%                      discrete-time models, the time interval must match the model sample time (Ts).
%                    - Cell array: For multi-experiment simulations. Array of time spans or time
%                      vectors, one value for each data experiment.
%                 OutputTimes need not be specified for simulation of models with input channels
%                 (size(model,2)>1); if OutputTimes = [], the output sample times are chosen
%                 to be the same as those of the input signal. For models with no inputs (time
%                 series models), a non-empty value for OutputTimes must be specified.
%
% See also idmodel/sim, initialCondition, lsim, idNeuralStateSpace.

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

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