Calculation methodology and boundaries

Price and payment timing

Let F be face value, c the annual coupon as a decimal, m the number of coupon periods per year, T whole years and y the nominal annual yield as a decimal. There are n = mT payments. Each coupon is Fc/m, and the last payment also includes F. Price is the sum of CF(k)/(1+y/m)^k over k from one to n.

The pinned financial 0.2.4 library supplies present-value and net-present-value functions. Its NPV convention includes a period-zero cash flow, so the implementation prepends zero to the future-payment list. Cash flows are independently discounted for the exported schedule. No intermediate cent rounding changes the internal calculation.

Duration, convexity and DV01

Macaulay duration is the sum of (k/m) times each discounted cash flow, divided by price. Modified duration divides Macaulay duration by (1+y/m). Convexity is the sum of k(k+1)/m^2 times each present value divided by (1+y/m)^2, then divided by price.

DV01 is price times modified duration times 0.0001. It is displayed as a positive first-order magnitude. With a decimal annual yield change d, duration estimates -D*d and the quadratic approximation adds 0.5*C*d^2. Exact repricing uses the full changed discount factors. Approximation error is approximation minus exact in percentage points.

Ladder aggregation

Each rung uses its own coupon, maturity, nominal yield and shock but the selected common payment frequency. Prices, DV01 and dollar changes are added. Aggregate modified duration is the present-value-weighted modified duration, consistent with a small common yield shift.

Annual payment rows sum scheduled coupons and principal. They do not reinvest receipts, roll maturities or calculate accumulated wealth. A maturity-specific shock is applied separately to each rung; no curve interpolation, key-rate construction or credit calibration is inferred.

Input limits and exclusions

Face value is between 0.01 and one billion USD; annual coupons run from 0% to 30%; whole-year maturity is one through thirty; nominal yields are -5% through 50%; shocks are -1,000 through 1,000 bp. Shifted yields must also remain inside the yield range. Frequency is annual, semiannual or quarterly. These are supported software bounds, not recommended investment ranges.

Real settlement dates, stub periods, day counts and accrued interest are not modeled. Neither are calls, puts, floating rates, amortization, inflation indexation, default, liquidity costs, tax, foreign exchange or reinvestment. A matching instrument label does not remove these exclusions.

Verification and reproducibility

The initial engine release is checked against 324 fixtures using independently implemented, 50-digit Decimal cash-flow calculations. Five metrics are compared per fixture: price, Macaulay duration, modified duration, convexity and DV01. Boundary, zero-yield, par-bond, scaling and finite-difference tests complement that grid.

The downloadable reference JSON preserves full-precision inputs and outputs. Passing these software checks supports the stated calculation convention; it does not certify a security, validate a trading strategy or establish the suitability of an investment. The distinction is especially important when extending a simple bond formula to instruments with changing cash flows.

Primary references

1. Financial library: net present value convention
2. FINRA: Bond structure, pricing and risks