58 lines
2.6 KiB
Markdown
58 lines
2.6 KiB
Markdown
# Design & Decision Log
|
||
|
||
## 2026-01-26 — Two-stage temporal backbone (GRU) + residual diffusion
|
||
- **Decision**: Add a stage-1 GRU trend model, then train diffusion on residuals.
|
||
- **Why**: Separate temporal consistency from distribution alignment.
|
||
- **Files**:
|
||
- `example/hybrid_diffusion.py` (added `TemporalGRUGenerator`)
|
||
- `example/train.py` (two-stage training + residual diffusion)
|
||
- `example/sample.py`, `example/export_samples.py` (trend + residual synthesis)
|
||
- `example/config.json` (temporal hyperparameters)
|
||
- **Expected effect**: improve lag-1 consistency; may hurt KS if residual distribution drifts.
|
||
|
||
## 2026-01-26 — Residual distribution alignment losses
|
||
- **Decision**: Apply distribution losses to residuals (not raw x0).
|
||
- **Why**: Diffusion models residuals; alignment should match residual distribution.
|
||
- **Files**:
|
||
- `example/train.py` (quantile loss on residuals)
|
||
- `example/config.json` (quantile weight)
|
||
|
||
## 2026-01-26 — SNR-weighted loss + residual stats
|
||
- **Decision**: Add SNR-weighted loss and residual mean/std regularization.
|
||
- **Why**: Stabilize diffusion training and improve KS.
|
||
- **Files**:
|
||
- `example/train.py`
|
||
- `example/config.json`
|
||
|
||
## 2026-01-26 — Switchable backbone (GRU vs Transformer)
|
||
- **Decision**: Make the diffusion backbone configurable (`backbone_type`) with a Transformer encoder option.
|
||
- **Why**: Test whether self‑attention reduces temporal vs distribution competition without altering the two‑stage design.
|
||
- **Files**:
|
||
- `example/hybrid_diffusion.py`
|
||
- `example/train.py`
|
||
- `example/sample.py`
|
||
- `example/export_samples.py`
|
||
- `example/config.json`
|
||
|
||
## 2026-01-26 — Per-feature KS diagnostics
|
||
- **Decision**: Add a per-feature KS/CDF diagnostic script to pinpoint KS failures (tails, boundary pile-up, shifts).
|
||
- **Why**: Avoid blind reweighting and find the specific features causing KS to stay high.
|
||
- **Files**:
|
||
- `example/diagnose_ks.py`
|
||
|
||
## 2026-01-26 — Quantile transform + sigmoid bounds for continuous features
|
||
- **Decision**: Add optional quantile normalization (TabDDPM-style) and sigmoid-based bounds to reduce KS spikes.
|
||
- **Why**: KS failures are dominated by boundary pile-up and tail mismatch.
|
||
- **Files**:
|
||
- `example/data_utils.py`
|
||
- `example/prepare_data.py`
|
||
- `example/export_samples.py`
|
||
- `example/config.json`
|
||
|
||
## 2026-01-27 — Quantile transform without extra standardization
|
||
- **Decision**: When quantile transform is enabled, skip mean/std normalization (quantile output already ~N(0,1)).
|
||
- **Why**: Prevent scale mismatch that pushed values to max bounds and blew up KS.
|
||
- **Files**:
|
||
- `example/data_utils.py`
|
||
- `example/export_samples.py`
|