<!--
      (Do not remove this comment block.)
  Version: 1.8.4
  Last modified: April 10th 2004
  Maintainers: 
               Chris Lyttle <chris@wilddev.net>
  Author:
  		Jon Lapham <lapham@extracta.com.br>
  Originally designed by Carol Champagne.
  Translators:
               (translators put your name and email here)
-->
 <chapter id="chapter7">
 <title>Loans</title>
 <para>
 This chapter explains how to manage your loans with GnuCash. 
  </para>
 <sect1 id="loans_concepts1">
 <title>Basic Concepts</title>
 <para>A loan is defined as a financial transaction in which someone pays for the use of someone else's money.  There are many familiar examples of loans: credits cards, auto loans, house mortgages, or a business loan.</para>

 <sect2 id="loans_conceptsterms2">
 <title>Terminology</title>
  <para>
Before discussing tracking loan in GnuCash specifically, it will be helpful to present a glossary of terminology.  The terms presented below represent some of the basic concepts found concerning loans.  It is a good idea to become familiar with these terms, or at least, refer back to this list if you encounter an unfamiliar word in the later sections.
  </para>

  <itemizedlist>
  <listitem>
  <para><emphasis>Amortization</emphasis> - the repayment plan which will insure that a loan is eventually paid off, typically utilizing equal valued monthly payments.  These payments are usually split into principal and interest, where the amount of principal per payment increases (and interest decreases) as the amortization period elapses.</para>
  </listitem>
  <listitem>
  <para><emphasis>Borrower</emphasis> - the person or company that receives the money from a loan.</para>
  </listitem>
  <listitem>
  <para><emphasis>Default</emphasis> - when a borrower fails to repay a loan according to the terms agreed upon with the lender.</para>
  </listitem>
  <listitem>
  <para><emphasis>Deferment</emphasis> - a temporary delay in the repayment of a loan.</para>
  </listitem>
  <listitem>
  <para><emphasis>Delinquency</emphasis> - is the term that refers to late payments.</para>
  </listitem>
  <listitem>
  <para><emphasis>Disbursement</emphasis> - amount of the loan paid to the borrower.  Some loans have multiple disbursements, meaning the borrower does not receive the full amount of the loan at one time.</para>
  </listitem>
  <listitem>
  <para><emphasis>Interest</emphasis> - the expense charged by the lender to the borrower for the use of the money loaned.  This is typically expressed in terms of a yearly percentage charged on the principal borrowed, known as the <emphasis>Annual Percentage Rate</emphasis> or APR.</para>
  </listitem>
  <listitem>
  <para><emphasis>Lender</emphasis> - the company or person who lends money to a borrower.</para>
  </listitem>
  <listitem>
  <para><emphasis>Loan Fee</emphasis> - a processing fee removed from the principal at the time the borrower receives a loan.</para>
  </listitem>
  <listitem>
  <para><emphasis>Principal</emphasis> - the original amount of the loan, or the amount of the original loan that is still owed.  When you make a monthly payment on a loan, part of the money pays the interest, and part pays the principal.</para>
  </listitem>
  <listitem>
  <para><emphasis>Promissory Note</emphasis> - the legal agreement between the borrower and lender concerning the loan.</para>
  </listitem>
  </itemizedlist>

  </sect2>
 </sect1>

 <sect1 id="loans_accounts1">
 <title>Setting Up Accounts</title>
 <para>When a borrower obtains a loan, it is usually with the intention to make a purchase of something of value.  In fact, most loans require the borrower to buy some predetermined asset, such as a house.  This asset is insurance against the borrower defaulting on the loan.  There are, of course, examples of loans which do not necessarily have an associated high value asset, such as educational loans.</para>
  <para>For the account structure presented here, we will assume the loan was used to purchase a compensating asset.</para>
  <para>A loan is a liability, the interest you accrue on the loan is an on-going expense, and any administrative fees you may have to pay would be another expense.  The thing purchased with the money from a loan is an asset.  With these parameters, we can now present a basic loan account structure: </para>

  <literallayout>
Basic Loan Account Structure

-Asset
   -Bank Account
   -Asset Purchased
-Liability
   -Loan
