                     Notes to the bond class, bond.cc

General and historic notes:
	
   Bonds are issued by the United States Treasury, state and local
governmental units, corporations and others to finance various
projects. Until recently, a bond was typically a large sheet of
expensive paper engraved with eye-numbing lawyerese and with its
right-hand half consisting of a set of coupons, one dated each
six months until and including the day of maturity of the bond.
The bond owner would clip each coupon when due and deposit it in
his bank account; the bank would remit the coupons through a
clearinghouse to the issuer for collection. On the maturity date
of the bond, the owner would surrender it as well, for payment
to him or her of the face value. The effect was that the bond
owner received interest every six months and the principal amount
of the bond at maturity.

   Increasingly, bonds are maintained as computer entries and the 
the interest paid by electronic transfer, but the structure developed
in earlier times remains. Its principal features are:

      Interest is paid semiannually, but the stated rate of
      interest is an annual percentage. A 6.00% bond bears
      two coupons per year, or otherwise pays interest twice
      a year, on each occasion in an amount equal to 3% of
      the face amount. Interest dates are the dates exact
      multiples of six months before the maturity date. On
      the maturity date, the owner receives the proceeds of
      the last coupon plus the face amount of the bond.

      Prices for bonds are stated in terms of "par", or the
      price of a bond of $100 face amount, regardless of the
      minimum denomination of bond actually issued. In fact,
      a minimum denomination of $5,000 face amount is usual, 
      so the minimum investment in such bonds priced at $99
      is 99/100 of $5,000, or $4,950. Each coupon of a 6.00% 
      $5,000 bond will be worth $150 on its due date.

      So that the price may be free of the daily adjustment
      otherwise required to reflect the approach of the date 
      on which the next coupon is paid, the purchaser pays the
      seller both the quoted price and the amount of interest
      earned through the settlement date (the date payment for
      and delivery of the bond are mutually due, which may be
      some days after the trade is agreed) on the current 
      coupon. If settlement occurs on a coupon date, the seller
      delivers the coupon and the purchaser pays its face value.

      Some bonds such as Treasury bonds are traded on the 
      "actual/actual" basis, which means that calendar 
      calculations are based on the actual calendar days 
      between any two relevant dates. Other bonds such as
      many corporate, state and municipal bonds are traded on
      the "30/360" basis, equating a year to 12 months of 30
      days each. This affects the amount calculated to be due
      to the seller for the current coupon and may also affect
      the yield or the price.

Using the Bond Class:

      At minimum, you must create an object of the class and set three
properties of the object:

             settledate   -- the date of settlement of the transaction
                             (purchase or sale of the bond)
             maturedate   -- the date the bond matures
             CPN	  -- the annual stated interest rate, such 
                             as 6.00 for 6% annual interest, two 
                             payments of 3.00 per each $100 of face
                             amount of the bond.
                             
With these properties set you may call on the method finddate() to 
find the date on which the first coupon is payable and the method
findcoupon() to find the amount (in dollars per $100 of face amount
of the bond) due from the purchaser of the bond to the seller as the
prorated value of the first coupon.

   If you want to know what a bond will actually cost you, add the amount
returned by findcoupon() to the price, and of course multiply the result
by the face amount/100 of the bonds you are buying. If you are buying 
$20,000 of XYZ 6.25% bonds at $98.50 and findcoupon() returns 3.22,
your total cost is $101.72 "per bond" or 20000/100 times as much,
$20,344, for the entire purchase. Some bond dealers will also charge
a small amount for postage or the like. 

   The remaining two accessible methods of the class require you to set 
the yield property of your bond object in order to find a price or to
set the price property in order to find a yield. In either case you must
also set the three properties listed above.

   Commonly, you will know the yield to maturity you desire or require
and need to know the price that will result in that yield. This is 
returned by the findprice() method of the class when you supply the
yield; the price returned is in "dollars per bond", such as 101.32 
meaning that each $100 face amount will cost you $101.32 plus the first
coupon.

   If you know the price at which a bond is offered and want to know
the yield to maturity in order to compare it to an investment you
believe equal in risk, set the price property of the bond object and
call findyield(). The yield will be returned as an annualized percentage,
such as 7.3276 meaning the investment yields 7.3276% if held to maturity.
You can similarly use findyield() if you know what yield is appropriate
and wish to set the price accordingly.

   The findyield() function operates by trial and error using the 
findroot() function of the Root class, guessing that it will soon be
able to select a yield that will result in an exactly-matching price.
The accuracy of result returned (by default .0001% of yield), iterations
allowed before an error is returned, initial range for estimating the
yield or other properties may have to be adjusted to obtain a result 
efficiently. All of these are represented as properties of the Bond
class; you may change them for your bond and the correct values will be
passed to findroot() automatically. If a call returns -4, the range is
too small and you must increase the range property of the bond object.
This may occur if the maturity of a bond is very short or its price is
greatly different from par, or both. 

   You should set the "actual" property of your bond object to agree
