API Documentation

Risk Factor Modeling

RiskFactor
RiskFactorModel	RiskFactorModel which implements StochasticProcess evolve for timewave engine
RiskFactorState	param list() value:
RiskFactorProducer	param RiskFactorModel process:
MultiRiskFactorProducer	param list(RiskFactorModel) process_list:
RiskFactorConsumer	consumer of RiskFactorState

class shortrate.risk_factor_model.RiskFactor

Bases: object

inner_factor

RiskFactor typically move given data structure like yield curves, fx curves or volatility surfaces. The inner factor is the driven structure.

pre_calculate(s, e)

Parameters:

• s (BusinessDate) – start date pre calc step
• e (BusinessDate) – end date pre calc step

pre calculation depending only on dates and model data

set_risk_factor(factor_date, factor_value=None)

Parameters:

• factor_date (BusinessDate) –
• or tuple factor_value (float) –

sets risk factor state, method should be idempotent, i.e. setting same state twice must not change risk factor state at all

class shortrate.risk_factor_model.RiskFactorModel(inner_factor=None, start=0.0)

Bases: timewave.stochasticprocess.base.StochasticProcess, shortrate.risk_factor_model.RiskFactor

RiskFactorModel which implements StochasticProcess evolve for timewave engine

Parameters:

• inner_factor (Curve or Volatility or object) – parameter object which is modeled by the risk factor model
• start (float or tuple) –

initialize risk factor model

pre_calculate(s, e)

Parameters:

• s (BusinessDate) – start date pre calc step
• e (BusinessDate) – end date pre calc step

pre calculation depending only on dates and model data (RiskFactor method)

get_numeraire(value_date)

Parameters:value_date (BusinessDate) – date of Return float:returns the numeraire value

evolve(x, s, e, q)

Parameters:

• x (float) – current state value, i.e. value before evolution step
• s (BusinessDate) – current point in time, i.e. start point of next evolution step
• e (BusinessDate) – next point in time, i.e. end point of evolution step
• q (float) – standard normal random number to do step

Return float:

next state value, i.e. value after evolution step

evolves process state x from s to e in time depending of standard normal random variable q

evolve_risk_factor(x, s, e, q)

Parameters:

• x (float) – current state value, i.e. value before evolution step
• s (BusinessDate) – current point in time, i.e. start point of next evolution step
• e (BusinessDate) – next point in time, i.e. end point of evolution step
• q (float) – standard normal random number to do step

Return float:

next state value, i.e. value after evolution step

evolves process state x from s to e in time depending of standard normal random variable q and sets risk factor at e to x after evolving from s.

set_risk_factor(factor_date=None, factor_value=None)

Parameters:

• factor_date (BusinessDate) – sets risk factor state at this date
• factor_value (float or tuple) – sets risk factor state to this value

sets risk factor state, method should be idempotent, i.e. setting same state twice must not change risk factor state at all (RiskFactor method)

class shortrate.risk_factor_model.RiskFactorState(value=[], numeraire_value=0.0)

Bases: timewave.engine.State

Parameters:

• value (list()) –
• numeraire_value (float) –

inits RiskFactorState

class shortrate.risk_factor_model.RiskFactorProducer(process)

Bases: timewave.stochasticproducer.GaussEvolutionFunctionProducer

Parameters:process (RiskFactorModel) –

producer for timewave simulation framework to evolve a RiskFactorModel depending of standard normal random values

initialize(grid=None, num_of_paths=None, seed=None)

Parameters:

• grid (list(BusinessDate)) – list of Monte Carlo grid dates
• num_of_paths (int) – number of simulation path
• seed (hashable) – initial seed of random generators

sets pre calculation depending only on grid

initialize_path(path_num=None)

initialize RiskFactorConsumer for path

class shortrate.risk_factor_model.MultiRiskFactorProducer(process_list, correlation=None, diffusion_driver=None)

Bases: timewave.stochasticproducer.CorrelatedGaussEvolutionProducer

Parameters:

• process_list (list(RiskFactorModel)) –
• correlation (list(list(float)) or dict((RiskFactorModel, RiskFactorModel): float)) – correlation of diffusion drivers of risk factors
• diffusion_driver (list(RiskFactorModel)) – index of diffusion driver if correlation is given by simple matrix (list(list(float)))

initialize MultiRiskFactorProducer

class shortrate.risk_factor_model.RiskFactorConsumer(*risk_factor_list)

Bases: timewave.consumers.QuietConsumer

consumer of RiskFactorState

Parameters:risk_factor_list (list(RiskFactor)) – list of risk factors which will be driven by risk factor state

initialize RiskFactorConsumer

start_date = None

valuation date

Type:BusinessDate