-Expenses
   -Loan Interest
   -Loan Admin Fees
  </literallayout>

<para>GnuCash has a number of predefined loan account hierarchies available, including Car Loans and Home Mortgage Loans.  To access these predefined account structures, click on <guimenu>File</guimenu> -> <guimenu>New File</guimenu> and select the loan types in which you are interested.</para>

 </sect1>

 <sect1 id="loans_mortgage1">
 <title>House Mortgage (How-To)</title>
 <para>A house mortgage can be setup using the account structure present in the previous section.</para>
 <para>As an example, assume you have $60k in you bank account, and you buy a $150k house.  The mortgage is charging 6% APR, and has administrative fees (closing costs, etc) of 3%.  You decide to put $50k down, and thus will need to borrow $103k, which will give you $100 after the closing costs are paid (3% of $100k).</para>
  <para>You accounts before borrowing the money:</para>

	<screenshot id="loans_mortgage">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/loans_mortgage1.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Accounts Before Receiving Loan</phrase>
	    </textobject>
	    <caption>
	       <para>Accounts Before Receiving Loan</para>
	    </caption>
          </mediaobject>
        </screenshot>
 
   <para>The purchase of the house is recorded with a split transaction in the Asset:House account, with $50k coming from the bank (IE: your down payment), and $100k coming from the Mortgage.  You can place the $3k closing costs in the same split.</para>

 <para>
  <table>
  <title>Buying a House Split Transaction</title>
  <tgroup cols="3">
  <tbody>
  <row>
<entry>Account</entry><entry>Increase</entry><entry>Decrease</entry>
  </row>
  <row>
<entry>Assets:House</entry><entry>$150,000</entry><entry></entry>
  </row>
  <row>
<entry>Assets:Bank</entry><entry></entry><entry>$50,000</entry>
  </row>
  <row>
<entry>Liabilities:Mortgage</entry><entry></entry><entry>$103,000</entry>
  </row>
  <row>
<entry>Expenses:Mortgage Adm Fees</entry><entry>$3000</entry><entry></entry>
  </row>
  </tbody>
  </tgroup>
  </table>
 </para>
 <para>The split will look like this in the Assets:House Account:</para>

	<screenshot id="loans_mortgage2.png">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/loans_mortgage2.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Mortgage Split Transaction</phrase>
	    </textobject>
	    <caption>
	       <para>Mortgage Split Transaction</para>
	    </caption>
          </mediaobject>
        </screenshot>

 <para>Which will give account totals like this:</para>
 	<screenshot id="loans_mortgage3">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/loans_mortgage3.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Mortgage Accounts</phrase>
	    </textobject>
	    <caption>
	       <para>Mortgage Account</para>
	    </caption>
          </mediaobject>
        </screenshot>
 

 </sect1>

 <sect1 id="loans_calcs1">
 <title>Calculations</title>
 <para>Determining loan amortization schedules, periodic payment amounts, total payment value, or interest rates can be somewhat complex.  To help facilitate these kinds of calculations, GnuCash has a built-in Financial Calculator.  To access the calculator, go to <guimenu>Tools</guimenu> -> <guimenu>Financial Calculator</guimenu>.</para>
 
 	<screenshot id="loans_fcalc">
	  <mediaobject>
	    <imageobject>
	      <imagedata fileref="figures/loans_fcalc.png" 
	      srccredit="Jon Lapham" format="PNG"/>
            </imageobject>
	    <textobject>
	        <phrase>Financial Calculator</phrase>
	    </textobject>
	    <caption>
	       <para>The GnuCash Financial Calculator.</para>
	    </caption>
          </mediaobject>
        </screenshot>