with the basis, actual/actual or 30/360, used in the market in which
such bonds are quoted or traded.  
 	
   A trivial form, bond.wfm, is provided with bond.cc and this file to
illustrate use of the Bond class.   

Source notes:

   The proposition that the buyer pays for and the seller delivers
the coupon if settlement occurs on a coupon payment date is
stated to be the standard practice by two brokers polled. In using
this class for a market in which this is not the practice (the
alternative is that the seller keeps the mature coupon and the 
purchaser pays nothing for it) change the code of calcdays() to add
6 months to this.firstcoupondate if it is equal to this.settledate,
and replace the int(??)+1 with ceiling(??) in the two calculations of
this.N. This will cause N to be 1 for bonds of exactly six months and
will thereby use the first of the SIA formulas below for such bonds. 

   The "Days360" formula is adapted from the Owner's Handbook for 
the Hewlett-Packard HP-12C financial calculator, pp. 208-209.
Related calculations such as that of "this.N" in calcdays()
were derived by trial of various possibilities against the
results returned by the HP-12C for the same data.

   The two price formulas are taken from the HP-12C handbook as
attributed by it to "Standard Securities Calculation Methods"
by Spence, Graudenz and Lynch, Securities Industry Association,
New York, 1973. No effort has been made to consult the latest
version of that work, which is offered for sale by the 
Securities Industry Association for amounts far beyond the 
budget of the programmers. Note that the first formula will
work in the case of a bond with exactly six months to 
maturity only on the assumption that the coupon due on the
settlement date is retained by the seller, which is contrary
to industry practice; it is not used herein for such bonds.

   Securities Industry Association formulas:

   price of a bond with six months or less to maturity:

      PRICE = 100*(RDV+CPN/2) / (100 + DSM/E * YIELD/2) ;
                 - DCS/E*CPN/2 

   price of a longer bond:

      PRICE  = RDV/(1+YIELD/200)^(N-1+DSC/E) ;
                 + [ sum for K = 1 to N of: ;
                     CPN/2/(1+YIELD/200)^(K-1+DSC/E)] ;
                 - DCS/E*CPN/2

   The first of the price formulas converts mathematically to

      YIELD = 200*E/DSM*((RDV+CPN/2)/ ;
                  (PRICE + DCS/E*CPN/2) - 1)

   As written, the properties of the Bond class use the same terms
as the SIA formulas:   
                  
      CPN   = The stated annual interest rate paid by semiannual 
                 coupon. Note that because the rate is annual but the
                 coupons semiannual, a 7% $100 bond with a CPN of 7% 
                 will have each coupon pay $3.50. Coupon rates, like 
                 yields, are stated as percentages, 7% = 7.00.
      DCS   = Days in the coupon period in which settlement occurs
                 that precede the settlement date (this value is not 
                 used as a property of the class).
      DSC   = Days from the settlement date to the end of the 
                 current coupon period, E - DCS.
      DSM   = Days from the settlement date to the maturity date 
         	 of the bond.
      E     = Whole number of days in the first coupon period.
      N     = Number of coupons payable from settlement through 
                 maturity.
      PRICE = The price quoted for a $100 bond, or the price that
                 will yield the given yield to maturity.
      RDV   = Redemption value. Usually $100 for a $100 bond. If 
              the bond is callable, recalculate the price or yield
              using the call price and call date in place of the
              redemption value and maturity date.  		
      YIELD = The yield to maturity required, or calculated for the
                 given price. For consistency with the Securities 
                 Industry Association formulas, yields are stated as
                 percentages, so that a yield to maturity of six 
                 percent per annum is 6.00, not 0.06.

   If you wish to relate the formulas used in the methods of the
Bond class to the formulas above, you should note that one term of
each of the two SIA formulas is "DCS/E*CPN/2." This is the amount
of the first coupon, CPN/2, multiplied by the portion of the coupon
period (E) expired at the settlement (DCS) and is the same as the
firstcouponcost property used in the class and the return value of
findcoupon(). It appears as a subtraction in the SIA formulas because
they operate by calculating the entire amount payable by the purchaser
to achieve the given yield, then subtracting out this separately-stated
component to arrive at the quoted price. 

   The class uses the equivalent (E - DSC) for DCS and the fracleft
property as shorthand for DSC/E. It also simplifies the summation of
K from 1 to N of the coupon values; instead of calculating each 
successive term anew by raising (1 + yield/200) to a new power involving
the increased K and dividing, it starts with the first term and divides
it by y = (1 + yield/200) for the next term, since dividing the term by
y is the equivalent of raising y in the divisor to a power one larger.


                                                Jay Parsons
                                                October 30, 1996
                                      