lending.amortisation-schedule Unreviewed

def amortisation_schedule(principal: Money, annual_rate_basis_points: int, term_months: int, payments_per_year: int, mode: RoundingMode) -> AmortisationSchedule

@dataclass(frozen=True)
class AmortisationRow:
    """One period of the schedule."""

    #: 1 for the first payment
    period: int
    #: the level payment, or the adjusted final one
    payment: Money
    #: interest for the period on the opening balance
    interest: Money
    #: the part of the payment that repays the loan
    principal: Money
    #: the balance after this payment
    balance: Money

@dataclass(frozen=True)
class AmortisationSchedule:
    """The level payment, every period, and the totals."""

    payment: Money
    rows: List[AmortisationRow]
    total_interest: Money
    total_paid: Money

from fune.lending.amortisation_schedule import amortisation_schedule  # lending.amortisation-schedule@^1

from typing import List

from .lending_amortisation_schedule_types import AmortisationRow, AmortisationSchedule
from .lending_loan_payment import loan_payment, payment_count, round_wide  ← from lending.loan-payment ^1.0.0 · built alongside by fune
from .math_round_div import RoundingMode  ← from math.round-div ^1.0.0 · built alongside by fune
from .money_amount import Money, money  ← from money.amount ^1.0.0 · built alongside by fune


def period_interest(balance: int, annual_rate_basis_points: int, payments_per_year: int) -> int:
    """Interest for one period on a positive balance: balance * b / D, rounded
    half-up to the minor unit, which is what gets posted to the account."""
    if balance <= 0 or annual_rate_basis_points == 0:
        return 0
    product = balance * annual_rate_basis_points
    # Rust holds the product in an i64; refuse it everywhere rather than in one language.
    if product > 9223372036854775807:
        raise ValueError("balance too large for exact interest")
    return round_wide(product, 10000 * payments_per_year, "half-up")


def amortisation_schedule(
    principal: Money,
    annual_rate_basis_points: int,
    term_months: int,
    payments_per_year: int,
    mode: RoundingMode,
) -> AmortisationSchedule:
    """The schedule a lender's system produces: each period's interest is
    computed on the opening balance and rounded to a whole minor unit, the
    level payment repays interest first and principal with the rest, and the
    last payment is whatever clears the balance, so it ends at exactly zero.
    """
    payment = loan_payment(principal, annual_rate_basis_points, term_months, payments_per_year, mode)
    n = payment_count(annual_rate_basis_points, term_months, payments_per_year)
    currency = principal.currency
    rows: List[AmortisationRow] = []
    balance = principal.minor
    total_interest = 0
    total_paid = 0
    period = 1
    while period <= n and balance > 0:
        interest = period_interest(balance, annual_rate_basis_points, payments_per_year)
        # The last period, or one where the level payment would overshoot (a
        # rounded-up payment can clear the loan a period early), pays exactly
        # what is owed.
        if period == n or balance + interest <= payment.minor:
            due = balance + interest
        else:
            due = payment.minor
        repaid = due - interest
        balance -= repaid
        total_interest += interest
        total_paid += due
        rows.append(
            AmortisationRow(
                period=period,
                payment=money(due, currency),
                interest=money(interest, currency),
                principal=money(repaid, currency),
                balance=money(balance, currency),
            )
        )
        period += 1
    return AmortisationSchedule(
        payment=payment,
        rows=rows,
        total_interest=money(total_interest, currency),
        total_paid=money(total_paid, currency),
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 3 dependencies, pins them in fune.lock, downloads only the Python package of each, and builds the code above into your project’s .fune/build, one readable file per capability with a header linking back here. Or pin a range in fune.project and build in one step:

fune add lending.amortisation-schedule

The manifest, vectors and README with only the Python implementation. Install it without the registry with fune add ./lending.amortisation-schedule-1.0.1-python.fune, or fetch it from a terminal with fune pull lending.amortisation-schedule@1.0.1:python.

The whole function, every language, is one file too: lending.amortisation-schedule-1.0.1.fune, 66,045 bytes, sha256 d20048fdaec868479307700ac9f444968a01d572c7be5809edaf48096ef9f96c. It installs into a project of any language.

# fune: before lending.amortisation-schedule

# fune: after lending.amortisation-schedule

# fune: replace lending.loan-payment in lending.amortisation-schedule
# fune: replace math.round-div in lending.amortisation-schedule
# fune: replace money.amount in lending.amortisation-schedule

# fune: step lending.amortisation-schedule after <n|label>

More from the author

1. The level payment comes from lending.loan-payment, rounded with the mode you pass. 2. Each period's interest is the opening balance × rate / paymentsPerYear, rounded half-up to a whole minor unit: that is the amount actually posted. 3. The payment pays that interest first; the rest reduces the balance. 4. The final payment is not the level payment. It is whatever is owed: the remaining balance plus that period's interest. So the balance ends at exactly zero, never at -3p or +2p.

The final payment is where every penny of rounding collects. With the payment rounded half-up it is within a few pence of the others; rounded `up` it is a little smaller, rounded `down` a little larger. If a rounded-up payment would clear the loan before the term ends (possible only for tiny loans, such as 25p over 12 months), the schedule stops at the payment that clears it, so it can have fewer rows than the term has payments. It never has a row with a payment of zero.

The totals are the sums of the posted rows: totalPaid = principal + totalInterest, exactly.

## What it does not do

The periods are equal and the rate is nominal and fixed, as in lending.loan-payment. It does not model daily interest, payment holidays, rate changes, fees or overpayments (lending.overpayment-effect covers a one-off overpayment).

## Limits

The same arguments as lending.loan-payment, so at most 3000 rows. A balance whose interest product (balance × basis points) would exceed 2^63 - 1 is an error ("balance too large for exact interest") in every language.

The module also exports `periodInterest(balance, annualRateBasisPoints, paymentsPerYear)`, the rounding rule of step 2.

## Before you rely on this

**Not professional advice.** This capability calculates lending figures from published rules. It is a software component for developers, not financial advice. Rules change and every rate here has an effective date. Check that the dates cover your case. Verify results against the official sources listed above, and have a consumer-credit compliance specialist review how you use it, before anyone relies on the output. Provided "as is" under its licence, without warranty.

**Unreviewed.** This capability's implementations agree in every language and pass its published test vectors, which were worked out from the official sources cited. But no qualified consumer-credit compliance specialist has yet checked those vectors, or confirmed that the capability covers the cases it claims. Treat it as a draft. Do not use it for real people, money or decisions without your own expert review. Once a qualified reviewer signs off, this notice is replaced with their name, qualification and the date. Each new version needs fresh sign-off.

1.0.1 marks it unreviewed. The code and the tests are unchanged.

Files