Value a fixed-coupon bond at a given yield to maturity.

Returns clean and dirty price, accrued interest with the day counts behind it, and the consistency checks the valuation satisfies.

Use this when the yield is known and the price is wanted. For the reverse, use yield_from_price_tool.

Solve for the yield to maturity implied by a market price.

Solved by bisection, which cannot converge on a value that satisfies the iteration without solving the pricing equation. The returned checks verify the ordering of coupon, current yield and yield to maturity, which alone rules out a large class of wrong answers.

This is the usual starting point: market prices are observable, yields are derived.

Macaulay duration, modified duration, DV01 and convexity.

Supply either a price or a yield, not both.

modified_duration_years divides Macaulay duration by one plus the PERIODIC yield. naive_modified_duration_years shows what dividing by one plus the ANNUAL yield would give — the standard error on any bond paying more than once a year. effective_duration_years is computed numerically by central differences and uses no annualisation, so it arbitrates between them. Report the modified figure; the other two are there to prove it.

Remaining payments, with discount factors when a yield is supplied.

The first flow sits a fraction of a period away rather than a whole one. That exponent is what makes an ACT/ACT ICMA yield differ from a naive one, so it is reported explicitly as periods_from_settlement.

Compare an exact repricing against first- and second-order estimates.

residual_bp is the genuine third-and-higher-order term. For a short bond and a 100 bp move it is a fraction of a basis point. A residual of several basis points means the duration is wrong, not that the Taylor expansion was truncated — a distinction worth making explicitly, because attributing such a gap to higher-order terms is a common and confident mistake.

Supply either a price or a yield, not both.

Test a yield someone has already produced against the required bounds.

Use this to audit a figure rather than compute one — for example when checking work, or when a yield appears in a document and its plausibility matters.

A bond priced below par must yield more than its coupon and more than its current yield; above par, the ordering reverses. These bounds need no iteration and reject a whole class of wrong answers immediately. The correctly solved yield is returned too, so the size of any error is visible.