固定利率附息债券的周期到期收益率：单调递减下的二分求根

实现 solution(price: float, face: float, coupon: float, n_periods: int) -> float。给定一只固定利率附息债券：当前 clean price 为 price，面值 face，每期票息现金额 coupon（已预乘——coupon = coupon_rate * face），剩余票息期数为 n_periods。返回让折现现金流恰好等于 price 的**周期到期收益率（YTM）y**。债券在 t = 1, 2, ..., n_periods 各期支付 coupon，并在第 n_periods 期额外返还 face（所以第 n 期现金流是 coupon + face，两者按同一个折现因子 (1+y)**n 折现）。定价函数 P(y) = sum_{t=1..n} coupon / (1+y)**t + face / (1+y)**n 在 y > -1 上严格递减。返回让 P(y) = price 的 y，绝对容差 1e-7。若输入不合规（price <= 0、face <= 0、coupon < 0、或 n_periods < 1）返回 float("nan")。

例

solution(1000.0, 1000.0, 50.0, 10) 返回约 0.05。face = 1000、每期票息现金 = 50（即票息率 5%）、剩余 10 期、clean price 等于面值——债券在平价交易，所以 YTM 等于票息率 y = 0.05。solution(62.0921323..., 100.0, 0.0, 5) 返回约 0.10：零息债券（coupon = 0），面值 100、5 期、价格 100 / 1.10**5 ~= 62.09，反推 y = 0.10。solution(92.9081..., 100.0, 3.0, 4) 返回约 0.05：4 期债券每期票息现金 3（票息率 3%）、价格约 92.9081（即 3/1.05 + 3/1.05**2 + 3/1.05**3 + 103/1.05**4，注意第 4 期票息和面值合并为 103，共用 1/1.05**4 折现），反推 YTM 为 5%——票息率低于 yield 时价格低于面值，标准的折价债。

关键形态是**在严格递减的价格曲线上对 y 二分**：P(y) 的每一项都是 c / (1+y)**t（c > 0、t >= 1），所以 dP/dy < 0 在 y > -1 上恒成立。y -> -1+ 时 P -> +inf、y -> +inf 时 P -> 0，因此对任意 price > 0，方程 P(y) = price 都恰好有一个根。自适应地选取初始区间（lo = -0.5 起，若 P(lo) <= price 则把 lo 半步推向 -1；hi = 1 起，若 P(hi) >= price 则把 hi 翻倍），再二分至 hi - lo < 1e-9。两个 off-by-one 陷阱：(a) 把 P(y) 当成递增（于是选错半区间）；(b) 把最后一期的票息和面值各自折现到 (1+y)**(n+1) 和 (1+y)**n 而不是共用 (1+y)**n。两者都要避免。

函数骨架见 stubs/stub.py。

实践背景

YTM 是固收交易台最基本的收益率指标：给定固定利率债券的市场价，反推让折现现金流等于该价格的唯一周期 yield。它是 duration、convexity、par-spread、价收曲线的输入端，是任何初级交易员闭着眼也要能反算出来的第一个量。定价函数没有闭式逆，工业界一律迭代求解——价收曲线单调（标准输入下严格递减）让二分成为教科书首选：基于符号的区间收缩绝对鲁棒。Newton 方法在实践中更快，但需要导数簿记 + 合适初值；二分用几次额外迭代换收敛保证，正是日终风险批量任务做净价校验时常用的解法。本题刻意以每期现金额 coupon（已经 coupon_rate * face）作为入参，而不是利率本身——这样定价器签名对零息（coupon = 0）、阶梯息（外部预聚合）以及任何让函数内部重新换算现金额会脆弱的变体都保持一致。