initialize(grid=None, num_of_paths=None, seed=None)

Parameters:

• grid (list(BusinessDate)) – list of Monte Carlo grid dates
• num_of_paths (int) – number of simulation path
• seed (hashable) – initial seed of random generators

sets pre calculation depending only on grid

initialize_path(path_num=None)

initialize RiskFactorConsumer for path

consume(state)

Parameters:state (RiskFactorState) – specific process state Return object:the new consumer state

returns pair the first element is the list of updated simulated hw curves the second element is True (indicates Curve mapping)

finalize()

finalize RiskFactorConsumer

Market Risk Factors

GaussRiskFactorModel	risk factor modeled as timewave.TimeDependentWienerProcess
GeometricBrownianMotionRiskFactorModel	risk factor modeled as timewave.TimeDependentGeometricBrownianMotion
GeometricBrownianMotionPriceFactorModel	risk factor modeled as GeometricBrownianMotionRiskFactorModel
GeometricBrownianMotionPrice
GeometricBrownianMotionFxRateFactorModel
GeometricBrownianMotionFxRate
GaussFlatSpreadZeroRateCurveFactorModel
GaussFlatSpreadZeroRateCurve	simple Brownian motion rate diffusion

class shortrate.market_risk_factor.GaussRiskFactorModel(inner_factor, mu=0.0, sigma=0.0, time=0.0027378507871321013, start=0.0)

Bases: shortrate.risk_factor_model.RiskFactorModel, timewave.stochasticprocess.gauss.TimeDependentWienerProcess

risk factor modeled as timewave.TimeDependentWienerProcess

class shortrate.market_risk_factor.GeometricBrownianMotionRiskFactorModel(inner_factor, mu=0.0, sigma=0.0, time=0.0027378507871321013, start=0.0)

Bases: shortrate.market_risk_factor.GaussRiskFactorModel, timewave.stochasticprocess.gauss.TimeDependentGeometricBrownianMotion

risk factor modeled as timewave.TimeDependentGeometricBrownianMotion

class shortrate.market_risk_factor.GeometricBrownianMotionPriceFactorModel(inner_factor, drift=0.0, volatility=0.0)

Bases: dcf.fx.Price, shortrate.market_risk_factor.GeometricBrownianMotionRiskFactorModel

risk factor modeled as GeometricBrownianMotionRiskFactorModel

class shortrate.market_risk_factor.GeometricBrownianMotionPrice(value=0.0, origin=None, day_count=None, drift=0.0, volatility=0.0)

Bases: shortrate.market_risk_factor.GeometricBrownianMotionPriceFactorModel

class shortrate.market_risk_factor.GeometricBrownianMotionFxRateFactorModel(inner_factor, domestic_curve=None, foreign_curve=None, volatility=0.0)

Bases: dcf.fx.FxRate, shortrate.market_risk_factor.GeometricBrownianMotionRiskFactorModel

class shortrate.market_risk_factor.GeometricBrownianMotionFxRate(value=1.0, origin=None, day_count=None, domestic_curve=None, foreign_curve=None, volatility=0.0)

Bases: shortrate.market_risk_factor.GeometricBrownianMotionFxRateFactorModel

class shortrate.market_risk_factor.GaussFlatSpreadZeroRateCurveFactorModel(inner_factor, drift=0.0, volatility=0.0)

Bases: dcf.interestratecurve.ZeroRateCurve, shortrate.market_risk_factor.GaussRiskFactorModel

class shortrate.market_risk_factor.GaussFlatSpreadZeroRateCurve(domain=None, data=None, interpolation=None, origin=None, day_count=None, forward_tenor=None, drift=0.0, volatility=0.0)

Bases: shortrate.market_risk_factor.GaussFlatSpreadZeroRateCurveFactorModel

simple Brownian motion rate diffusion

The Hull White Model

Single Currency

HullWhiteCurveFactorModel	build HullWhiteCurve i.e.
shortrate.HullWhiteCurve

class shortrate.hullwhite_model.HullWhiteCurveFactorModel(inner_factor, mean_reversion=0.0, volatility=0.0, terminal_date=None)

Bases: dcf.interestratecurve.ZeroRateCurve, shortrate.risk_factor_model.RiskFactorModel

build HullWhiteCurve i.e. Hull White model in terminal measure from ZeroRateCurve, mean reversion speed, volatility and terminal measure date.

Parameters:

• domain (list(float)) –
• data (list(float)) –
• interpolation (list(interpolation)) –
• origin (BusinessDate) –
• day_count (DayCount) –
• forward_tenor (BusinessPeriod) – standard forward
• mean_reversion (float or function) – mean reversion speed of short rate process
• volatility (float or function) – short rate volatility
• terminal_date (BusinessDate) – date of terminal measure
• inner_factor (RateCurve) –

