---
title: Implementing SOR models in OWL
format: gfm
---

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 gaussian 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:

[
\rho_k = \rho_1 \cdot (\text{decay})^{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"
```

