# Implementing SOR models in OWL


This content generated by ChatGPT 5.2 Instance, 2/13/2026

Below is a draft specification you can drop into your documentation for
the new TOML methods:

- `method = "toeplitz_sor"`
- `method = "bootstrap_sor"`

# Additions to `[rates_selection]`

## New Methods

    method = "toeplitz_sor"
    method = "bootstrap_sor"

These methods model **sequence-of-returns risk using time dependence
across years** rather than independent annual draws.

# Toeplitz Sequence-of-Returns Method

    method = "toeplitz_sor"

## Description

Generates correlated multi-year return paths using a stationary Toeplitz
time covariance structure. Correlation depends only on lag (k-year
separation).

This method models:

- Time persistence (e.g., bad years cluster)
- Volatility clustering (if enabled)
- Optional fat-tailed innovations
- Smooth regime behavior

Returns are generated via multivariate sampling with a structured time
covariance matrix.

## Required Parameters

### `values`

Type: list of 4 floats Description: Mean annual rates (percent format)
for:

    [S&P 500, Corporate Baa, 10-year Treasury, Inflation]

## Optional Parameters

### `standard_deviations`

Type: list of 4 floats Description: Annual volatility (percent format)
for each asset class.

Required unless using historical calibration (see below).

### `correlations`

Type: 4×4 matrix or 6-value flattened list Description: Cross-asset
contemporaneous correlation matrix.

Same format as current stochastic method.

### `autocorrelation_lag1`

Type: float or list of 4 floats Description: AR(1)-style lag-1
autocorrelation coefficient(s).

- Single value → applied to all assets
- List → one per asset

Typical values:

- 0.15 to 0.35 for equities
- 0.05 to 0.20 for bonds

### `autocorrelation_decay`

Type: float Description: Exponential decay rate for higher lags.

Defines:

\[ \_k = \_1 ()^{k-1}\]

Default: 0.7

If omitted, pure AR(1) structure is used.

### `innovation_distribution`

Type: string Valid values:

    "normal"
    "student_t"

Default: `"normal"`

If `"student_t"` is selected:

### `degrees_of_freedom`

Type: integer Description: Tail thickness for Student-t innovations.

Typical values:

- 5–8 → realistic equity tails
- \<5 → very heavy tails

### `volatility_regime`

Type: string Valid values:

    "none"
    "garch"

Optional extension for later implementation.

### `rate_seed`

Type: integer Description: Random seed for reproducible sequence
generation.

### `reproducible_rates`

Type: boolean Description: Whether to reuse the seed or regenerate.

## Behavioral Notes

- `reverse_sequence` and `roll_sequence` remain supported.
- Stationary process assumption.
- Does not resample history.
- Does not preserve structural breaks.
- Smooth persistence only.

# Bootstrap Sequence-of-Returns Method

    method = "bootstrap_sor"

## Description

Generates multi-year return paths by resampling blocks of historical
returns from 1928–2025.

Preserves:

- Real crisis clusters
- Empirical skew and kurtosis
- Historical regime structure
- Multi-year drawdowns

## Required Parameters

### `from`

Type: integer Description: Start year of historical window.

### `to`

Type: integer Description: End year of historical window.

Must satisfy:

    1928 ≤ from < to ≤ 2025

## Optional Parameters

### `block_length`

Type: integer Description: Number of consecutive years per block.

Typical values:

- 2 → weak clustering
- 3–5 → realistic regime clustering
- 5–7 → strong clustering

Default: 3

### `bootstrap_mode`

Type: string Valid values:

    "overlapping"
    "non_overlapping"

Default: `"overlapping"`

Overlapping blocks provide smoother statistical properties.

### `circular_blocks`

Type: boolean Description: Whether blocks wrap at end of dataset.

Default: true

### `rate_seed`

Type: integer Description: Seed for reproducible block sampling.

### `reproducible_rates`

Type: boolean Description: Whether to reuse seed.

## Behavioral Notes

- No parametric assumptions.
- Exact historical tail behavior.
- Preserves crisis clustering.
- No artificial smoothing.
- Reverse/roll options apply after block construction.

# Comparison Summary (for Documentation)

| Feature                   | toeplitz_sor | bootstrap_sor |
|---------------------------|--------------|---------------|
| Stationary                | Yes          | No            |
| Gaussian assumption       | Optional     | No            |
| Fat tails                 | Optional     | Natural       |
| Crisis clusters           | Approximate  | Exact         |
| Parametric control        | High         | Low           |
| Empirical realism         | Moderate     | High          |
| Implementation complexity | Moderate     | Moderate      |

# Suggested Defaults

For conservative retirement modeling:

## Toeplitz default:

    autocorrelation_lag1 = 0.25
    autocorrelation_decay = 0.7
    innovation_distribution = "student_t"
    degrees_of_freedom = 6

## Bootstrap default:

    block_length = 3
    bootstrap_mode = "overlapping"
    circular_blocks = true

# Optional Future Extension

    sequence_stress = "none" | "early_crash" | "late_crash"