initializes Hull White drift

calc_integral_I1(t1, t2)

Parameters:

• t1 (float) – start time as year fraction / float
• t2 (float) – end time as year fraction / float

Returns:

float

returns the value of the helper function I1

\[I_1(t_1, t_2) = \exp \left( -\int_{t_1}^{t_2} a(\tau) \,\mathrm{d}\tau \right) = \mathrm{e}^{-a(t_2 - t_1)}\]

calc_integral_I1_squared(t1, t2)

Parameters:

• t1 (float) – start time as year fraction / float
• t2 (float) – end time as year fraction / float

Return float:

returns the value of the helper function I1^2

\[I_1(t_1, t_2)^2 = \exp \left( -2\int_{t_1}^{t_2} a(\tau) \,\mathrm{d}\tau \right) = \mathrm{e}^{-2a(t_2 - t_1)}\]

calc_integral_B(t1, t2, mr=None)

returns the value of the helper function B

\[B(t_1, t_2) = \int_{t_1}^{t_2} I_1(t_1, \tau) \, \mathrm{d}\tau = \frac{1}{a}\Big(1 - \mathrm{e}^{-a(t_2 - t_1)}\Big)\]

Parameters:

• t1 (float) – start time as year fraction / float
• t2 (float) – end time as year fraction / float

Return float:

calc_integral_volatility_squared_with_I1(t1, t2)

Parameters:

• t1 –
• t2 –

Return float:

Calculates integral of integrand \(f\) with \(I_1\) between two time points \(t_1\) and \(t_2\) with \(t_1 \le t_2\) is as:

\[extrm{Var}_r(t_1,t_2) = \int_{t_1}^{t_2} vol(u)^2 I_1(u,t_2) \,\mathrm{d} u\]

calc_integral_volatility_squared_with_I1_squared(t1, t2)

Parameters:

• t1 –
• t2 –

Return float:

calculates drift integral \(I_2\)

calc_integral_I2(s, t)

Parameters:

• s (float) – start time as year fraction / float
• t (float) – end time as year fraction / float

Return float:

returns the value of the helper function Integrals

One of the deterministic terms of a step in the MC simulation is calculated here with last observation date for T-Bond numeraire T

\[\int_s^t \sigma^2(u) I_1(u,t) (B(u,t)-B(u,T)) \,\mathrm{d} u + B(s,t)I_1(s,t)\int_0^s \sigma^2(u) I_1^2(u,s)\,\mathrm{d}u\]

pre_calculate(s, e)

Parameters:

• s (BusinessDate) – start date
• e (BusinessDate) – end date

pre calculate values based only on grid points

evolve(x, s, e, q)

evolve Hull White process of shortrate diviation math:: y = r - y

set_risk_factor(factor_date=None, factor_value=0.0)

Parameters:

• factor_date (BusinessDate) – date of t
• factor_value (float) – value of risk factor y

set \(y=r(t)-F(0,t)\) risk factor and prepare discount factor integral .. :math: ` int_0^t sigma(u)^2 I_1(u, t) du`

get_discount_factor(start, stop=None)

Parameters:

• start (BusinessDate) – start date
• stop (BusinessDate) – end date

Return float:

calculate the discount rate for the given start date and end date

\[P_{u,y}: \textrm{BusinessDate} {\times} \textrm{BusinessDate} \to \mathbb{R}\]

and

\[(s,t) \mapsto P_{\text{init}}(s,t) \exp \left(-\frac{1}{2}(B^2(u,t)-B^2(u,s)) \int_0^u \sigma^2(\tau)I_1(\tau,t), \mathrm{d}\tau\right)\mathrm{e}^{-(B(t,T)-B(t,S))y}\]

with \(P_{\text{init}}(s,t) = \verb|Curve.get_discount_curve(s,t)|\)

Here the variables with subscript \(\textrm{pld}\) are dates (BusinessDate instances) and the variables without subscripts are year fractions between the correspondent \(\textrm{pld}\) variables and \(\verb|validity_date|\) in the default DCC (Act/365.25).

class shortrate.hullwhite_model.HullWhiteCurve(domain=(), data=(), interpolation=None, origin=None, day_count=None, forward_tenor=None, mean_reversion=0.0, volatility=0.0, terminal_date=None)

Bases: shortrate.hullwhite_model.HullWhiteCurveFactorModel

Multi Currency Extension

HullWhiteFxRateFactorModel	param GeometricBrownianMotionFxRateFactorModel or FxRate inner_factor:  if FxRate, volatility is used
HullWhiteFxRate
HullWhiteMultiCurrencyCurveFactorModel	build HullWhiteMultiCurrencyCurve from HullWhiteCurves and HullWhiteFxCurve.
HullWhiteMultiCurrencyCurve	initializes foreign Hull White drift in multi currency model

