FinanceModels.ShortRate API Reference
FinanceModels.ShortRate.CoxIngersollRossFinanceModels.ShortRate.HullWhiteFinanceModels.ShortRate.Vasicek
Exported API
FinanceModels.ShortRate — Module
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.
Simulation and Monte Carlo
FinanceModels.simulate — Function
simulate(model::Equity.BlackScholesMerton;
n_scenarios=1000, timestep=1/12, horizon=30.0,
rng=Random.default_rng())Generate n_scenarios Black–Scholes–Merton price paths, as PricePaths that start at 1. A path is the ex-dividend price relative to its start, on the grid of FinanceModels.simulation_steps(horizon, timestep).nsteps steps that simulate uses for rate models.
Each step is the exact lognormal transition $S(t + Δt) = S(t)\exp\big((r - q - σ^2/2)Δt + σ\sqrt{Δt}\,Z\big)$, so the prices at the grid times have no discretisation bias at any timestep.
σis the model's number or itsVolatility.Constant's value.Volatility.Constant()is zero volatility, which gives the deterministic pathexp((r - q)t). Other volatility models are aMethodError.- The drift is the model's constant
r - q: risk-neutral whenris the risk-free rate, real-world whenris an expected return. It is never a simulated short rate. - A negative volatility throws an
ArgumentError.
Paths are repeatable as for rate models: the same rng state, arguments and package versions give the same paths, and a model whose parameters carry ForwardDiff numbers draws the same shocks as its Float64 counterpart.
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 astimestep → 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.
simulate(models::Tuple, ρ::AbstractMatrix;
n_scenarios=1000, timestep=1/12, horizon=30.0,
rng=Random.default_rng())
simulate(models::NamedTuple, ρ::AbstractMatrix; ...)Simulate several models together with correlated shocks. Each scenario is a tuple of paths, one per model in order (a NamedTuple with the same names for a NamedTuple of models): a RatePath for a short-rate model and a PricePath for an Equity.BlackScholesMerton model, all on the grid a single model's simulate uses. Each model steps with its own transition: exact for Vasicek, Hull–White and Black–Scholes–Merton, full truncation for Cox–Ingersoll–Ross.
ρ is the correlation between the standardized innovations the models receive at each step: a step draws d standard normals z and gives model i the i-th entry of F z, where F Fᵀ = ρ. It is not, in general, the Brownian-driver correlation of an exact continuous-time joint model. An exact transition weights a step's Brownian increments by when they occur: mean reversion discounts the earlier ones, at its own speed, and a model without mean reversion weights them equally. Two models that weight them the same way, such as two Vasicek models with the same speed, have innovations with their drivers' correlation. Models that weight them differently have innovations correlated less strongly than their drivers, by an amount that grows with the difference in weighting and with the timestep. The dependence of the models' values at a later time follows from the models and the timestep.
This is a scenario generator, not a hybrid pricing model: a Black–Scholes–Merton model keeps its constant-rate drift, so a RatePath's discount factor times a PricePath is not a martingale.
ρ must be d × d, finite, with a unit diagonal and symmetric (within 8eps), or a DimensionMismatch or ArgumentError is thrown. A positive-definite ρ is factored by Cholesky. A singular positive-semidefinite one, including correlations of ±1 and rank-deficient factor models, is factored by pivoted Cholesky and accepted when F Fᵀ reproduces it within 8 d eps; any other matrix throws. A ρ carrying ForwardDiff derivatives must have full numerical rank, checked by pivoted Cholesky on its values with tolerance 8 d eps, before any random draw. The factor's derivative is undefined at a singular matrix, although expected payoffs can have finite one-sided derivatives there. Near singularity, correlation-sensitivity estimates can have high variance as the smallest eigenvalue shrinks. Supported element types for pivoted Cholesky, including this rank check, follow Julia's implementation (Float32/Float64, plus generic types such as BigFloat on Julia 1.12 and later).
A scenario draws d standard normals per step, in the order scenario, step, model. A single model with ρ = [1;;] gives exactly the paths of simulate(model; rng).
With Copulas.jl loaded, a d-dimensional copula can take the place of ρ, simulate(models, copula; ...). Each step draws one sample of uniforms from the copula and maps each through the standard normal quantile to a model's innovation, so the copula is the dependence of each step's innovations, not of the models' later values. A GaussianCopula is simulated as its correlation matrix and an IndependentCopula as the identity, exactly as the matrix method. A copula sample of exactly 0 or 1 throws a DomainError rather than giving an infinite shock. Copula-parameter sensitivities use the Gaussian correlation-matrix path only. Generic copulas declaring derivative-carrying samples throw an ArgumentError before sampling; derivatives through their sampling algorithms need not be derivatives of expectations. Model-parameter sensitivities with a fixed copula remain supported.
FinanceModels.pv_mc — Function
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.
pv_mc is designed for fixed-cashflow instruments where each RatePath scenario provides the discount factors. For floating-rate instruments whose cashflows depend on the rate path, project cashflows per scenario using Projection instead.
The horizon must cover the contract's maturity, since a simulated path throws beyond its horizon. The default (maturity + 1) ensures this.
FinanceModels.short_rate — Function
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.
Unexported API
FinanceModels.ShortRate.CoxIngersollRoss — Type
CoxIngersollRoss(a, b, σ, initial)Cox-Ingersoll-Ross (1985) mean-reverting short-rate model:
dr = a(b - r) dt + σ √r dWArguments
a: speed of mean reversionb: long-term mean rate. ARateis converted to its continuously compounded equivalent.σ: volatilityinitial: initial short rater₀(aRateobject orReal)
The condition 2ab > σ² is required for the variance process to stay strictly positive. When violated, the short rate can reach zero; simulation uses the full truncation scheme (Lord, Koekkoek & Van Dijk, 2010), which lets an auxiliary process go negative while the observed rate is floored at zero. Discretisation bias grows with σ²/(2ab) — use a finer timestep when the Feller condition is strongly violated.
FinanceModels.ShortRate.HullWhite — Type
HullWhite(a, σ, curve)Hull-White (1990) one-factor model:
dr = (θ(t) - a r) dt + σ dWwhere θ(t) is calibrated to fit the initial term structure curve.
Arguments
a: speed of mean reversionσ: volatilitycurve: an existing yield model providing the initial term structure
FinanceModels.ShortRate.Vasicek — Type
Vasicek(a, b, σ, initial)Vasicek (1977) mean-reverting short-rate model:
dr = a(b - r) dt + σ dWArguments
a: speed of mean reversionb: long-term mean rate. ARateis converted to its continuously compounded equivalent.σ: volatilityinitial: initial short rater₀(aRateobject orReal)
Please open an issue if you encounter any issues or confusion with the package.