金融计算 `hscredit.core.financial`

现值/终值/年金与收益率计算：FV / PV / PMT / NPER / IPMT / PPMT / RATE，以及 NPV / IRR / MIRR。

金融计算模块.

提供常用的金融计算函数，参考 numpy_financial 实现。

子模块:

basic: 基础金融计算（FV、PV、PMT、NPER、IPMT、PPMT、RATE）
advanced: 高级金融计算（NPV、IRR、MIRR）

参数

所有函数均支持标量和数组输入，自动进行向量化计算。

参考样例

>>> from hscredit.core.financial import fv, pv, npv, irr
>>> fv(0.05/12, 10*12, -100, -100)  # 未来值
15692.93
>>> pv(0.05/12, 10*12, -100)       # 现值
9428.14
>>> npv(0.05, [-1000, 300, 400, 400, 300])  # 净现值
240.87
>>> irr([-1000, 300, 400, 400, 300])         # 内部收益率
0.149

hscredit.core.financial.fv(rate, nper, pmt, pv, when='end')[源代码]

计算未来值 (Future Value).

在固定每期利率与等额分期付款条件下，计算一系列现金流在最后一期期末的累计价值。常用于储蓄/投资终值、定投账户余额测算等场景。

满足等式 fv + pv*(1+rate)**nper + pmt*(1+rate*when)/rate*((1+rate)**nper-1) = 0 （当 rate == 0 时退化为 fv = -(pv + pmt*nper)）。

参数:

rate -- 每期利率，小数表示（如年利率 5% 按月计息则传 0.05/12）
nper -- 总付款（计息）期数
pmt -- 每期固定付款额，按现金流方向约定（流出为负，如每月储蓄 -100）
pv -- 现值，即期初一次性金额（流出为负，如初始投入 -100）
when --
每期付款发生的时点，默认 'end'。可取以下枚举值：
- 'end' / 'e' / 'finish' / 0：期末付款（普通年金 ordinary annuity），每期现金流在期末发生——最常见
- 'begin' / 'b' / 'beginning' / 'start' / 1：期初付款（预付年金 annuity-due），每期现金流在期初发生，比期末多计一期利息
- 也可传入 numpy 数组对每个元素分别指定时点（向量化）

返回:

未来值（与输入现金流方向相反，通常为正表示终值收入）；标量入参返回标量，数组入参返回 numpy 数组

参考样例

标量计算（月利率 0.05/12，10 年共 120 期，每月储蓄 -100，初始 -100）:

>>> fv(0.05/12, 10*12, -100, -100)
15692.92889433575

期初付款（预付年金，终值更高）:

>>> fv(0.05/12, 10*12, -100, -100, when='begin')
15757.629844104778

向量化计算（同时评估多个利率；注意所有数值参数需为等长数组，含 when）:

>>> import numpy as np
>>> fv(np.array([0.05/12, 0.06/12]), np.array([120, 120]),
...    np.array([-100, -100]), np.array([-100, -100]), np.array([0, 0]))
array([15692.92889434, 16569.87435405])

引用

对应 Excel FV 函数与 numpy_financial.fv： https://numpy.org/numpy-financial/latest/functions/fv.html

hscredit.core.financial.pv(rate, nper, pmt, fv=0, when='end')[源代码]

计算现值 (Present Value).

在固定每期利率与等额分期付款条件下，将未来各期现金流与终值折算到期初的等价价值。常用于贷款可借本金测算、未来收益的当前估值等场景。

参数:

rate -- 每期利率，小数表示（如年利率 5% 按月计息则传 0.05/12）
nper -- 总付款（计息）期数
pmt -- 每期固定付款额，按现金流方向约定（流出为负）
fv -- 未来值，即最后一期期末的目标余额，默认为 0
when --
每期付款发生的时点，默认 'end'。可取以下枚举值：
- 'end' / 'e' / 'finish' / 0：期末付款（普通年金）
- 'begin' / 'b' / 'beginning' / 'start' / 1：期初付款（预付年金）
- 也可传入 numpy 数组对每个元素分别指定时点（向量化）

返回:

现值（与未来现金流方向相反，通常为负表示期初支出）

参考样例

每月收款 100、共 120 期、月利率 0.05/12 时，期初一次性等价价值:

>>> pv(0.05/12, 10*12, -100)
9428.135032823473

向量化计算（所有数值参数需为等长数组）:

>>> import numpy as np
>>> pv(np.array([0.05/12, 0.06/12]), np.array([120, 120]),
...    np.array([-100, -100]), np.array([0, 0]), np.array([0, 0]))
array([9428.13503282, 9007.34533272])

引用

对应 Excel PV 函数与 numpy_financial.pv： https://numpy.org/numpy-financial/latest/functions/pv.html

hscredit.core.financial.pmt(rate, nper, pv, fv=0, when='end')[源代码]

计算每期付款额 (Payment).

在给定现值、每期利率与期数条件下，计算等额本息分期的每期偿付额。是评分卡/信贷场景中测算月供的核心函数。

参数:

