function [LLF , x , y] = garch11grid(ySeries , C , K , x , y)
%GARCH11GRID Univariate GARCH(1,1) default model grid evaluation.
%   Given an observed univariate return series and parameters of the GARCH 
%   Toolbox default model, evaluate the log-likelihood objective function on a
%   grid in the plane defined by the conditional variance parameters. The 
%   default model assumes a return series, y(t), is a constant with GARCH(1,1)
%   Gaussian innovations, e(t), and conditional variance h(t),
%
%   Conditional Mean:     y(t) = C + e(t)
%   Conditional Variance: h(t) = K + G(i)h(t-1) + A(j)e^2(t-1)
%
%   The grid is defined at the intersection of the G(i) and A(j) coefficients
%   in the (X,Y) plane.
%
%   [LLF , X , Y] = garch11grid(Series , C , K)
%   [LLF , X , Y] = garch11grid(Series , C , K , GarchValues , ArchValues)
%
%   Optional Inputs: GarchValues, ArchValues
%
% Inputs:
%   Series - Vector of observations of the univariate return series 
%     of interest (i.e., the y(t) series). Series is the variable fit to the
%     constant conditional mean/GARCH(1,1) conditional variance default model.
%     The last element of Series holds the most recent observation.
%
%   C - Scalar constant of the conditional mean equation.
%
%   K - Positive, scalar constant of the conditional variance equation.
%
% Optional Inputs:
%   GarchValues - Vector of X-axis values at which the GARCH coefficient (i.e., 
%     the G(i) parameter) is used to evaluate the log-likelihood function. If
%     empty or unspecified, the default is [0:0.025:1].
%
%   ArchValues - Vector of Y-axis values at which the ARCH coefficient (i.e., 
%     the A(j) parameter) is used to evaluate the log-likelihood function. If
%     empty or unspecified, the default is [0:0.025:1].
%
% Outputs:
%   LLF - Matrix of log-likelihood objective function values given the input C 
%     and K values, evaluated on a grid defined by the intersection of 
%     GarchValues and ArchValues. GarchValues correspond to the X-axis and 
%     determine the number of columns in LLF; the ArchValues correspond to the 
%     Y-axis and determine the number of rows in LLF. Thus, LLF will be a 
%     matrix of size length(ArchValues)-by-length(GarchValues). Constraint 
%     violations for which G(i) + A(j) >= 1 are indicated by NaN's.
%
%   X - Vector of GarchValues (i.e., G(i)) values that define the X-axis of the
%     grid. X is a convenience output vector to facilitate subsequent graphical
%     analysis.
%
%   Y - Vector of ArchValues (i.e., A(j)) values that define the Y-axis of the
%     grid. Y is a convenience output vector to facilitate subsequent graphical
%     analysis.
%
% Example:
%   Assume Series is a vector of returns. Evaluate the objective on the default
%   grid,
%
%     [LLF , X , Y] = garch11grid(Series , 0 , 0.0005);
%
%   and display 3-D surface and 2-D contour plots,
%
%     figure , surf(X, Y, LLF)
%     xlabel('GARCH Coefficient') , ylabel('ARCH Coefficient')
%     figure , contour(X , Y , LLF, 200);
%     xlabel('GARCH Coefficient') , ylabel('ARCH Coefficient')
%
% See also GARCHFIT, GARCHLLFN, GARCHSET.

%   Copyright 1999-2002 The MathWorks, Inc.   
%   $Revision: 1.5 $  $Date: 2002/03/11 19:50:12 $

%
% Check observed return series vector y(t).
%

if prod(size(ySeries)) == length(ySeries)   % Check for a vector (single return series).
   ySeries  =  ySeries(:);                  % Convert to a column vector.
else
   error(' Observed return series ''Series'' must be a vector.');
end

%
% Ensure the conditional mean constant (C) is a scalar, and 
% the conditional variance constant (K) is a positive scalar.
%

if nargin >= 3
   if prod(size(C)) ~= 1    % Check for a scalar.
      error(' Conditional mean constant ''C'' must be a scalar.');
   end
   if (prod(size(K)) ~= 1) | (K <= 0)    % Check for a scalar.
      error(' Conditional variance constant ''K'' must be a positive scalar.');
   end
else
   error(' At least 3 inputs are required (''Series'',''C'',''K''.');
end

%
% Ensure the (x,y) = (GARCH,ARCH) inputs are vectors 
% between (0,1), and set defaults if necessary.
%

if (nargin >= 4) & ~isempty(x)
   if prod(size(x)) ~= length(x)    % Check for a vector.
      error(' ''GarchGrid'' must be a vector.');
   end
   x  =  x(:);
   if any(x < 0) | any(x > 1)
      error(' ''GarchGrid'' must be between (0,1).')
   end
else
   x  =  [0:0.025:1]';
end

if (nargin >= 5) & ~isempty(y)
   if prod(size(y)) ~= length(y)    % Check for a vector.
      error(' ''ArchGrid'' must be a vector.');
   end
   y  =  y(:);
   if any(y < 0) | any(y > 1)
      error(' ''ArchGrid'' must be between (0,1).')
   end
else
   y  =  [0:0.025:1]';
end

%
% Initialize the GARCH Toolbox default model:
%
%    Conditional Mean:     y(t) = C + e(t)
%    Conditional Variance: h(t) = K + G(1)h(t-1) + A(1)e^2(t-1)

spec = garchset;
spec = garchset(spec , 'C' , C , 'K' , K);

%
% Evaluate the Log-Likelihood function on the (x,y) grid in
% GARCH/ARCH coefficient space, given the constants C and K.
%

LLF  =  NaN;
LLF  =  LLF(ones(length(y) , length(x)));

for i = 1:length(x)

    spec.GARCH  =  x(i);

    for j = 1:length(y)

        spec.ARCH  =  y(j);

        if (x(i) + y(j)) < 1
           [e , s , LLF(j,i)] = garchinfer(spec , ySeries , []);
        end
    end

end