Duration Convexity And Dv01

Duration, convexity and DV01

"Duration" names at least four different numbers and "DV01" at least two. Substituting one for another gives a risk report that is a few percent wrong — too small to notice, too large to hedge with.

Every figure below is printed by scripts/duration.py (runs in 0.29 s; QuantLib optional). ✅ Measured means this file produced it on 2026-09-09 with QuantLib 1.43, numpy 2.2.6, Python 3.11.3.

The rule: Macaulay = (1 + y/m) × Modified, and only Modified belongs in a DV01. DV01 is on the DIRTY price. Past 100 bp you need convexity. A floater's rate duration is the time to its next reset, not its maturity.

1. Macaulay and Modified differ by exactly (1 + y/m)

✅ Measured — the ratio is the compounding factor to the last digit:

🚨 The error is one-directional and grows with the level of rates. A hedge sized off a Macaulay duration is always too big, by exactly y/m. On a zero-coupon bond Macaulay is the maturity — which is why the two are so easy to confuse, and why the confusion survives a sanity check on a zero.

Definitions, so the names stop moving:

2. 🚨 Duration is a first derivative — a 30y 4% bond at par

✅ Measured: P0 = 100.000000, ModDur = 17.380443, Convexity = 420.8130.

🚨 At −200 bp duration alone misses 10.19 points — 7.03% of the price. Convexity cuts that to 1.78 points.

🔑 The error is one-sided: duration alone always understates the price, up moves and down moves alike, because the price/yield curve is convex. So a P&L attribution built on duration alone has a persistent negative residual that looks like an unexplained loss and is arithmetic.

3. DV01 is on the DIRTY price

Modified duration is defined against the full price, so a DV01 built on the clean price is short by ModDur × accrued × 1e-4. ✅ Measured, 10y 5% semiannual at y = 4.50%, 1,000,000 notional:

🚨 The error breathes with the coupon cycle — zero on payment dates, largest just before one. On a portfolio it never nets out, because every bond's cycle is in the same direction.

✅ DV01 vs PV01: 817.2379 against 816.8504 on 1,000,000, a gap of 0.39. DV01 is the linear approximation; PV01 reprices. The gap is the convexity term inside one basis point — small on a 10-year, not small on a 30-year, and not zero anywhere.

4. ✅ Effective duration reproduces the closed form where the closed form applies

That agreement is the licence to use the bump everywhere else. Use effective duration whenever the cash flows themselves move with the rate — callables, floaters, MBS, anything with an embedded option — because the analytic formula assumes they do not.

5. 🚨 A floater has two durations and only one of them is five years

✅ Measured on a 5y quarterly FRN, index 5.00% flat, quoted margin = discount margin = 40 bp. The naive comparator, a 5y quarterly fixed bond at 5.40%, has modified duration 4.356304:

• ✅ Rate duration tracks the time to the next reset, not the maturity: 0.246670 against 0.250000 years just after a reset, 0.002500 the day before the next one. The coupon reprices with the curve, so there is almost nothing left to hedge.
• ✅ Spread duration runs to maturity — 4.356304 years — and on a reset date at par it equals the modified duration of the equivalent fixed bond to 1.9e-07 — the residual is the central-difference bump, not the model. That identity is the check that the spread bump is doing what you think.
• 🚨 Booking the FRN as a 5-year fixed bond invents about 41,000 per 1,000,000 per 100 bp of rate risk the instrument does not have — and hides the spread risk it does. The two errors do not offset; they are risks to different factors.

6. 🚨 QuantLib: three Duration enum values, two numbers, and one silent 28% error

✅ Measured, 10y 5% semiannual at y = 5.00%:

• ✅ Under Compounded my closed forms match QuantLib: |Macaulay diff| 4.4e-15, |Modified diff| 4.4e-15, |convexity diff| 4.3e-14.
• ✅ Duration.Simple == Duration.Macaulay (|diff| 8.9e-16). Three enum values, two numbers. The one you want is Modified.
• ✅ BondFunctions.duration raises compounded rate required — but only for Duration.Macaulay.
• 🚨 Duration.Modified on a Simple InterestRate returns 5.56346580 instead of 7.79458114 — 28.6% low, silently. So does basisPointValue (−0.05563 vs −0.07795) and convexity (68.60 vs 73.63). The guard exists and does not cover the case you will actually hit, since Modified is what a DV01 calls. Build the InterestRate with ql.Compounded explicitly.
• ⚠️ basisPointValue is a signed price CHANGE (−0.07794544 per 100 = −779.45 per 1,000,000); a DV01 is conventionally quoted positive. My DV01 is 779.46 — the 0.01 is the convexity term QuantLib includes.

7. What the script gives you

scripts/duration.py — numpy only at import; QuantLib inside one function.

Where this sits

• ../yield-measures-and-bill-quotes/SKILL.md — the yield every number here is a derivative with respect to, and 🚨 why a bill discount rate is not one.
• ../bond-conventions-and-accrued/SKILL.md — the accrued that makes §3's dirty price.
• ../ois-discounting-and-multi-curve/SKILL.md — 🚨 the swap analogue, where discounting at the wrong curve leaves the par rate unchanged and moves the annuity 1.461%, so every PV01 is wrong by that factor.
• ../sofr-and-rfr-compounding/SKILL.md — what a floating coupon actually is, before you take its derivative.
• ../../../fin-core/skills/portfolio-and-risk/SKILL.md — aggregating these into a portfolio risk number.
• ../../../fin-models/skills/term-structure-models/SKILL.md — key-rate and bucketed risk need a curve, and a curve is a different object from a yield.
• ../../../fin-libraries/skills/lib-quantlib/SKILL.md — BondFunctions needs evaluationDate set; a stale one gives NPV exactly 0.0.