lending.loan-payment Unreviewed

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

from fune.lending.loan_payment import loan_payment  # lending.loan-payment@^1

from .math_round_div import RoundingMode, round_div  ← 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

#: A hundred years of monthly payments, sixty of weekly ones.
MAX_PAYMENTS = 3000


def _is_int(value: object) -> bool:
    return isinstance(value, int) and not isinstance(value, bool)


def payment_count(annual_rate_basis_points: int, term_months: int, payments_per_year: int) -> int:
    """The number of payments a term holds, after checking the arguments every
    lending capability shares."""
    if not _is_int(annual_rate_basis_points) or annual_rate_basis_points < 0 or annual_rate_basis_points > 100000:
        raise ValueError(
            "annualRateBasisPoints must be between 0 and 100000, received %r" % (annual_rate_basis_points,)
        )
    if not _is_int(payments_per_year) or payments_per_year < 1 or payments_per_year > 52:
        raise ValueError("paymentsPerYear must be between 1 and 52, received %r" % (payments_per_year,))
    if not _is_int(term_months) or term_months < 1:
        raise ValueError("termMonths must be at least 1, received %r" % (term_months,))
    if (term_months * payments_per_year) % 12 != 0:
        raise ValueError(
            "a term of %d months is not a whole number of payments at %d a year" % (term_months, payments_per_year)
        )
    n = term_months * payments_per_year // 12
    if n > MAX_PAYMENTS:
        raise ValueError("%d payments is more than the %d payment limit" % (n, MAX_PAYMENTS))
    return n


def round_wide(numerator: int, denominator: int, mode: RoundingMode) -> int:
    """Round the exact quotient numerator / denominator (both positive) with a
    math.round-div mode, however large they are.

    Only the integer part and where the remainder sits against one half
    matter, so the decision is handed to round_div as a small fraction with the
    same integer part and the same side of the half: q, q + 1/4, q + 1/2 or
    q + 3/4.
    """
    q, remainder = divmod(numerator, denominator)
    twice = remainder * 2
    if twice == 0:
        return round_div(q, 1, mode)
    if twice == denominator:
        return round_div(2 * q + 1, 2, mode)
    return round_div(4 * q + (1 if twice < denominator else 3), 4, mode)


def loan_payment(
    principal: Money,
    annual_rate_basis_points: int,
    term_months: int,
    payments_per_year: int,
    mode: RoundingMode,
) -> Money:
    """The level payment that repays ``principal`` over the term at a nominal
    annual rate divided equally between the periods:

        payment = P * r / (1 - (1 + r)^-n),   r = rate / payments_per_year

    With r = b / D (b basis points, D = 10000 * payments_per_year) this is the
    exact fraction P * b * (D + b)^n / (D * ((D + b)^n - D^n)), evaluated in
    integers of whatever size it takes and rounded once. A zero rate is P / n.
    """
    if not _is_int(principal.minor) or principal.minor <= 0:
        raise ValueError("principal must be greater than zero, received %r" % (principal.minor,))
    n = payment_count(annual_rate_basis_points, term_months, payments_per_year)
    if annual_rate_basis_points == 0:
        return money(round_div(principal.minor, n, mode), principal.currency)
    b = annual_rate_basis_points
    d = 10000 * payments_per_year
    grown = (d + b) ** n
    numerator = principal.minor * b * grown
    denominator = d * (grown - d ** n)
    return money(round_wide(numerator, denominator, mode), principal.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.loan-payment

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

The whole function, every language, is one file too: lending.loan-payment-1.0.1.fune, 22,812 bytes, sha256 ae3adb6e388662e058f53225156c2198c46abb159e47c6967cb931c48a9670a1. It installs into a project of any language.

# fune: before lending.loan-payment

# fune: after lending.loan-payment

# fune: replace math.big-integer in lending.loan-payment
# fune: replace math.round-div in lending.loan-payment
# fune: replace money.amount in lending.loan-payment

# fune: step lending.loan-payment after <n|label>

More from the author

With a nominal annual rate split equally between the periods, r = rate / paymentsPerYear, and n payments:

payment = P × r / (1 − (1 + r)^−n)

That is the textbook present-value-of-an-annuity formula, the same one as a spreadsheet's PMT. Here it is never evaluated in floating point. The rate is b basis points, so r = b / D with D = 10000 × paymentsPerYear, and the formula is exactly the fraction

P × b × (D + b)^n / ( D × ((D + b)^n − D^n) )

Both sides are integers. For a 25-year monthly mortgage (D + b)^n is a number of over 1,500 digits, far past what `math.rational` holds (its parts must stay within 2^53 so JavaScript numbers stay exact), so the fraction is built with arbitrary-size integers: `bigint` in TypeScript, `int` in Python and `math.big-integer` in Rust. It is then rounded exactly once, with the `math.round-div` mode you pass. A zero rate is P / n, rounded the same way.

## Rounding

- `half-up` gives the nearest penny, what most quotes show: £100,000 at 5% over 25 years is £584.59. - `up` never under-repays: every payment is at most a penny high, and the final payment (see lending.amortisation-schedule) comes out slightly smaller. - `down` or `half-even` are available where a contract says so.

The mode applies to the exact value, so there is no double rounding: a payment of exactly x.5 pence rounds by the mode's tie rule, anything else to the nearer penny.

## What it does not do

- The rate is nominal and divided equally (12% a year is 1% a month). It is not an APR or AER; lending.apr and banking.savings-aer convert. - Every period is treated as equal. Interest charged daily, or a first period of odd length, changes the payment slightly; build the schedule with lending.daily-interest when that matters. - No fees are added, and the payment is not a regulated APR disclosure.

## Limits

The rate is 0 to 100000 basis points, payments per year 1 to 52, and the term must hold a whole number of payments (13 months cannot be paid quarterly), at most 3000 of them. The principal must be positive and, for TypeScript to stay exact, below 2^51 minor units.

The module also exports `paymentCount` (the argument checks and n) and `roundWide` (round a large positive fraction with a round-div mode), which the other lending capabilities reuse.

## 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