rate -- 每期利率，小数表示（如年利率 5% 按月计息则传 0.05/12）
nper -- 总付款（计息）期数
pv -- 现值，即贷款本金或投资额（借款人视角下本金为正流入）
fv -- 未来值，即最后一期期末的目标余额，默认为 0
when --
每期付款发生的时点，默认 'end'。可取以下枚举值：
- 'end' / 'e' / 'finish' / 0：期末付款（普通年金）
- 'begin' / 'b' / 'beginning' / 'start' / 1：期初付款（预付年金）
- 也可传入 numpy 数组对每个元素分别指定时点（向量化）

返回:

每期付款额（与本金方向相反，通常为负表示每期支出）

参考样例

本金 10000、月利率 0.05/12、分 120 期等额本息的月供:

>>> pmt(0.05/12, 10*12, 10000)
-106.06551523907554

引用

对应 Excel PMT 函数与 numpy_financial.pmt： https://numpy.org/numpy-financial/latest/functions/pmt.html

hscredit.core.financial.nper(rate, pmt, pv, fv=0, when='end')[源代码]

计算期数 (Number of Periods).

在给定每期利率、每期付款额与现值条件下，计算达到目标未来值所需的付款期数。返回值一般为非整数，表示理论上的精确期数。

参数:

rate -- 每期利率，小数表示（如年利率 5% 按月计息则传 0.05/12）
pmt -- 每期固定付款额，按现金流方向约定（流出为负）
pv -- 现值，即初始投资或贷款本金
fv -- 未来值，即目标余额，默认为 0
when --
每期付款发生的时点，默认 'end'。可取以下枚举值：
- 'end' / 'e' / 'finish' / 0：期末付款（普通年金）
- 'begin' / 'b' / 'beginning' / 'start' / 1：期初付款（预付年金）
- 也可传入 numpy 数组对每个元素分别指定时点（向量化）

返回:

达到目标未来值所需的期数（通常为非整数）

参考样例

本金 10000、每期还 -100、月利率 0.05/12 时所需期数:

>>> nper(0.05/12, -100, 10000)
129.62847166352213

引用

对应 Excel NPER 函数与 numpy_financial.nper： https://numpy.org/numpy-financial/latest/functions/nper.html

hscredit.core.financial.ipmt(rate, per, nper, pv, fv=0, when='end')[源代码]

计算给定期间的利息部分 (Interest Payment).

将等额本息分期中第 per 期的还款额拆分出"利息"部分。基于摊销公式：第 per 期利息 = 期初剩余本金 × rate。满足 ipmt + ppmt == pmt。

参数:

rate -- 每期利率，小数表示（如年利率 5% 按月计息则传 0.05/12）
per -- 指定期次，取值范围 1 ~ nper``（第 1 期至第 ``nper 期）
nper -- 总付款（计息）期数
pv -- 现值，即贷款本金或投资额
fv -- 未来值，即最后一期期末的目标余额，默认为 0
when --
每期付款发生的时点，默认 'end'。可取以下枚举值：
- 'end' / 'e' / 'finish' / 0：期末付款（普通年金）
- 'begin' / 'b' / 'beginning' / 'start' / 1：期初付款（预付年金；此时首期无利息，返回 0，其余期相应折现一期）

返回:

第 per 期的利息支付额（与付款额同向，通常为负）

参考样例

本金 10000、月利率 0.05/12、共 120 期，第 1 期的利息（≈本金×月利率）:

>>> ipmt(0.05/12, 1, 12*10, 10000)
-41.666666666666664

引用

对应 Excel IPMT 函数与 numpy_financial.ipmt： https://numpy.org/numpy-financial/latest/functions/ipmt.html

hscredit.core.financial.ppmt(rate, per, nper, pv, fv=0, when='end')[源代码]

计算给定期间的本金部分 (Principal Payment).

将等额本息分期中第 per 期的还款额拆分出"本金"部分，等于该期总付款额减去利息（ppmt = pmt - ipmt）。随着期次推进，本金占比逐期增大、利息占比逐期减小。

参数:

rate -- 每期利率，小数表示（如年利率 5% 按月计息则传 0.05/12）
per -- 指定期次，取值范围 1 ~ nper``（第 1 期至第 ``nper 期）
nper -- 总付款（计息）期数
pv -- 现值，即贷款本金或投资额
fv -- 未来值，即最后一期期末的目标余额，默认为 0
when --
每期付款发生的时点，默认 'end'。可取以下枚举值：
- 'end' / 'e' / 'finish' / 0：期末付款（普通年金）
- 'begin' / 'b' / 'beginning' / 'start' / 1：期初付款（预付年金）

返回:

第 per 期的本金支付额（与付款额同向，通常为负）

参考样例

本金 10000、月利率 0.05/12、共 120 期，第 1 期偿还的本金:

>>> ppmt(0.05/12, 1, 12*10, 10000)
-64.39884857240887

引用

对应 Excel PPMT 函数与 numpy_financial.ppmt： https://numpy.org/numpy-financial/latest/functions/ppmt.html