class shortrate.hullwhite_multicurrency_model.HullWhiteFxRateFactorModel(inner_factor, domestic_hw_curve, foreign_hw_curve, volatility=0.0, domestic_correlation=0.0, foreign_correlation=0.0, rate_correlation=0.0, correlation=None)

Bases: dcf.fx.FxRate, shortrate.risk_factor_model.RiskFactorModel

Parameters:

• or FxRate inner_factor (GeometricBrownianMotionFxRateFactorModel) – if FxRate, volatility is used
• domestic_hw_curve (HullWhiteCurveFactorModel) –
• foreign_hw_curve (HullWhiteCurveFactorModel) –
• float – volatility (optional) Default: either inner_factor.volatility or 0.0
• domestic_correlation (float) – (optional) Default: 0.0
• foreign_correlation (float) – (optional) Default: 0.0
• rate_correlation (float) – (optional) Default: 0.0
• RiskFactorModel), float) correlation (dict((RiskFactorModel,) – (optional) Default: explicit given correlations

pre_calculate(s, e)

Parameters:

• s (BusinessDate) – start date pre calc step
• e (BusinessDate) – end date pre calc step

pre calculation depending only on dates and model data (RiskFactor method)

evolve(x, s, e, q)

Parameters:

• x (float) – current state value, i.e. value before evolution step
• s (BusinessDate) – current point in time, i.e. start point of next evolution step
• e (BusinessDate) – next point in time, i.e. end point of evolution step
• float, float] q ([float,) – standard normal random list number to do step

Return float:

next state value, i.e. value after evolution step

evolves process state x from s to e in time depending of standard normal random variable q

class shortrate.hullwhite_multicurrency_model.HullWhiteFxRate(value=1.0, origin=None, day_count=None, domestic_curve=None, foreign_curve=None, volatility=0.0, domestic_correlation=0.0, foreign_correlation=0.0, rate_correlation=0.0, correlation=None)

Bases: shortrate.hullwhite_multicurrency_model.HullWhiteFxRateFactorModel

class shortrate.hullwhite_multicurrency_model.HullWhiteMultiCurrencyCurveFactorModel(inner_factor, domestic_hw_curve, hw_fx_curve)

Bases: shortrate.hullwhite_model.HullWhiteCurveFactorModel

build HullWhiteMultiCurrencyCurve from HullWhiteCurves and HullWhiteFxCurve. Terminal measure date in foreign_curve is ignored since it is taken from domestic_curve. initializes foreign Hull White drift in multi currency model

Parameters:

• inner_factor (HullWhiteCurveFactorModel) –
• domestic_hw_curve (HullWhiteCurveFactorModel) –
• hw_fx_curve (HullWhiteFxRateFactorModel) –

calc_integral_I2(s, t)

calculates the following integral (see formula for the step in the MC evolution)

\[\begin{split}\textrm{Var}(\chi(t) | \mathcal{F}_s) = \int_s^t \sigma^2_d(u)B^2_d(u, T) + \sigma^2_f(u)B^2_f(u,T) + \sigma^2_{FX}(u) \\ + 2\left(- \rho_{d,f} B_f(u, T)\sigma_f(u)B_d(u, T)\sigma_d(u) + \left( - \rho_{f,FX} B_f(u, T)\sigma_f(u) + \rho_{d,FX} B_d(u, T)\sigma_d(u) \right) \sigma_{FX}(u) \right)\,\mathrm{d}u\end{split}\]

Parameters:

• s (float) –
• t (float) –

Return float:

class shortrate.hullwhite_multicurrency_model.HullWhiteMultiCurrencyCurve(domain=(), data=(), interpolation=None, origin=None, day_count=None, forward_tenor=None, mean_reversion=0.0001, volatility=0.0, domestic_hw_curve=None, hw_fx_curve=None)

Bases: shortrate.hullwhite_multicurrency_model.HullWhiteMultiCurrencyCurveFactorModel

initializes foreign Hull White drift in multi currency model

Parameters:

• domain (list(BusinesDate)) –
• data (list(float)) –
• dcf.interpolation, dcf.interpolation) interpolation ((dcf.interpolation,) –
• origin (BusinessDate) –
• day_count (function) –
• forward_tenor (BusinessPeriod) –
• mean_reversion (float) –
• or float volatility (TimeDependentParameter) –
• domestic_hw_curve (HullWhiteCurveFactorModel) –
• hw_fx_curve (HullWhiteFxRateFactorModel) –
• foreign_correlation (float) –
• rate_correlation (float) –