use crate::mathx;
pub const OMEGA: f64 = 0.000002;
pub const ALPHA: f64 = 0.02;
pub const BETA: f64 = 0.80;
pub const GAMMA: f64 = 0.34;
pub const CEILING_MULTIPLE: f64 = 5.0;
pub const FLOOR_MULTIPLE: f64 = 0.25;
pub fn vix_coupled_response(
params: &crate::params::ModelParams,
coupling: f64,
vix_ratio: f64,
) -> f64 {
if params.garch_vix_exponent == 2.0 {
coupling * vix_ratio * vix_ratio
} else {
coupling * mathx::pow(vix_ratio, params.garch_vix_exponent)
}
}
pub const CASCADE_MAX: usize = 8;
pub fn update_garch_cascade(
params: &crate::params::ModelParams,
garch_beta: f64,
cascade: &mut [f64; CASCADE_MAX],
last_daily_return: f64,
sector_base_variance: f64,
) -> f64 {
let requested = params.garch_cascade_components as usize;
let k = if requested > CASCADE_MAX { CASCADE_MAX } else { requested };
let asym = if last_daily_return < 0.0 { params.garch_gamma } else { 0.0 };
let shock = (params.garch_alpha + asym) * last_daily_return * last_daily_return;
let persistence = params.garch_alpha + garch_beta + params.garch_gamma / 2.0;
if !(persistence > 0.0 && persistence < 1.0) {
return update_garch_variance_for(
params, garch_beta, cascade[0], last_daily_return, sector_base_variance);
}
let base_half_life = mathx::log(0.5) / mathx::log(persistence);
let previous_component_0 = cascade[0];
let mut total = 0.0;
for (i, slot) in cascade.iter_mut().enumerate().take(k) {
let half_life = base_half_life * powi(params.garch_cascade_ratio, i);
let target = pow_half(half_life);
let beta_i = target - params.garch_alpha - params.garch_gamma / 2.0;
let beta_i = if beta_i < 0.0 { 0.0 } else { beta_i };
let pers_i = params.garch_alpha + beta_i + params.garch_gamma / 2.0;
let omega_i = sector_base_variance * (1.0 - pers_i);
let raw = omega_i + shock + beta_i * *slot;
*slot = mathx::max(
mathx::min(raw, sector_base_variance * params.garch_ceiling_multiple),
sector_base_variance * params.garch_floor_multiple,
);
total += *slot;
}
let cascade_variance = total / (k as f64);
let w = params.garch_cascade_weight;
let legacy = update_garch_variance_for(
params, garch_beta, previous_component_0, last_daily_return,
sector_base_variance);
(1.0 - w) * legacy + w * cascade_variance
}
fn pow_half(half_life: f64) -> f64 {
mathx::exp(mathx::log(0.5) / half_life)
}
fn powi(base: f64, n: usize) -> f64 {
let mut out = 1.0;
for _ in 0..n {
out *= base;
}
out
}
pub const GARCH_PERSISTENCE_CEILING: f64 = 0.97;
const PERSISTENCE_REFERENCE_CAP: f64 = 2.0e10;
const PERSISTENCE_CAP_SCALE: f64 = 3.0;
pub fn garch_beta_for(params: &crate::params::ModelParams, market_cap: f64) -> f64 {
let d = params.garch_beta_dispersion;
if d == 0.0 {
return params.garch_beta;
}
if market_cap <= 0.0 {
return params.garch_beta;
}
let z = mathx::clamp(
mathx::log(market_cap / PERSISTENCE_REFERENCE_CAP) / PERSISTENCE_CAP_SCALE,
-1.0,
1.0,
);
let beta = params.garch_beta + d * z;
let headroom =
GARCH_PERSISTENCE_CEILING - params.garch_alpha - 0.5 * params.garch_gamma;
mathx::max(0.0, mathx::min(beta, headroom))
}
pub fn update_garch_variance(
current_variance: f64,
last_daily_return: f64,
sector_base_variance: f64,
) -> f64 {
update_garch_variance_with(
&crate::params::PT_V1,
current_variance,
last_daily_return,
sector_base_variance,
)
}
pub fn update_garch_variance_with(
params: &crate::params::ModelParams,
current_variance: f64,
last_daily_return: f64,
sector_base_variance: f64,
) -> f64 {
update_garch_variance_for(
params,
params.garch_beta,
current_variance,
last_daily_return,
sector_base_variance,
)
}
pub fn update_garch_variance_for(
params: &crate::params::ModelParams,
garch_beta: f64,
current_variance: f64,
last_daily_return: f64,
sector_base_variance: f64,
) -> f64 {
let omega = if params.garch_omega_sector_scaled == 0.0 {
params.garch_omega
} else {
let persistence = params.garch_alpha + garch_beta + params.garch_gamma / 2.0;
let identity = sector_base_variance * mathx::max(0.0, 1.0 - persistence);
if params.garch_omega_sector_scaled == 1.0 {
identity
} else {
(1.0 - params.garch_omega_sector_scaled) * params.garch_omega
+ params.garch_omega_sector_scaled * identity
}
};
let mut new_var = omega
+ params.garch_alpha * last_daily_return * last_daily_return
+ garch_beta * current_variance;
if last_daily_return < 0.0 {
new_var += params.garch_gamma * last_daily_return * last_daily_return;
}
mathx::max(
mathx::min(new_var, sector_base_variance * params.garch_ceiling_multiple),
sector_base_variance * params.garch_floor_multiple,
)
}
#[cfg(test)]
mod tests {
use super::*;
use crate::params::ModelParams;
const BASE: f64 = 0.015 * 0.015;
#[test]
fn the_omega_scaling_is_bit_identical_at_zero() {
let base = ModelParams::pt_v16();
assert_eq!(base.garch_omega_sector_scaled, 0.0, "the dial must ship off");
for r in [-0.03_f64, -0.005, 0.0, 0.004, 0.02] {
for v in [BASE * 0.3, BASE, BASE * 2.0] {
let with = update_garch_variance_for(&base, base.garch_beta, v, r, BASE);
let mut off = ModelParams::pt_v16();
off.garch_omega_sector_scaled = 0.0;
let without = update_garch_variance_for(&off, off.garch_beta, v, r, BASE);
assert_eq!(with.to_bits(), without.to_bits());
}
}
}
#[test]
fn the_per_name_vix_response_is_the_square_at_two() {
let ship = ModelParams::pt_v19();
assert_eq!(ship.garch_vix_exponent, 2.0, "the dial must ship at the square");
let c = ship.garch_vix_coupling;
for r in [0.0_f64, 0.2, 0.9, 1.0, 1.5, 2.8, 5.2] {
let reference = BASE * (1.0 - c + vix_coupled_response(&ship, c, r));
let literal = BASE * (1.0 - c + c * r * r);
assert_eq!(reference.to_bits(), literal.to_bits(), "at ratio {r}");
}
}
#[test]
fn at_full_coupling_the_reference_is_the_power_law() {
let mut p = ModelParams::pt_v19();
p.garch_vix_coupling = 1.0;
p.garch_vix_exponent = 1.4176;
for k in [2.0_f64, 5.0, 13.0] {
let lo = 0.4;
let hi = vix_coupled_response(&p, 1.0, lo * k);
let ratio = hi / vix_coupled_response(&p, 1.0, lo);
assert!((ratio - mathx::pow(k, 1.4176)).abs() < 1e-9 * ratio, "{ratio}");
}
assert_eq!(vix_coupled_response(&p, 1.0, 1.0), 1.0);
}
#[test]
fn the_omega_scaling_puts_the_unconditional_level_on_the_sector_base() {
let mut p = ModelParams::pt_v16();
p.garch_omega_sector_scaled = 1.0;
p.garch_alpha = 0.0;
p.garch_gamma = 0.0;
p.garch_beta = 0.85;
for start in [BASE * 0.3, BASE * 4.0] {
let mut v = start;
for _ in 0..400 {
v = update_garch_variance_for(&p, p.garch_beta, v, 0.0, BASE);
}
assert!(
(v / BASE - 1.0).abs() < 1e-9,
"unconditional variance {v} is not the sector base {BASE} (from {start})"
);
}
}
#[test]
fn a_non_stationary_persistence_cannot_make_omega_negative() {
let mut p = ModelParams::pt_v16();
p.garch_omega_sector_scaled = 1.0;
p.garch_gamma = 0.55;
let persistence = p.garch_alpha + p.garch_beta + p.garch_gamma / 2.0;
assert!(persistence > 1.0, "this test needs a divergent persistence, got {persistence}");
let out = update_garch_variance_for(&p, p.garch_beta, BASE, 0.0, BASE);
assert!(out > 0.0, "variance went non-positive: {out}");
}
#[test]
fn the_cascade_blend_is_a_weighted_average_of_its_components() {
for k in [1_usize, 2, 3, 6, 8] {
for w in [0.0_f64, 0.25, 0.5, 0.75, 1.0] {
for ret in [0.03_f64, -0.03, 0.0, -0.005] {
let mut p = ModelParams::pt_v19();
p.garch_omega_sector_scaled = 1.0;
p.garch_cascade_components = k as f64;
p.garch_cascade_ratio = 3.0;
p.garch_cascade_weight = w;
let mut cascade = [BASE; CASCADE_MAX];
let h = update_garch_cascade(
&p, p.garch_beta, &mut cascade, ret, BASE);
let mut expected = 0.0;
for (i, v) in cascade.iter().take(k).enumerate() {
let wt = w / (k as f64)
+ if i == 0 { 1.0 - w } else { 0.0 };
expected += wt * v;
}
for v in cascade.iter().take(k) {
assert!(
*v > BASE * p.garch_floor_multiple * 1.000001
&& *v < BASE * p.garch_ceiling_multiple
* 0.999999,
"k={k} w={w} ret={ret}: component {v} is on a \
clamp, so this case cannot test the identity"
);
}
let err = (h - expected).abs() / expected;
assert!(
err < 1e-12,
"k={k} w={w} ret={ret}: blend {h} is not the tilted \
average {expected} of its components, off by \
{:.3}% of h. The legacy term is reading a cascade[0] \
that already carries today's shock; see the blend \
paragraph on update_garch_cascade.",
100.0 * err
);
if w == 1.0 {
let mut total = 0.0;
for v in cascade.iter().take(k) {
total += v;
}
assert_eq!(
h.to_bits(),
(total / (k as f64)).to_bits(),
"k={k} ret={ret}: at weight 1.0 the blend must be \
the component mean to the bit"
);
}
}
}
}
}
#[test]
fn the_widest_beta_a_preset_admits_has_a_finite_fourth_moment() {
const OVER: [(&str, f64); 2] = [
("pt-v1", 1.1390000000000002),
("pt-v2", 1.1108006659369685),
];
let caps = [0.0_f64, 1.0e6, 1.0e9, 2.0e10, 4.1e11, 1.0e14];
for name in ModelParams::preset_names() {
let p = ModelParams::preset(name).unwrap();
let (a, g) = (p.garch_alpha, p.garch_gamma);
let m4 = |b: f64| {
3.0 * a * a + 3.0 * a * g + 1.5 * g * g
+ 2.0 * a * b + b * g + b * b
};
let mut worst_beta = 0.0_f64;
let mut worst = 0.0_f64;
for cap in caps {
let b = garch_beta_for(&p, cap);
if m4(b) > worst {
worst = m4(b);
worst_beta = b;
}
}
if let Some((_, recorded)) = OVER.iter().find(|(n, _)| *n == *name) {
assert!(
(worst - recorded).abs() < 1e-12,
"{name} is on the known-over list at {recorded} and now \
reads {worst} (beta {worst_beta}). If the coefficients \
moved on purpose, update the list and say so; if this \
went DOWN through 1.0, take the preset off the list."
);
continue;
}
assert!(
worst < 1.0,
"{name}: garch_beta_for reaches beta {worst_beta} at some \
cap, whose fourth-moment coefficient is {worst} at \
kappa^2 = 1. GARCH_PERSISTENCE_CEILING is a first-moment \
guard and admits it. Redo the fourth-moment derivation and read \
the note on GARCH_PERSISTENCE_CEILING before widening \
garch_beta_dispersion further. Check the WIRED attenuation \
too: it is `idio_sigma_scale^2 * cap_mult^2 * \
volatility_multiplier^2 * intraday_variance_factor`, which \
is at most 0.729463 at pt-v19's idio_sigma_scale of 0.5126 \
but 1.9589 at pt-v1's 0.84, so a preset can clear this \
assertion and still be over the line where it runs."
);
}
let mut p = ModelParams::pt_v19();
let (a, g) = (p.garch_alpha, p.garch_gamma);
let m4 = |b: f64| {
3.0 * a * a + 3.0 * a * g + 1.5 * g * g + 2.0 * a * b + b * g
+ b * b
};
assert!(p.garch_beta_dispersion == 0.0, "pt-v19 must ship at 0.0");
assert!(m4(garch_beta_for(&p, 4.1e11)) < 1.0);
p.garch_beta_dispersion = 0.0284;
let widened = garch_beta_for(&p, 4.1e11);
assert!(
m4(widened) > 1.0,
"the sweep above cannot catch anything: a dispersion of 0.0284 \
reaches beta {widened}, which should be past the fourth-moment \
crossing at 0.8128347454829143"
);
}
#[test]
fn every_shipped_preset_has_a_stationary_variance_process() {
for name in ModelParams::preset_names() {
let p = ModelParams::preset(name).unwrap();
let persistence = p.garch_alpha + p.garch_beta + p.garch_gamma / 2.0;
let half_life = (0.5f64).ln() / persistence.ln();
assert!(
persistence < 1.0,
"{name}: persistence {persistence} at or above 1.0 — variance \
grows without bound"
);
assert!(
(0.75..1.0).contains(&persistence),
"{name}: persistence {persistence}, shock half-life \
{half_life:.1} days. Below 0.75 there is no volatility \
clustering left to speak of. If this moved on purpose, \
update the module note and §115."
);
}
}
#[test]
fn persistence_is_high_enough_for_crises_to_last() {
let persistence = ALPHA + BETA + GAMMA / 2.0;
assert!(
(0.98..1.0).contains(&persistence),
"persistence {persistence} — below 0.98 crises evaporate, at or above 1.0 the \
process is non-stationary and volatility runs away"
);
}
#[test]
fn a_down_day_raises_tomorrows_volatility_at_least_as_much_as_an_up_day() {
let up = update_garch_variance(BASE, 0.02, BASE);
let down = update_garch_variance(BASE, -0.02, BASE);
assert!(
down >= up,
"a −2% day must raise variance at least as much as a +2% day: {down} vs {up}"
);
if GAMMA > 0.0 {
assert!(
down > up,
"with GAMMA = {GAMMA} a −2% day must raise variance STRICTLY more \
than a +2% day: {down} vs {up}"
);
} else {
assert!(
down == up,
"at GAMMA = 0 the update must be exactly the symmetric reference: \
{down} vs {up}"
);
}
}
#[test]
fn a_large_return_raises_tomorrows_volatility() {
let calm = update_garch_variance(BASE, 0.001, BASE);
let shocked = update_garch_variance(BASE, 0.08, BASE);
assert!(
shocked > calm,
"an 8% day must raise variance above a 0.1% day: {shocked} vs {calm}"
);
}
#[test]
fn volatility_clusters_rather_than_resetting() {
let mut shocked = update_garch_variance(BASE, 0.08, BASE);
let quiet_after_shock = {
for _ in 0..5 {
shocked = update_garch_variance(shocked, 0.0, BASE);
}
shocked
};
let never_shocked = {
let mut v = BASE;
for _ in 0..6 {
v = update_garch_variance(v, 0.0, BASE);
}
v
};
assert!(
quiet_after_shock > never_shocked * 1.2,
"five days after an 8% move, variance must still be elevated: {quiet_after_shock} \
vs {never_shocked}"
);
}
#[test]
fn the_shock_does_eventually_decay() {
let mut v = update_garch_variance(BASE, 0.15, BASE);
for _ in 0..400 {
v = update_garch_variance(v, 0.0, BASE);
}
assert!(
v <= BASE * FLOOR_MULTIPLE * 1.000001,
"after 400 quiet days variance should have fallen to its floor, got {v}"
);
}
#[test]
fn variance_stays_inside_its_sector_bounds_however_hard_it_is_driven() {
let mut v = BASE;
for day in 0..1000 {
let ret = if day % 2 == 0 { 0.9 } else { 0.0 };
v = update_garch_variance(v, ret, BASE);
assert!(
v <= BASE * CEILING_MULTIPLE * 1.000001,
"day {day}: variance {v} escaped its {CEILING_MULTIPLE}x ceiling"
);
assert!(
v >= BASE * FLOOR_MULTIPLE * 0.999999,
"day {day}: variance {v} fell through its {FLOOR_MULTIPLE}x floor"
);
}
}
#[test]
fn a_higher_volatility_sector_carries_a_higher_floor_and_ceiling() {
let calm_sector = 0.008 * 0.008;
let wild_sector = 0.035 * 0.035;
let settle = |base: f64| {
let mut v = base;
for _ in 0..500 {
v = update_garch_variance(v, 0.0, base);
}
v
};
assert!(settle(wild_sector) > settle(calm_sector));
}
#[test]
fn the_bounds_are_applied_max_of_min_and_the_order_shows() {
assert_eq!(update_garch_variance(0.01, 0.5, 0.0), 0.0);
for v in [0.0, 0.001, 1.0] {
assert_eq!(update_garch_variance(v, 0.0, 0.0), 0.0);
}
}
}