Financial Math Submodule

Provides a set of common routines in financial maths.

Quickstart

using ActuaryUtilities

cfs = [5, 5, 105]
times    = [1, 2, 3]

discount_rate = 0.03

present_value(discount_rate, cfs, times)           # 105.65
duration(Macaulay(), discount_rate, cfs, times)    #   2.86
duration(discount_rate, cfs, times)                #   2.78
convexity(discount_rate, cfs, times)               #  10.62

Floating-rate, multi-curve & portfolios

Macaulay/Modified duration are for fixed cashflows. For a floating-rate bond, a portfolio, or any curve-dependent contract, pass the contract directly — duration(Effective(), contract, curve, tenors) / duration(Spread(), …) / dv01(…) re-project the coupons and give the rate-vs-spread durations (years and DV01s); sensitivities(contract, curve, tenors) returns the full bundle, and sensitivities(contract, tenors; discount = (; rf, credit, ilp), index = …) does the multi-curve decomposition. See Key Rate Sensitivities.

Zero cashflow streams

An empty collection and an all-zero projection grid both represent no cashflows. Explicit-cashflow duration, convexity, and key-rate sensitivities return zero risk for either representation. Value and dollar risk are zero; normalized duration and convexity are assigned zero by convention. This includes scalar Macaulay/Modified duration, DV01/IR01/CS01, legacy key rates, and Hull–White cashflow sensitivities. present_values returns an empty vector or a vector of zeros.

Every cashflow needs a corresponding time, but the time grid may be longer. Unused trailing times are ignored, including when deriving a legacy key-rate grid or a Hull–White simulation horizon. Too few times throws DimensionMismatch. Empty cashflows are valid with either an empty or populated time grid.

Cashflow amounts	Value and dollar risk	Normalized risk
Empty or all exactly zero	Zero	Zero by convention
Nonzero amounts with zero net present value	Dollar risk can be nonzero	Undefined (`NaN`/`Inf`)
Nonzero present value	Calculated as usual	Calculated as usual

The check uses exact iszero on amounts, including AD partials, rather than a tolerance or net present value. Both 0.0 and -0.0 are zero; a tiny nonzero amount is not. Normalized duration is invariant to nonzero scaling of amounts, so the assigned value at exactly zero is not the limit as amounts shrink. Explicit key-rate grid validation still applies; zero streams need no derived default grid. Zero streams need no discount factors, so the curve is never evaluated and Hull–White does not simulate. Their numeric types come from amounts and times, plus the tenor grid for key-rate results. They may therefore differ from a nonzero stream's curve-derived type (for example, Float64 versus BigFloat or Dual). Abstractly typed empty inputs fall back to Float64. When preallocating batch or AD buffers, choose a compatible numeric type from the calculation's inputs inside the differentiated function. Do not infer it from the first contract's result, which may come from a zero stream.

Skipping Hull–White simulation leaves the RNG unchanged, so a shared-RNG batch uses different subsequent draws than versions that simulated zero streams. Independently assigned RNG streams avoid dependence on preceding contracts.

To aggregate portfolio risk, sum values and dollar derivatives before normalizing once. This also preserves exposures from positions whose net value is zero. An unweighted average of contract durations includes zero-stream entries as zeros and is not a portfolio duration. Valuation-function and contract APIs retain their existing normalization behavior: a zero valuation alone does not identify a zero stream.

Curve Transformations

FinanceModels.Yield.TenorShift lets you lazily transform any yield curve's zero rates via curve + (z, t) -> new_rate. This is useful for scenario analysis (parallel shifts, twists, stresses) without refitting.

Parallel shift

using ActuaryUtilities, FinanceModels, FinanceCore

base = Yield.Constant(Continuous(0.05))
shifted = base + (z, t) -> z + Continuous(0.01)   # +100 bp parallel

zero(shifted, 1.0)

Continuous(0.060000000000000005)

Periodic rate arithmetic

Rate arithmetic automatically handles compounding conversion — a Periodic(0.01, 1) bump converts to continuous internally:

shifted_p = base + (z, t) -> z + Periodic(0.01, 1)
zero(shifted_p, 5.0)   # ≈ Continuous(0.05 + log(1.01))

Continuous(0.05995033085316809)

Tenor-dependent twist

A steepener that fades at 30y:

twist = base + (z, t) -> z + Continuous(0.02 * max(0.0, 1.0 - t / 30.0))
(zero(twist, 1.0), zero(twist, 15.0), zero(twist, 30.0))

(Continuous(0.06933333333333333), Continuous(0.060000000000000005), Continuous(0.05))

PV comparison under stress

cfs = [5.0, 5.0, 5.0, 105.0]
times = [1.0, 2.0, 3.0, 4.0]

pv_base = present_value(base, cfs, times)
pv_shifted = present_value(shifted, cfs, times)
pct_change = (pv_shifted - pv_base) / pv_base * 100
(; pv_base = round(pv_base, digits=4), pv_shifted = round(pv_shifted, digits=4), pct_change = round(pct_change, digits=2))

(pv_base = 99.5506, pv_shifted = 95.9157, pct_change = -3.65)

Bootstrapped curve + stress

quotes = ZCBYield.([0.04, 0.05, 0.055, 0.06], [1.0, 3.0, 5.0, 10.0])
fitted = fit(Spline.Linear(), quotes, Fit.Bootstrap())
stressed = fitted + (z, t) -> z + Continuous(0.005)   # +50 bp

dur_base = duration(fitted, cfs, times)
dur_stressed = duration(stressed, cfs, times)
(; dur_base = round(dur_base, digits=4), dur_stressed = round(dur_stressed, digits=4))

(dur_base = 3.719, dur_stressed = 3.716)

Negative rates

Real-world EUR/JPY/CHF scenarios with negative base rates:

neg = Yield.Constant(Continuous(-0.01))
shifted_neg = neg + (z, t) -> z + Continuous(0.005)
(; rate = zero(shifted_neg, 5.0), df = round(discount(shifted_neg, 5.0), digits=6))

(rate = Continuous(-0.005), df = 1.025315)

API

Exported API

ActuaryUtilities.FinancialMath.CS01 — Type

CS01 <: Duration

Credit Spread 01. The dollar change in value for a 1 basis point parallel shift in the credit spread, holding the risk-free (base) curve constant.

Requires both a base curve and credit spread to be specified. For a flat additive decomposition, CS01 ≈ IR01 ≈ DV01.