# HUYLE / STQD v2 — VLAAI EEG encoder, one-seed AAD experiment

This is a **complete standalone code directory** for the classifier experiment at:

```
/root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/experiments/huyle/v2
```

It was adapted from the previously supplied `huyle` v1 code and the archived `decoder_lodo` source. **The original reconstruction decoder, its trained LODO evidence and external AASD/Carta evidence are reused unchanged.** The new classifier folds, checkpoint files, pretraining, external classifier evidence, and result summaries are saved **only under this v2 directory**. It does not write to the old `decoder_lodo`, `v1`, or external-data directories.

## 1. What changed relative to v1?

Only the EEG backbone changes in the scientific architecture comparison:

| Stage | STQD v1 | STQD v2 |
|---|---|---|
| EEG input | `[B, 320, 58]` | `[B, 320, 58]` |
| EEG feature extractor | `1x1 Conv + 3 TemporalBlocks` | **`VLAAIwsBackbone` (3 repeated, weight-shared blocks, kernels 3/7/11, context kernel 17)** |
| Fine EEG features | `[B,320,64]` | `[B,320,64]` |
| Token reduction | average pool by 4 | **unchanged** |
| EEG memory | `[B,80,64]` | `[B,80,64]` |
| Speech processing | separate env/onset/dom stems + temporal conv | **unchanged** |
| Speech tokens | `[B,2,80,64]` | **unchanged** |
| Interaction | temporal speech-to-EEG cross-attention | **unchanged** |
| Readout | token 72 / shared scoring head | **unchanged** |
| Output | `[B]` signed logit, speaker-0 positive | **unchanged** |

The EEG backbone is copied from the original `vlaai_ws_model.py` (not reimplemented approximately). Importantly, it takes **only the 58 EEG channels** and returns learned temporal features; it is not the original early-fusion classifier's 64-channel concatenated-input network. Its 3 shared blocks have LayerNorm over 320 chronological positions and a fixed ten-second input window.

Training loss, synthetic `sw2` augmentation, speaker swap behavior, speech feature per-window normalization, readout, early stopping, and downstream evidence/HMM are left as in v1. **We did not silently change `dom` normalization** or other speech inputs: that is a separate hypothesis requiring its own ablation.

The one engineering change is activation-memory **microbatching**: sample the original effective 64-window batch, split into forward/backward chunks of 16, accumulate their appropriately weighted gradients, then do one AdamW step. This substantially reduces peak activation memory while preserving the same effective batch loss (up to floating-point/BatchNorm effects; the VLAAI backbone uses LayerNorm, the other branches use GroupNorm). Evaluation is also chunked. Different GPU numerical effects may remain.

## 2. Default experiment matrix

**Exactly one classifier seed: 0.** Two variants are run by default:

- `v2_full`: VLAAI EEG backbone + original v1 speech stems + time-biased cross-attention + shared target-token scoring.
- `v2_cosine`: same EEG and speech encoders, but replaces the cross-attention interaction with cosine matching (v1's strongest comparator).

One optional extra ablation is provided but **not run by default**:

- `v2_no_time_bias`: same as `v2_full`, but removes the fixed Gaussian relative-time bias.

Default per variant: SparrKULee match-mismatch pretraining (max 80 epochs, minimum 25), 5 × LODO training (max 40 epochs, minimum 10; train on other 4 + Fuglsang), synthetic-switch scoring, fusion with **four already-trained reconstruction decoder seeds**, all-five training from the new classifier pretrain, and AASD/Carta real-switch evaluation and fusion. Decoder branches are **not retrained** unless explicitly requested.

Pretraining and every held-out fold use the same classifier seed 0, and only a single all-five classifier is trained per variant. **The final fusion is 4 decoder seeds + 1 classifier seed**, so its performance is not a matched 4+4 comparison with the historical best baseline. Its primary purpose is measuring whether this new *single classifier* gives a useful direction before a costly seed ensemble.

## 3. Files and locations

```
experiments/
  decoder_lodo/            # existing caches and unchanged decoder evidence/models
  external_data/           # existing Fuglsang, SparrKULee, AASD, Carta caches
  v1/                      # optional old code/results; not read by v2
  huyle/
    v2/
      run_v2.sh            # ONLY recommended launcher; tee captures all output to v2.log
      run_all.py           # sequential resume-aware orchestration
      stqd_model.py        # STQD + VLAAIwsBackbone EEG encoder
      vlaai_ws_model.py    # original weight-shared VLAAI implementation
      direct_classifier.py # LODO training, pretraining, inference, shortcut controls
      eval_external_clf.py # all-5 classifier + real switches
      fuse_general.py      # LODO fusion with decoder evidence
      fuse_external.py     # AASD/Carta fusion
      common_exp.py        # data & shared cache paths
      config.yaml, ...     # source-compatible support modules
      tests/
      models/              # only new v2 models
      folds/               # only new v2 classifier folds
      results/             # new v2 JSON/CSV and real-switch evidence
      v2.log               # the ONE combined run log (created by launcher)
```

No v1 files, model weights, data, or credentials are included in the ZIP.

## 4. Installation

Extract the package ZIP from the `experiments/` folder so the resulting files end up in `experiments/huyle/v2/` (the ZIP already contains `huyle/v2/...`). You do **not** need to copy anything into the existing `decoder_lodo` directory.

Confirm that the parent repository virtualenv exists at `../../../.venv/bin/python` relative to `v2/`. The environment already used for `decoder_lodo` should have the necessary packages. Package versions, environment data readers, third-party scoring scripts and original cached data must remain available.

```bash
cd /root/disk_3tb/EEG-sAAD-Grand-Challenge-Training-Dataset/experiments/huyle/v2

# Local smoke tests (quick, CPU-compatible); these are not performance results
../../../.venv/bin/python -m unittest discover -s tests -v

# Verify the generated commands and missing-input diagnostics WITHOUT training
bash run_v2.sh --dry-run

# Full experiment: full model + one cosine ablation, classifier seed 0
bash run_v2.sh
```

**All console output from the launcher and its child training/scoring processes is appended to `v2.log`.** No separate training `.log` files are created by the v2 training code; JSON, CSV, checkpoint and fold artifacts remain separate machine-readable outputs. `bash run_v2.sh` uses `set -o pipefail` to propagate runtime errors through the tee logger.

To monitor training:

```bash
tail -n 120 -f v2.log
```

## 5. Optional commands

```bash
# Add no-time-bias as a second ablation (the earlier two variants will be skipped if complete)
bash run_v2.sh --variants v2_full,v2_cosine,v2_no_time_bias

# Only train the primary proposed architecture (fastest)
bash run_v2.sh --variants v2_full

# Skip the AASD/Carta phase for a faster initial LODO-only run
bash run_v2.sh --skip-external

# Re-run only the missing external evaluations after LODO has completed
bash run_v2.sh --skip-lodo

# Lower peak GPU memory further (effective batch remains 64)
bash run_v2.sh --microbatch 8

# Allow recreating missing unchanged reconstruction external evidence;
# this costs time and is NOT the default, and still uses no eval labels for fitting.
bash run_v2.sh --allow-rebuild-decoder-external

# Skip all pretraining (different experiment: identifiers marked _scratch)
bash run_v2.sh --pretrain-mode none
```

**Resume caution:** If training hyperparameters or architecture change, use `--run-tag _mynewtag` or a new v2 directory. Do not mix previously cached evidence from different configurations. Restarting with exactly the same parameters skips completed pretraining checkpoints, LODO folds, and completed external-evidence files.

## 6. Expected outputs

Default names, for each variant (`v2_full`, `v2_cosine`):

```
models/pretrain_spk_direct_clf_<variant>_s0.pt
models/all5_direct_clf_<variant>_s0.pt
folds/direct_clf__eaP_n5_t60_<variant>_s0/AVGC.pkl
folds/direct_clf__eaP_n5_t60_<variant>_s0/DTU.pkl
folds/direct_clf__eaP_n5_t60_<variant>_s0/KUL.pkl
folds/direct_clf__eaP_n5_t60_<variant>_s0/UHD.pkl
folds/direct_clf__eaP_n5_t60_<variant>_s0/USTC.pkl
results/direct_clf__eaP_n5_t60_<variant>_s0.json
results/research/ext_clf_AASD_<variant>_evidence_s0.pkl
results/research/ext_clf_Carta2026_<variant>_evidence_s0.pkl
results/research/fuse_general.csv
results/research/fuse_external.csv
results/v2_classifier_summary.csv
results/v2_lodo_fusion_summary.csv
results/v2_real_switch_summary.csv
v2.log
```

`fuse_external.csv` includes a source-calibrated grid of `p_stay` and fusion weights. Reporting a **best** AASD/Carta setting selected from this grid is only a diagnostic, not an independent held-out-test score. In particular, `a=0.0` means *decoder only*; it cannot establish that adding the classifier helped.

## 7. Reading outcomes and known scientific limitations

- The v1 report found approximately `H=0.536` for `stqd_full` versus ~`0.588` for `stqd_cosine` over two classifier seeds. These are **synthetic-switch LODO classifier-only** results, not the competition's fused `H≈0.8003` result. A classifier result near 0.5 does not *by itself* distinguish optimization underfitting, overfitting, shortcut learning or miscalibration. Training and validation BCE/accuracy should be read from `v2.log`.
- The historical four-classifier/four-decoder score is not a fair direct comparison to our one-classifier/four-decoder fusion. Compare classifier-only metrics with a **baseline classifier using the same seed** and report the ensemble-size difference transparently.
- Neither architectural feature separation nor VLAAI guarantees a domain-generalization gain; future LODO experiments must still use source-only hyperparameter selection.
- Full-trial EA, acoustic normalization, synthetic-switch scoring and all-five evaluation are as in v1. The user requested **no complete temporal leakage audit in this development run**; model timing is inherited from the 320-sample window and its original target index, but this is not proof of challenge-compliant deployment.
- `SIGKILL (-9)` in the report has no demonstrated root cause (OOM and server limits are possibilities). Microbatching reduces GPU activation pressure but does not eliminate host RAM or timeout risks.
- The original reconstruction branch is deliberately unchanged. It cannot independently establish that a new classifier improved when fusion weight `a=0`.

## 8. Local validation performed before packaging

- Python syntax compilation of all copied/modified modules.
- Four `unittest` checks for the end-to-end classifier interface, the three v2 variants, tensor shapes, speaker swap anti-symmetry, differentiability and error on invalid input length.
- Dry-run command generation for both default variants, including pretraining, fold training, source fusion and real-switch evidence.

**Actual GPU training, five-dataset LODO performance, and real-switch results are not supplied or claimed in this ZIP.** Those require the user's original datasets, external evaluation caches and reconstruction checkpoints on the server.
