function BKTimeSpec = bktimespec(varargin)
%BKTIMESPEC Specify time structure for a Black Karasinski(BK) tree.
%   Set the number of levels and node times for a BK tree, and
%   determine the mapping between dates and time for rate quoting.
%   
%   TimeSpec = bktimespec(ValuationDate, Maturity)
%   TimeSpec = bktimespec(ValuationDate, Maturity, Compounding)
%
% Inputs:
%   ValuationDate - Scalar date marking the pricing date and first observation
%                   in the tree. Specify ValuationDate as a serial date number 
%                   or date string.
%
%   Maturity      - NLEVELS x 1 vector of dates marking the cash flow
%                   dates of the tree.  Cash flows with these maturities will fall 
%                   on tree nodes.  This argument determines the number of levels, 
%                   or depth, of the tree.  Maturity should be in increasing order.
%
% Optional Inputs:
%   Compounding   - Scalar value representing the frequency at which the rates
%                   are compounded when annualized. Default = -1 (continuously compounded).
%                   This argument determines the formula for the discount  
%                   factors and interpretation of times as follows: 
%     1) Compounding = 1, 2, 3, 4, 6, 12 = F
%        Disc = (1 + Z/F)^(-T), where F is the compounding frequency,
%        Z is the zero rate, and T is the time in periodic units, i.e. T=F
%        is one year.
%     2) Compounding = 365 
%        Disc = (1 + Z/F)^(-T), where F is the number of days in the
%        basis year and T is a number of days elapsed computed by basis.
%     3) Compounding = -1 
%        Disc = exp( -T * Z ), where T is time in years.
%
% Output:
%   TimeSpec - Structure specifying the time layout for BKTREE.  The
%              state observation dates are [ValuationDate; Maturity(1:end-1)].  
%              Because a forward rate is stored at the last observation, the 
%              tree can value cash flows out to Maturity(end).
%
% See also BKTREE, BKVOLSPEC, HWTREE.

%   Copyright 1998-2005 The MathWorks, Inc.


%-----------------------------------------------------------------------
% Argument parsing and defaults
%-----------------------------------------------------------------------

% Insure that there are 2 argument variables
if nargin<2,
  error(message('fininst:bktimespec:NotEnoughArgs')); 
end

BKTimeSpec = trintimespec('BKTimeSpec', varargin{:});



