lending.overpayment-effect Unreviewed

def overpayment_effect(balance: Money, annual_rate_basis_points: int, remaining_term_months: int, payments_per_year: int, payment: Money, overpayment: Money, mode: RoundingMode) -> OverpaymentEffect

@dataclass(frozen=True)
class OverpaymentEffect:
    """Both options side by side, with the no-overpayment baseline to compare against."""

    #: balance after the overpayment
    new_balance: Money
    #: payments to clear the old balance at the current payment
    baseline_payments: int
    #: interest paid doing that
    baseline_interest: Money
    #: payments to clear the new balance at the current payment
    reduced_term_payments: int
    #: the smaller last payment of that option
    reduced_term_final_payment: Money
    reduced_term_interest: Money
    #: baselinePayments minus reducedTermPayments
    payments_saved: int
    #: the new level payment over the remaining term
    reduced_payment: Money
    reduced_payment_interest: Money

from fune.lending.overpayment_effect import overpayment_effect  # lending.overpayment-effect@^1

from typing import Tuple

from .lending_amortisation_schedule import amortisation_schedule, period_interest  ← from lending.amortisation-schedule ^1.0.0 · built alongside by fune
from .lending_loan_payment import payment_count  ← from lending.loan-payment ^1.0.0 · built alongside by fune
from .lending_overpayment_effect_types import OverpaymentEffect
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 _pay_off(
    balance: int, annual_rate_basis_points: int, payments_per_year: int, payment: int, term: int
) -> Tuple[int, int, int]:
    """Run a balance down at a fixed payment, with the schedule's rounding,
    until it is clear or the term ends: (payments, final payment, interest).
    As in lending.amortisation-schedule, the last payment of the term is
    whatever clears the balance."""
    owed = balance
    payments = 0
    interest = 0
    final_payment = 0
    while owed > 0:
        accrued = period_interest(owed, annual_rate_basis_points, payments_per_year)
        if payment <= accrued:
            raise ValueError("the payment of %d does not cover the interest of %d" % (payment, accrued))
        due = owed + accrued if payments + 1 == term or owed + accrued <= payment else payment
        owed -= due - accrued
        interest += accrued
        payments += 1
        final_payment = due
    return payments, final_payment, interest


def overpayment_effect(
    balance: Money,
    annual_rate_basis_points: int,
    remaining_term_months: int,
    payments_per_year: int,
    payment: Money,
    overpayment: Money,
    mode: RoundingMode,
) -> OverpaymentEffect:
    """The two things a lender offers after a lump-sum overpayment, side by
    side: keep paying the same amount and finish sooner, or keep the same end
    date and pay less each period. Both are built period by period with the
    same rounding as lending.amortisation-schedule, and compared with carrying
    on as if nothing had been overpaid.
    """
    term = payment_count(annual_rate_basis_points, remaining_term_months, payments_per_year)
    currency = balance.currency
    for other in (payment, overpayment):
        if other.currency != currency:
            raise ValueError("currency mismatch: %s and %s" % (currency, other.currency))
    if payment.minor <= 0:
        raise ValueError("payment must be greater than zero, received %r" % (payment.minor,))
    if overpayment.minor <= 0:
        raise ValueError("overpayment must be greater than zero, received %r" % (overpayment.minor,))
    if overpayment.minor >= balance.minor:
        raise ValueError("overpayment must be less than the balance; paying it all off is an early settlement")
    new_balance = balance.minor - overpayment.minor
    base_n, _, base_interest = _pay_off(balance.minor, annual_rate_basis_points, payments_per_year, payment.minor, term)
    short_n, short_final, short_interest = _pay_off(
        new_balance, annual_rate_basis_points, payments_per_year, payment.minor, term
    )
    lower = amortisation_schedule(
        money(new_balance, currency), annual_rate_basis_points, remaining_term_months, payments_per_year, mode
    )
    return OverpaymentEffect(
        new_balance=money(new_balance, currency),
        baseline_payments=base_n,
        baseline_interest=money(base_interest, currency),
        reduced_term_payments=short_n,
        reduced_term_final_payment=money(short_final, currency),
        reduced_term_interest=money(short_interest, currency),
        payments_saved=base_n - short_n,
        reduced_payment=lower.payment,
        reduced_payment_interest=lower.total_interest,
    )

Install

fune build

With that line in your source, in a Python project (language python in fune.project), fune build resolves it and its 4 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.overpayment-effect

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

The whole function, every language, is one file too: lending.overpayment-effect-1.0.1.fune, 29,666 bytes, sha256 fc3aabd047cbf3d1b5254941c6ebef4ebd6a7293999346017809571b78e00bc8. It installs into a project of any language.

# fune: before lending.overpayment-effect

# fune: after lending.overpayment-effect

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

# fune: step lending.overpayment-effect after <n|label>

More from the author

Both are compared with a baseline: carrying on at the current payment as if nothing had been overpaid (`baselinePayments`, `baselineInterest`). Interest saved is baseline minus option. Reducing the term always saves at least as much interest as reducing the payment, because the balance falls faster; reducing the payment gives cash-flow room instead. Which to choose is the borrower's, which is why both are returned.

## Conventions

The overpayment is applied just after a regular payment, to the balance that payment left, and takes effect from the next period. Every period is built exactly as in lending.amortisation-schedule: interest on the opening balance rounded half-up to a whole minor unit, the payment covers interest first, and the last payment of the term (or the one that would overshoot) is exactly what is owed, so no option ever ends with a stray penny outstanding.

The baseline and the reduce-the-term option pay the `payment` you pass; it need not be the level payment (a borrower who already pays extra each month is modelled by passing what they pay). The reduce-the-payment option recalculates with lending.loan-payment and your rounding `mode`.

## What it does not do

- Early repayment charges. Many fixed-rate mortgages charge 1-5% of an overpayment above an annual allowance (often 10% of the balance); take that off before calling, or compare it with the interest saved. - Overpaying the whole balance. That is an early settlement: the lender's settlement figure (for regulated consumer credit, lending.early-settlement) is the right tool, so an overpayment of the whole balance is an error. - Rate changes, daily interest or payment holidays.

## Errors

A payment that does not cover the first period's interest never repays and is refused. Currencies must match. The rate, frequency and remaining term are checked as in lending.loan-payment.

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