Return Models¶
Return models generate asset return paths for the simulation. All models implement the ReturnModel protocol.
ReturnModel Protocol¶
ReturnModel
¶
Bases: Protocol
Protocol for asset return generators.
sample(n_paths, n_steps, rng)
¶
Generate random returns.
Returns:
| Type | Description |
|---|---|
ndarray
|
Array of shape (n_paths, n_steps, n_assets) with monthly returns. |
MultivariateNormalReturns¶
MultivariateNormalReturns
¶
Generate correlated asset returns from a multivariate normal distribution.
Converts annual return/volatility assumptions to monthly, then samples using the numpy multivariate normal generator.
sample(n_paths, n_steps, rng)
¶
Generate correlated monthly returns.
Returns:
| Type | Description |
|---|---|
ndarray
|
Array of shape (n_paths, n_steps, n_assets) with monthly returns. |
StudentTReturns¶
StudentTReturns
¶
Generate correlated asset returns from a multivariate student-t distribution.
Uses Cholesky decomposition + univariate t-distributed marginals to produce correlated fat-tailed returns.
sample(n_paths, n_steps, rng)
¶
Generate correlated fat-tailed monthly returns.
Uses the approach: X = mu + sigma * L @ (Z / sqrt(W/df)) where Z ~ N(0,1) and W ~ chi2(df), L = cholesky(corr).
Returns:
| Type | Description |
|---|---|
ndarray
|
Array of shape (n_paths, n_steps, n_assets) with monthly returns. |
HistoricalBootstrapReturns¶
HistoricalBootstrapReturns
¶
Block bootstrap from historical monthly returns.
Samples contiguous blocks of historical returns to preserve autocorrelation structure, then tiles to fill the required number of steps.
__init__(historical_returns, block_size=12)
¶
Initialize with historical data.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
historical_returns
|
ndarray
|
(n_months, n_assets) array of historical monthly returns. |
required |
block_size
|
int
|
Number of contiguous months per block. |
12
|
sample(n_paths, n_steps, rng)
¶
Generate bootstrapped monthly returns.
Returns:
| Type | Description |
|---|---|
ndarray
|
Array of shape (n_paths, n_steps, n_assets) with monthly returns. |
RegimeSwitchingReturns¶
RegimeSwitchingReturns
¶
Generate correlated asset returns with Markov regime switching.
Each regime has its own mean returns, volatilities, and correlation structure. Regime transitions follow a discrete Markov chain with a pre-specified transition matrix.
sample(n_paths, n_steps, rng)
¶
Generate correlated monthly returns with regime switching.
Returns:
| Type | Description |
|---|---|
NDArray[floating[Any]]
|
Array of shape (n_paths, n_steps, n_assets) with monthly returns. |
Inflation Models¶
OUInflationModel¶
OUInflationModel
¶
Stochastic inflation via an Ornstein-Uhlenbeck process.
dI = kappa * (theta - I) * dt + sigma * dW
where
I = annualized inflation rate theta = long-run mean inflation kappa = mean-reversion speed sigma = annual volatility of inflation
sample(n_paths, n_steps, rng)
¶
Generate monthly inflation rate paths.
Returns:
| Type | Description |
|---|---|
ndarray
|
Array of shape (n_paths, n_steps) with monthly inflation rates |
ndarray
|
(i.e., annual rate / 12 per step). |
RegimeSwitchingInflationModel¶
RegimeSwitchingInflationModel
¶
OU inflation with regime-dependent theta/sigma.
At each time step, the mean-reversion target (theta) and volatility (sigma) are determined by the current market regime, coupling inflation dynamics to the regime-switching return model.
sample(n_paths, n_steps, rng, regime_indices)
¶
Generate monthly inflation rate paths with regime-dependent parameters.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
n_paths
|
int
|
Number of simulation paths. |
required |
n_steps
|
int
|
Number of monthly time steps. |
required |
rng
|
Generator
|
Numpy random generator. |
required |
regime_indices
|
NDArray[intp]
|
(n_paths, n_steps) array of regime indices from the regime-switching return model. |
required |
Returns:
| Type | Description |
|---|---|
NDArray[floating[Any]]
|
Array of shape (n_paths, n_steps) with monthly inflation rates. |
Stress Scenarios¶
apply_stress_scenarios(returns, inflation_rates, scenarios, timeline)
¶
Apply stress scenario overlays to pre-generated returns and inflation.
Modifies the arrays in-place and also returns them.
Parameters:
| Name | Type | Description | Default |
|---|---|---|---|
returns
|
ndarray
|
(n_paths, n_steps, n_assets) monthly asset returns. |
required |
inflation_rates
|
ndarray
|
(n_paths, n_steps) monthly inflation rates. |
required |
scenarios
|
list[StressScenario]
|
List of stress scenarios to apply. |
required |
timeline
|
Timeline
|
Timeline for age-to-step conversion. |
required |
Returns:
| Type | Description |
|---|---|
tuple[ndarray, ndarray]
|
Modified (returns, inflation_rates) tuple. |