API Documentation

Risk Factor Modeling

risk_factor_model.RiskFactor
risk_factor_model.RiskFactorModel	param inner_factor:  parameter object which is modeled by the risk factor model
risk_factor_model.RiskFactorState	param list() value:
risk_factor_model.RiskFactorProducer	param RiskFactorModel process:
risk_factor_model.MultiRiskFactorProducer	param list(RiskFactorModel) process_list:
risk_factor_model.RiskFactorConsumer	consumer of RiskFactorState

class 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 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 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

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

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

start_date = None

BusinessDate – valuation date

class risk_factor_model.RiskFactorModel(inner_factor, start_value=0.0)

Bases: timewave.stochasticprocess.StochasticProcess, risk_factor_model.RiskFactor

Parameters:

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

initialize risk factor model

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.

get_numeraire(value_date)

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

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)

set_risk_factor(factor_date, 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 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 risk_factor_model.RiskFactorState(value=[], numeraire_value=0.0)

Bases: timewave.engine.State

Parameters:

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

inits RiskFactorState

Market Risk Factors

market_risk_factor.BrownianZeroRateCurve	simple Brownian motion rate diffusion
market_risk_factor.GBMFxCurve	models fx spot rate as spot * x

class market_risk_factor.BrownianZeroRateCurve(x_list=None, y_list=None, y_inter=None, origin=None, day_count=None, forward_tenor=None, drift=0.0, volatility=0.0, inner_factor=None)

Bases: dcf.curve.ZeroRateCurve, risk_factor_model.RiskFactorModel

simple Brownian motion rate diffusion

initializes Hull White curve

Parameters:

• x_list (list(float)) –
• y_list (list(float)) –
• y_inter (list(interpolation)) –
• origin (BusinessDate) –
• day_count (DayCount) –
• forward_tenor (BusinessPeriod) –
• or function drift (float) –
• or function volatility (float) –
• inner_factor (RateCurve) –

classmethod cast(other, drift=0.0, volatility=0.0)

evolve(x, s, e, q)

get_zero_rate(start, stop)

class market_risk_factor.GBMFxCurve(x_list=None, y_list=None, y_inter=None, origin=None, day_count=None, domestic_curve=None, foreign_curve=None, volatility=0.0, inner_factor=None)

Bases: dcf.fx.FxCurve, risk_factor_model.RiskFactorModel

models fx spot rate as spot * x

Parameters:

• x_list (list(BusinessDate)) –
• y_list (list(BusinessDate)) –
• y_inter (list()) –
• origin (BusinessDate) –
• day_count (DayCount) –
• domestic_curve (RateCurve) –
• foreign_curve (RateCurve) –
• or function volatility (float) –
• inner_factor (FxCurve) –

classmethod cast(other, volatility=0.0)

Parameters:

• other (FxCurve) – FxCurve to retrieve factor expectation
• or function or Curve volatility (float) – fx rate volatility

evolve(x, s, e, q)

get_fx_rate(value_date)

The Hull White Model

hullwhite_model.HullWhiteCurve

calculation of discount factors in the Hull White model

class hullwhite_model.HullWhiteCurve(x_list=None, y_list=None, y_inter=None, origin=None, day_count=None, forward_tenor=None, mean_reversion=0.0, volatility=0.0, terminal_date=None, inner_factor=None)

Bases: dcf.curve.ZeroRateCurve, risk_factor_model.RiskFactorModel

calculation of discount factors in the Hull White model

Parameters:

• x_list (list(float)) –
• y_list (list(float)) –
• y_inter (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 curve

calc_integral_B(t1, t2)

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_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_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$$

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$

classmethod cast(other, mean_reversion=0.0, volatility=0.0, terminal_date=None)

Parameters:

• other (ZeroRateCurve) –
• 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

Returns:

HullWhiteCurve

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

evolve(x, s, e, q)

Parameters:

• x –
• s –
• e –
• q –

Returns:

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

get_discount_factor(start_date, end_date)

Parameters:

• start_date (BusinessDate) – start date
• end_date (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).

get_zero_rate(S, T)

Parameters:

• S –
• T –

Returns:

calculate zero rate between S and T.

pre_calculate(s, e)

Parameters:

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

pre calculate values based only on grid points

set_risk_factor(factor_date, 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`

Multi Currency Hull White Model Extension

hullwhite_multicurrency_model.HullWhiteFxCurve	param list(BusinessDate) x_list:
hullwhite_multicurrency_model.HullWhiteMultiCurrencyCurve	initializes foreign Hull White curve in multi currency model

class hullwhite_multicurrency_model.HullWhiteFxCurve(x_list=None, y_list=None, y_inter=None, 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, inner_factor=None)

Bases: market_risk_factor.GBMFxCurve

Parameters:

• x_list (list(BusinessDate)) –
• y_list (list(BusinessDate)) –
• y_inter (list()) –
• origin (BusinessDate) –
• day_count (DayCount) –
• domestic_curve (HullWhiteCurve) –
• foreign_curve (HullWhiteCurve) –
• volatility (float or function or Curve) –
• domestic_correlation (float) –
• foreign_correlation (float) –
• rate_correlation (float) –
• inner_factor (GBMFxCurve or FxCurve) –

classmethod cast(fx_curve, domestic_curve, foreign_curve, volatility=0.0, correlation=None)

Parameters:

• fx_curve (GBMFxCurve or FxCurve) – FxCurve to retrieve factor expectation
• domestic_curve (HullWhiteCurve) – domestic HullWhiteCurve
• foreign_curve (HullWhiteCurve) – foreign HullWhiteCurve
• volatility (float or function) – fx spot forward volatility
• correlation (dict(RiskFactorModel, RiskFactorModel)) – correlation matrix indexed by risk factors

Build HullWhiteFxCurve from HullWhiteCurves and GBMFxCurve. Terminal measure date in foreign_curve is ignored since it is taken from domestic_curve.

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

get_fx_rate(value_date)

pre_calculate(s, e)

class hullwhite_multicurrency_model.HullWhiteMultiCurrencyCurve(x_list=None, y_list=None, y_inter=None, origin=None, day_count=None, forward_tenor=None, mean_reversion=0.0001, volatility=0.0, domestic_curve=None, fx_curve=None, foreign_correlation=0.0, rate_correlation=0.0, inner_factor=None)

Bases: hullwhite_model.HullWhiteCurve

initializes foreign Hull White curve in multi currency model

Parameters:

• x_list (list(float)) –
• y_list (list(float)) –
• y_inter (list(interpolation)) –
• origin (BusinessDate) –
• day_count (DayCount) –
• forward_tenor (BusinessPeriod) –
• or function mean_reversion (float) – volatility of foreign short rate process
• or function volatility (float) – volatility of foreign short rate process
• domestic_curve (HullWhiteCurve) – domestic rate HullWhite process
• or GBMFxCurve fx_curve (HullWhiteFxCurve) – fx curve with volatility of ln(fx) process
• foreign_correlation (float) – correlation of ln(fx) process and foreign rate process
• rate_correlation (float) – correlation of domestic rate process and foreign rate process
• inner_factor (RateCurve) –

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:

classmethod cast(foreign_curve, domestic_curve, fx_curve)

Parameters:

• foreign_curve (HullWhiteCurve) –
• domestic_curve (HullWhiteCurve) –
• fx_curve (HullWhiteFxCurve) –

Return HullWhiteMultiCurrencyCurve:  

build HullWhiteMultiCurrencyCurve from HullWhiteCurves and HullWhiteFxCurve. Terminal measure date in foreign_curve is ignored since it is taken from domestic_curve.