README.md

# generator_v2 — SARIMA-compositional + chaotic + long-memory cascade generator

A cascade data generator that keeps the strong **SARIMA-compositional** backbone
of `new_generator` and adds the two classes of dynamics that backbone
structurally cannot produce, plus a bilinear nonlinear-AR family. It is a
genuine *capability* upgrade — new mechanisms, not just re-weighted knobs.

## What's inside

| file | purpose |
|------|---------|
| `generator.py` | `class Generator(DataGenerator)` — the entrypoint |
| `config.json` | length band, SARIMA caps, **core-family weights**, enrichment probs |
| `requirements.txt` | hash-locked, allowlisted deps (`numpy`, `scipy`) |

## Core families (selected per series by `core_weights`)

1. **SARIMA-compositional** *(dominant, best single scorer)* — regime-switching
   `SARIMA(p,d,q)(P,D,Q)_s` with stochastic volatility, fat tails, integration.
2. **Chaotic dynamical systems** *(new)* — continuous chaotic flows integrated
   by RK4 (Lorenz, Rössler, Thomas, Chen, driven Van der Pol) plus the
   Mackey-Glass delay system. Motivated by **DynaMix (NeurIPS'25)**: a TSFM
   trained purely on a small library of chaotic attractors generalises zero-shot
   to real traffic/weather. These give deterministic-but-complex, broadband,
   long-range structure no ARMA prior contains.
3. **Long-memory / fractional** *(new)* — (i) power-law `1/f^β` colored-noise
   spectral synthesis (β∈[-1,3]: anti-persistent → pink → Brownian), and
   (ii) **ARFIMA(p,d,0)** via truncated fractional-differencing (Hosking)
   coefficients. Fills the gap between SARIMA's I(0) and I(1) with genuine
   long-range dependence (Hurst ≠ 0.5).
4. **Bilinear nonlinear-AR** *(new)* — `y_t = φ y_{t-1} + b y_{t-1} e_{t-1} +
   θ e_{t-1} + e_t`: bursty multiplicative autocorrelation distinct from
   SETAR/GARCH.

Every core then flows through the **same** enrichment stack as before —
additive nested-calendar seasonality, trends, level shifts, spikes, nonlinear
marginal warps, TSMixup and finalisation — so the new dynamics inherit the full
compositional breadth.

## Performance & stability

- The chaotic cores use a **bounded scalar recursion** capped at
  `chaos_max_steps` (default 1200) integration steps and then resample to the
  target length, so cost stays linear and small even at length 4096.
- Any core that diverges or returns non-finite falls back **deterministically**
  to the SARIMA core; the final series is rescaled and hard-clipped to
  `max_abs_value`.
- SARIMA AR/MA roots are guaranteed outside the unit circle (Levinson-Durbin on
  reflection coefficients); ARFIMA uses `d < 0.5` for stationarity.

## Determinism

The corpus is a pure function of `(seed, n_series)` via
`np.random.SeedSequence` sub-seeds. The chaotic/bilinear scalar recursions are
ordinary deterministic float arithmetic. No `hash()`, wall-clock, or unseeded
global RNG.

## Verify

```bash
# from the cascade repo root, with deps installed and cascade importable
cascade verify ../generator_v2
```

## Config knobs (`config.json`)

- `min_length` / `max_length` — per-series length band.
- `core_weights` — probability mass over `sarima` / `chaotic` / `longmem` /
  `bilinear` cores. SARIMA is kept dominant (strongest single scorer).
- `chaos_min_steps` / `chaos_max_steps` — chaotic integration-step budget
  (bounds cost; trajectories are resampled to the series length).
- `max_ar` / `max_ma` / `max_seasonal_ar` / `max_seasonal_ma` — SARIMA caps.
- `d_weights` / `seasonal_d_weights` — integration-order probability mass.
- `seasonal_prob` / `student_t_prob` / `stoch_vol_prob` — SARIMA innovations.
- `regime_prob` / `max_regimes` — regime-switching frequency and count.
- `trend_prob` / `calendar_prob` / `level_shift_prob` / `spike_prob` — components.
- `warp_prob` / `mixup_prob` — nonlinear marginal warp / TSMixup probabilities.
- `standardize` — z-normalise each series (default `false`).
- `max_abs_value` — hard magnitude clip to keep output trainer-safe finite.