<para>The Financial Calculator can be used to calculate any one of the parameters: <guilabel>Payment Periods</guilabel>, <guilabel>Interest Rate</guilabel>, <guilabel>Present Value</guilabel>, <guilabel>Periodic Payment</guilabel>, or <guilabel>Future Value</guilabel> given that the other 4 have been defined.  You will also need to specify the compounding and payment methods.</para>

  <itemizedlist>
  <listitem>
  <para><emphasis>Payment Periods</emphasis> - the number of payment periods.</para>
  </listitem>
  <listitem>
  <para><emphasis>Interest Rate</emphasis> - the nominal interest rate of the loan, ie: the yearly interest rate.</para>
  </listitem>
  <listitem>
  <para><emphasis>Present Value</emphasis> - the present value of the loan, ie: current amount owed on the loan.</para>
  </listitem>
  <listitem>
  <para><emphasis>Periodic Payment</emphasis> - the amount to pay per period.</para>
  </listitem>
  <listitem>
  <para><emphasis>Future Value</emphasis> - the future value of the loan, ie: the amount owed after all payment periods are over.</para>
  </listitem>
  <listitem>
  <para><emphasis>Compounding</emphasis> - two interest compounding methods exist, discrete or continuous.  For discrete compounding select the compounding frequency from the popup menu with a range from yearly to daily.</para>
  </listitem>
  <listitem>
  <para><emphasis>Payments</emphasis> - the popup menu allows you to select the payment frequency with a range from yearly to daily.  You can also select whether your payments occur at the beginning or end of the period.  Payments made at the beginning of the payment period have interest applied to the payment as well as any previous money paid or money still owed.</para>
  </listitem>
  </itemizedlist>


  <sect2 id="loans_calcsexample1_2">
  <title>Example: Monthly Payments</title>
  <para>What is your monthly payment on a $100000 30 year loan at a fixed rate of 4% compounded monthly?</para>
  <para>This scenario is shown in the example image above.  To perform this calculation, set Payment Periods to 360 (12 months x 30 years), Interest Rate to 4, Present Value to 100000, leave Periodic Payment empty and set Future Value to 0 (you do not want to owe anything at the end of the loan).  Compounding is Monthly, Payments are Monthly, assume End of Period Payments, and Discrete Compounding.  Now, click on the <guibutton>Calculate</guibutton> button next to the Periodic Payment area.  You should see -473.30.</para>
  <para>Answer: You must make monthly payments of 473.30.</para>
 </sect2>

  <sect2 id="loans_calcsexample2_2">
  <title>Example: Length of Loan</title>
<para>How long will you be paying back a $20000 loan at 10% fixed rate interest compounded monthly if you pay $500 per month?</para>
  <para>To perform this calculation, leave Payment Periods empty, set Interest Rate to 10, Present Value to 20000, Periodic Payment is -500, and set Future Value is 0 (you do not want to owe anything at the end of the loan).  Compounding is Monthly, Payments are Monthly, assume End of Period Payments, and Discrete Compounding.  Now, click on the <guibutton>Calculate</guibutton> button next to the Payment Periods area, you should calculate 48.</para>
   <para>Answer: You will pay off the loan in 4 years (48 months).</para>
 </sect2>

  <sect2 id="loans_calcsdetails2">
  <title>Advanced: Calculation Details</title>
  <para>In order to discuss the mathematical formulas used by the Financial Calculator, we first must define some variables.

<literallayout>
 n  == number of payment periods
 %i  == nominal interest rate, NAR, charged
 PV  == Present Value
 PMT == Periodic Payment
 FV  == Future Value
 CF == Compounding Frequency per year
 PF == Payment Frequency per year

Normal values for CF and PF are:
   1   == annual
   2   == semi-annual
   3   == tri-annual
   4   == quaterly
   6   == bi-monthly
   12  == monthly
   24  == semi-monthly
   26  == bi-weekly
   52  == weekly
   360 == daily
   365 == daily
</literallayout>
</para>

  <sect3 id="loans_calcsdetails_i2">
  <title>Converting between nominal and effective interest rate</title>

  <para>When a solution  for n, PV,  PMT or FV  is required, the nominal interest rate (i) must first be converted to the effective interest rate per payment period (ieff). This rate, ieff, is then used to compute the selected variable.  When a solution for i is required, the computation produces the effective interest rate (ieff).  Thus, we need functions which convert from i to ieff, and from ieff to i.</para>

<literallayout>
To convert from i to ieff, the following expressions are used:
Discrete Interest:     <emphasis>ieff = (1 + i/CF)^(CF/PF) - 1</emphasis>
Continuous Interest: <emphasis>ieff = e^(i/PF) - 1 = exp(i/PF) - 1</emphasis>

