pass start_date (present "moment") and end_date (future "moment") to XFV about pyxirr

[yonil7]

XLeratorDB (the link you sent) has 2 relevant functions:

• XFV: calculate the future value of a single cash flow
• XNFV: calculate the future value of a series of cash flows (N is for "net". as the example on XFV shows, this function is similar to SUMFV that summarize multiple XFV together)

As all this library functions works on multiple cash flows (and not a single cash flow), XLeratorDB XNFV is what we need. (but on pyxirr I would name it XFV - see comment on pyxirr naming convention below)

As for the naming conventions on pyxirr, I would use:

• FV, IRR, PV,... for periodic, constant payments
• XFV, XIRR, XPV, ... for a series of irregular cash flows (cash flows of varying amounts occurring on various dates)

[Anexen]

@yonil7, so, this is similar to the first link I suggested in #7.
Please, see http://westclintech.com/SQL-Server-Financial-Functions/SQL-Server-XFV-function

• If XFV and XNFV functions from the link above work for you, I can re-implement them in pyxirr.
• If this is not the case, please provide an example with the full function signature, input data, and expected results, so I can write the test. OR provide a link to a clear description of XFV function.

I also believe it's better to have two distinct functions for regular XFV and irregular XFV.

[Anexen]

@yonil7, XLeratorDB documentation says that XNPV is the net future value of a series of irregular cash flows. This makes sense because we are using net present value for the calculation.

So far I have come up with the following functions:

from pyxirr import fv, xnpv, npv

# http://westclintech.com/SQL-Server-Financial-Functions/SQL-Server-XFV-function
def xfv(start_date, cash_flow_date, end_date, cash_flow_rate, end_rate, cash_flow):
    return (
        fv(end_rate, (end_date - start_date).days / 365, 0, -1)
        / fv(cash_flow_rate, (cash_flow_date - start_date).days / 365, 0, -1)
        * cash_flow
    )

# http://westclintech.com/SQL-Server-Financial-Functions/SQL-Server-XNFV-function
def xnfv(rate, dates, amounts):
    periods = (max(dates) - min(dates)).days / 365
    pv = xnpv(rate, dates, amounts)
    return fv(rate, periods, 0, -pv)


# http://westclintech.com/SQL-Server-Financial-Functions/SQL-Server-NFV-function
def nfv(rate, nper, amounts):
    pv = npv(rate, amounts, start_from_zero=False)
    return fv(rate, nper, 0, -pv)

Examples:

Uneven periodic cash flows:

# net future value of an investment based on a series of periodic cash flows and a rate.
# example from https://www.youtube.com/watch?v=775ljhriB8U
print("NFV:", nfv(0.03, 6, [1050.0, 1350.0, 1350.0, 1450.0]))  # 5750.16

Irregular cash flows:

from datetime import date

cash_flows = [
    (date(2011, 11, 30), -100000),
    (date(2012, 3, 15), -50000),
    (date(2012, 7, 18), -2500),
    (date(2012, 11, 30), 12500),
    (date(2013, 1, 23), 37500),
    (date(2013, 4, 30), 75000),
    (date(2014, 2, 6), 90000),
]
dates, amounts = list(zip(*cash_flows))
start_date = min(dates)
end_date = max(dates)
rate = 0.0250  # annual 

print("XNFV:", xnfv(rate, dates, amounts))  # 57238. must be the same as below
print(
    "SUM(XFV):",
    sum(
        xfv(start_date, cash_flow_date, end_date, rate, rate, amount)
        for cash_flow_date, amount in cash_flows
    ),
)

I'm going to include these functions in pyxirr shortly.