hscredit.core.financial.rate(nper, pmt, pv, fv=0, when='end', guess=0.1, tol=1e-06, max_iter=100)[源代码]

计算每期利率 (Rate).

在给定期数、每期付款额、现值与未来值条件下，使用牛顿迭代法（Newton-Raphson）反解使现金流等式成立（净现值为零）的每期利率。如需年化，自行乘以每年期数。

参数:

nper -- 总付款（计息）期数
pmt -- 每期固定付款额，按现金流方向约定（流出为负）
pv -- 现值，即初始投资或贷款本金
fv -- 未来值，即最后一期期末的目标余额，默认为 0
when --
每期付款发生的时点，默认 'end'。可取以下枚举值：
- 'end' / 'e' / 'finish' / 0：期末付款（普通年金）
- 'begin' / 'b' / 'beginning' / 'start' / 1：期初付款（预付年金）
guess -- 牛顿迭代的初始猜测利率，默认为 ``0.1``（即 10%）。当方程存在多解或迭代不收敛时，可调整该初值
tol -- 收敛容差，残差或步长小于该值即视为收敛，默认为 1e-6
max_iter -- 最大迭代次数，默认为 100

返回:

每期利率（小数表示）

抛出:

ValueError -- 导数过小或在 max_iter 次迭代内无法收敛时抛出

参考样例

本金 10000、每期还 -100、共 120 期时反解出的月利率:

>>> rate(10*12, -100, 10000)
0.0031141819460226306

引用

对应 Excel RATE 函数与 numpy_financial.rate；牛顿迭代法参见 https://numpy.org/numpy-financial/latest/functions/rate.html

hscredit.core.financial.npv(rate, values)[源代码]

计算净现值 (Net Present Value).

将一段现金流序列按固定折现率折算到第 0 期并求和，用于判断项目是否创造价值（NPV > 0 表示在该折现率下项目可接受）。

备注

采用 numpy_financial 约定：values[0] 位于第 0 期、不折现，与 Excel NPV``（从第 1 期开始折现所有值）相差一个 ``(1+rate) 因子。

参数:

rate -- 每期折现率，小数表示（如 0.05 表示每期 5%）
values -- 现金流序列（类数组），values[0] 通常为初始投资（负值），其后为各期回报

返回:

净现值，正值表示在该折现率下项目盈利

参考样例

初始投入 1000，其后四期回报 300/400/400/300，折现率 5%:

>>> npv(0.05, [-1000, 300, 400, 400, 300])
240.87185894766066

引用

对应 numpy_financial.npv： https://numpy.org/numpy-financial/latest/functions/npv.html

hscredit.core.financial.irr(values)[源代码]

计算内部收益率 (Internal Rate of Return).

求解使净现值（NPV）恰好为零的每期折现率，即项目隐含的真实回报率。内部使用二分法（bisection）在 [-0.99, +∞) 区间搜索，要求现金流同时包含正值与负值（至少一次变号）以保证解存在。

备注

IRR 仅在现金流方向单次变号时唯一；多次变号可能存在多个解，本实现返回二分法在默认区间内找到的第一个根。

参数:: values -- 现金流序列（类数组），通常 values[0] 为初始投资（负值），且序列中至少各有一个正值与一个负值
返回:: 内部收益率（每期，小数表示）
抛出:: ValueError -- 现金流未同时包含正负值、无法确定搜索上界或迭代不收敛时抛出

参考样例

初始投入 1000，其后四期回报 300/400/400/300 的内部收益率:

>>> irr([-1000, 300, 400, 400, 300])
0.14895028127237311

引用

对应 numpy_financial.irr： https://numpy.org/numpy-financial/latest/functions/irr.html

hscredit.core.financial.mirr(values, finance_rate, reinvest_rate)[源代码]

计算修正内部收益率 (Modified Internal Rate of Return).

MIRR 修正了 IRR 隐含"按 IRR 自身再投资"的不现实假设：正现金流按再投资收益率复利至末期，负现金流按融资成本折现至初期，再由两者之比反解年化收益。相比 IRR 更贴近真实资金成本，且对单变号以外的现金流也唯一。

公式：MIRR = (FV(正现金流) / -PV(负现金流)) ** (1/(n-1)) - 1，其中 n 为现金流期数。

参数:

values -- 现金流序列（类数组），需同时包含正值与负值
finance_rate -- 融资成本率（每期），用于将负现金流折现到第 0 期
reinvest_rate -- 再投资收益率（每期），用于将正现金流复利到末期

返回:

修正内部收益率（每期，小数表示）

抛出:

ValueError -- 现金流中不含负值或不含正值时抛出

参考样例

现金流 -1000/300/400/400/300，融资成本 5%、再投资收益 8%:

>>> mirr([-1000, 300, 400, 400, 300], 0.05, 0.08)
0.1205253227096672

引用

对应 Excel MIRR 与 numpy_financial.mirr： https://numpy.org/numpy-financial/latest/functions/mirr.html

金融计算 hscredit.core.financial

金融计算 `hscredit.core.financial`