To convert from ieff to i, the following expressions are used:
Discrete Interst:      <emphasis>i = CF*[(1+ieff)^(PF/CF) - 1]</emphasis>
Continuous Interest: <emphasis>i = ln[(1+ieff)^PF]</emphasis>
</literallayout>

<note>
<para>NOTE: in the equations below for the financial transaction, all interest rates are the effective interest rate, ieff.  For the sake of brevity, the symbol will be shortened to just 'i'.</para>
</note>
  </sect3>

  <sect3 id="loans_calcsdetails_basic2">
  <title>The basic financial equation</title>

<para>One equation fundamentally links all the 5 variables.  This is known as the fundamental financial equation:</para>

<literallayout>
<emphasis>PV*(1 + i)^n + PMT*(1 + iX)*[(1+i)^n - 1]/i + FV = 0</emphasis>

  Where: X = 0 for end of period payments, and
         X = 1 for beginning of period payments
</literallayout>
<para>From this equation, functions which solve for the individual variables can be derived.  For a detailed explanation of the derivation of this equation, see the comments in the file src/calculation/fin.c from the GnuCash source code.  The A, B, and C variables are defined first, to make the later equations simpler to read.</para>

<literallayout>
<emphasis>A = (1 + i)^n - 1</emphasis>
<emphasis>B = (1 + iX)/i</emphasis>
<emphasis>C = PMT*B</emphasis>

<emphasis>n = ln[(C - FV)/(C + PV)]/ln((1 + i)</emphasis>
<emphasis>PV = -[FV + A*C]/(A + 1)</emphasis>
<emphasis>PMT = -[FV + PV*(A + 1)]/[A*B]</emphasis>
<emphasis>FV = -[PV + A*(PV + C)] </emphasis>

The solution for interest is broken into two cases.  
The simple case for when  PMT == 0 gives the solution:
<emphasis>i = [FV/PV]^(1/n) - 1</emphasis>

</literallayout>
<para>The case where PMT != 0 is fairly complex and will not be presented here.  Rather than involving an exactly solvable function, determining the interest rate when PMT !=0 involves an iterative process.  Please see the src/calculation/fin.c source file for a detailed explanation.
</para>
  </sect3>

  <sect3 id="loans_calcsdetails_ex2">
  <title>Example: Monthly Payments</title>
  <para>Let's recalculate the examples shown above, this time using the mathematical formulas rather than the Financial Calculator.  What is your monthly payment on a $100000 30 year loan at a fixed rate of 4% compounded monthly?</para>
  <para>First, let's define the variables:  n = (30*12) = 360, PV = 100000, PMT = unknown, FV = 0, i = 4, CF = PV = 12, X = 0 (end of payment periods).</para>
  <para>The second step is to convert the nominal interest rate (i) to the effective interest rate (ieff).  Since the interest rate is compounded monthly, it is discrete, and we use: ieff = (1 + i/CF)^(CF/PF) - 1, which gives ieff = (1 + 4/12)^(12/12) - 1, thus ieff = 1/3 = 0.3333333.</para>
  <para>Now we can calculate A and B.  A = (1 + i)^n - 1 = (1 + 1/3)^360 - 1 = 9.504848x10^44.  B = (1 + iX)/i = (1 + 0.33333*0)/0.33333 = 3.</para>
  <para>With A and B, we can calculate PMT.  PMT = -[FV + PV*(A + 1)]/[A*B] = -[0 + 100000*(9.504848x10^44 + 1)] / [9.504848x10^44 * 3] = -9.504848x10^49 / 2.851454x10^45 = -33333.3.</para>
   </sect3>

 </sect2>
 </sect1>


 <sect1 id="loans_missing1">
 <title>Missing Loan Documentation</title>

 <literallayout>
 -Automobile Loan (How-To)

 -Entering a Payment Schedule
     -Monthly Payments (How-To)
     -Final Payment (How-To)

 -Selling a House or Automobile (How-To)

 -Reconciling with the Loan Statements (How-To)

 -Putting It All Together
 </literallayout>

 </sect1>

 </chapter>
