FinanceModels.ShortRate API Reference

Stochastic short-rate models (Vasicek, Cox-Ingersoll-Ross, Hull-White) that implement the AbstractYieldModel interface via closed-form zero-coupon bond prices. They also support Monte Carlo simulation via simulate and pv_mc.

simulate(model::AbstractStochasticModel;
         n_scenarios=1000, timestep=1/12, horizon=30.0,
         rng=Random.default_rng())

Generate n_scenarios interest-rate paths. Each path is returned as a RatePath (an AbstractYieldModel) so it plugs directly into present_value, discount, etc. A path is defined on its time grid of simulation_steps(horizon, timestep).nsteps steps, from 0 to horizon (or the first grid point beyond an unaligned horizon); evaluating it outside that range throws rather than extending the path.

Discretisation schemes:

• Vasicek / Hull-White: the exact Gaussian transition density, so the simulated short rate has no discretisation bias at any timestep.
• Cox-Ingersoll-Ross: full truncation (Lord, Koekkoek & Van Dijk, 2010) — an auxiliary process may go negative while the observed rate is max(x, 0). Weak bias vanishes as timestep → 0, but is material for coarse steps when the Feller condition is strongly violated.

In all cases the cumulative discount integral $∫₀ᵗ r(s)\,ds$ is accumulated with the trapezoidal rule between grid points, so pathwise discount factors (and hence pv_mc) retain an integration error that grows with timestep even when the short-rate transition itself is exact.

Each path also records the simulated short rate at its grid times (FinanceModels.simulation_times), read with short_rate.

Paths are repeatable: the same rng state, arguments and package versions give the same paths. A model whose parameters carry ForwardDiff numbers draws the same shocks as its Float64 counterpart, so paired sensitivity runs see identical scenarios. A change to which draws feed which step is recorded in the NEWS.

pv_mc(model, contract;
      n_scenarios=1000, timestep=1/12, horizon=nothing,
      rng=Random.default_rng())

Estimate the expected present value of contract under the stochastic model by averaging present_value across simulated scenarios.

The horizon must cover the contract's maturity, since a simulated path throws beyond its horizon. The default (maturity + 1) ensures this.

short_rate(path::RatePath, t)

The simulated short rate at grid time t of a path from simulate, as a Continuous rate: the model's state there (for Cox-Ingersoll-Ross, the observed rate max(x, 0)). It is the rate to pass as r_t to a conditional discount(model, t, T, r_t).

t must be one of the path's simulated times, FinanceModels.simulation_times(path). A time within roundoff of one, 8eps at the scale of that time or of the step, whichever is larger, is read as that time. Any other t, between grid times or outside the grid, throws a DomainError: the simulation has no rate there. A path built from an integral alone, RatePath(interp), records no rates, and short_rate throws an ArgumentError.

Yield.instantaneous_forward(path, t) is different: it is the slope of the discount integral over the step that starts at t, the average of that step's two simulated rates, so it depends on the rate at the end of the step.

CoxIngersollRoss(a, b, σ, initial)

Cox-Ingersoll-Ross (1985) mean-reverting short-rate model:

dr = a(b - r) dt + σ √r dW

Arguments

• a: speed of mean reversion
• b: long-term mean rate. A Rate is converted to its continuously compounded equivalent.
• σ: volatility
• initial: initial short rate r₀ (a Rate object or Real)

HullWhite(a, σ, curve)

Hull-White (1990) one-factor model:

dr = (θ(t) - a r) dt + σ dW

where θ(t) is calibrated to fit the initial term structure curve.

Arguments

• a: speed of mean reversion
• σ: volatility
• curve: an existing yield model providing the initial term structure

Vasicek(a, b, σ, initial)

Vasicek (1977) mean-reverting short-rate model:

dr = a(b - r) dt + σ dW

Arguments

• a: speed of mean reversion
• b: long-term mean rate. A Rate is converted to its continuously compounded equivalent.
• σ: volatility
• initial: initial short rate r₀ (a Rate object or Real)