[franrizz15]

PR summary

• What problem does this PR solve? Link any relevant issues and PRs.

This PR is related to #38.
Adds cumprinc and cumipmt to calculate the cumulative principal and interest paid between two periods, matching the Excel/SAS functions of the same names. Both functions include the start and end periods.

cumprinc is computed as the difference between two loan balances rather than by summing ppmt period by period. Each principal payment is the amount the balance falls that period, so the sum telescopes and only the endpoints survive:

cumprinc = _rbl(rate, start, total_pmt, pv, when)
         - _rbl(rate, end + 1, total_pmt, pv, when)

_rbl reports the balance entering a period, hence the end + 1. when='begin' the payment lands before the period's interest accrues, so both balances are discounted one period except at start == 1, where nothing has accrued yet.

cumipmt then follows from pmt = ipmt + ppmt summed over the range:

cumipmt = total_pmt * (end - start + 1) - cumprinc(...)

• Why are you interested in working on this PR?

I was looking for enhancement issues that would allow me to get a good understanding of the library's structure and available functionality. This one got my attention since it is closely related to the existing ipmt and ppmt.

• How does the proposed change help you?

I am part of the 2026 Sustain cohort, would like to keep contributing to open source, especially numpy-financial.

First time contributor introduction

Hi! I am new to the community - I will be contributing to numpy and numpy-financial through the open source initiative run by my company.

AI Disclosure

I used claude to navigate the current codebase to identify what pieces of code I could reuse and to make sure the style matched the existing code.

[franrizz15]

@InessaPawson fyi added the PR, could not change the label to sustain-2026

[InessaPawson]

Thanks for picking this up, @franrizz15 !
Two small requests before this is ready for merge:

• Add cumprinc and cumipmt to the autosummary list in doc/source/api.rst so they show up in the rendered documentation.
• Add an entry to CHANGELOG.md under the unreleased section.

[franrizz15]

@InessaPawson thank you for the quick reply! Added them

[seberg]

@lcrmorin since you were interested in helping more with the project. If you have time, do you have thoughts on this (and maybe other recent PRs)? Especially, since it expands API.

[lcrmorin]

@seberg basically this is implementing some widely used Excel functions. It is a good idea and the direction I had in mind. However I am not entirely sure how to proceed. Do we want to keep exactly same name and functioning ? Notably 1) Isn't there a legal issue ? and 2) should we ensure exact match trough testing ?

[franrizz15]

@seberg basically this is implementing some widely used Excel functions. It is a good idea and the direction I had in mind. However I am not entirely sure how to proceed. Do we want to keep exactly same name and functioning ? Notably 1) Isn't there a legal issue ? and 2) should we ensure exact match trough testing ?

Hi @lcrmorin , wanted to understand more about the concern. 1) what would be the legal issue of adding functions with the same name as excel, the functions offered in npf already share acronyms with excel functions. I am not saying there is not an issue with it, but I wonder, if there was, wouldn’t we need to change all the names?
2) In the issue linked to the PR I was asked to add some unit tests where I confirm that the return in excel and sas is the same as npf, the unit test for these are in the test module starting with test_sas_ / test_excel_

thanks

[seberg]

My understanding is that the legal risk should be very small (there was a big court case once around API not being copyrightable); it seems also a good chance there are many others who use this name by now. That said, there are some concerns around copyright (at least if docs are too close).

But there is a another point here maybe: Can't we find a nicer name anyway, even cumprinciple() might be just fine and read easier? (I am not sure, maybe "cumprinc" is super well recognized, but generally, I feel times changed toward embracing longer names.)

[franrizz15]

Interesting, didn’t know about the API copyright concerns. Appreciate the background.
The functions are well known to excel users, however I think it might be a good chance to start differentiating npf from Excel and assign more readable names.
If cumprinciple and cuminterest are a good compromise between the excel acronym and the full cumulative_principle_payment and cumulative_interest_payment I can make the change.