# Suite35 — PACE

Version1.1.1 fixes startup on raw transcript `NHHK=0`/invalid semesters: unusable supplemental records are excluded and audited, while canonical enrollment validation stays strict. No cache rebuild is required. See `docs/SEMESTER_ZERO_FIX.md`.

Suite35 studies whether self-supervised learning from earlier academic histories improves course-failure prediction. It includes DeepSets/MLP, GRU and causal Transformer encoders; grade, course and joint reconstruction tasks; matched tree/neural controls; chronological selection and fresh refits; frozen F1–F5 development and F6–F7 retrospective evaluation; detailed results and interpretation.

## Run on your actual AQ data

Extract this package into your existing project, then run:

```bash
cd /root/disk_3tb/earlywarning/30072026/suite35_pace
./run_suite35.sh
```

**No numeric-grade export, calendar file, column mapping or configuration editing is required.** With no arguments, the script runs the complete study on your existing AQ inputs. It automatically uses `/root/miniconda3/envs/Huy/bin/python3` when present, otherwise `python3`; `AQ_PYTHON` can select a different installed environment.

Python 3.10+ and the packages in `requirements.txt` are required. Use your existing CUDA-enabled PyTorch on the AQ server. If dependencies are missing, install them into that same environment. Device and library versions are printed; HGB runs on CPU, while neural training uses CUDA when available.

The default locations are:

| Purpose | Automatic location |
| --- | --- |
| AQ project | `/root/disk_3tb/earlywarning/30072026` |
| Canonical caches | `results/cross_faculty_residual_moe/cache/{faculty}_fold_{fold}.joblib` |
| Structured sidecars | `results/suite12_structured_cache/{faculty}_fold_{fold}.joblib` |
| Full numeric transcript | `../database/**/DDTBHP.csv`, then known `raw_index/course_history.joblib` locations |
| Split fallback | `data/splits/expanding` under the project or its parent directories |
| Consolidated log | `/root/disk_3tb/earlywarning/30072026/log/suite35_pace.log` |
| Results and checkpoints | `/root/disk_3tb/earlywarning/30072026/results/suite35_pace` |

Relative paths in the table are relative to the AQ project. Canonical caches take precedence over split CSVs. Existing caches and database files are read without modification. Sidecars are reused when present; missing course metadata is reconstructed from the available static fields and strictly earlier course outcomes. When no full transcript source is available, historical numeric `train_frame.target_grade10` values are used automatically.

A different project location needs only a path override:

```bash
./run_suite35.sh --root /path/to/your/AQ/project
```

Optional audit without training:

```bash
./run_suite35.sh --audit-only
```

The default launcher resumes automatically: rerunning the same command validates source/data/configuration fingerprints, completed artifact hashes and checkpoint predictions before reusing work. Changed data or modeling code requires a different output directory. Run one process per output directory.

## What was corrected in this revision

The input integration follows the previous implementations you supplied, particularly Suites17,25,26,32 and33. `train_frame` and `test_frame` provide `IDSV`, `IDMH`, `target_NHHK`, registration identity and numeric `target_grade10`; canonical `Xtr/Xte/ytr/yte` remain aligned to those frames. `course_target` is the **17 numeric course features**, not a course-ID vector. Structured training positions must match `cf_covered_mask & finite(cf_probabilities)`; valid permutations are honored. Existing sidecar values remain intact.

The common raw features are intersected across the requested faculty/fold snapshots, then the 17 known course fields are appended. Every fold retains its own engineered-feature snapshot. On the standard inputs this is expected to recover the established 136+17 fields; the discovered names and counts are printed instead of assuming a count that might hide a mismatch.

Full labeled historical support is the default, following the full-history direction in Suite26. Older covered-only support remains available through `--history-support covered` in a separate output directory. The audit prints full, CF-covered and reconstructed row counts. All Suite35 arms within a run use the same rows, including students without history. An upstream training row is retained even when its numeric historical grade is missing; that missing grade is never fabricated from its binary failure label.

`DDTBHP` grades use `DiemHP`, then `DiemHPCalc` if missing. Canonical `target_IDCongDiem` enables exact reconciliation. Missing IDs use checked one-to-one matching; unresolved ambiguity or conflicting outcomes fail explicitly. Registration rows remain in supervised data, while repeated grade records are counted once in histories. Target identities can join **earlier** transcript events; their current outcomes cannot enter their prediction histories.

AQ semester codes use `year*3+term-1`, with terms 1,2,3. Native mode inherits the previous suites' assumption that an observed earlier-semester grade is available by the next semester. **It does not certify publication dates or historical grade revisions.** The generated timestamp values are internal ordinal comparison carriers, never observed calendar dates. Logs show semester codes. No external calendar is needed. Upstream engineered-feature construction remains inherited from the earlier caches.

## Research matrix

| Arm | Model/input | Purpose |
| --- | --- | --- |
| H0 | Engineered features → HGB | Same-run tree baseline |
| H1 | Features + deterministic history summaries → HGB | Extra history without SSL |
| N0 | Features → MLP | Neural baseline |
| N1 | Features + supervised history encoder → MLP | Encoder without SSL |
| N2 | Features + frozen SSL encoder → MLP | Frozen transfer |
| N3 | Features + fine-tuned SSL encoder → MLP | Adaptation |
| H2 | Features + frozen SSL embedding → HGB | Primary practical transfer test |
| HR | Features + frozen random embedding → HGB | Random-representation control |
| HS, optional | HGB + independently pretrained shuffled-semester encoder | Chronology placebo |

All three encoders share an event frontend and permutation-invariant within-semester aggregation. DeepSets/MLP is invariant to semester order; GRU and the causal Transformer receive elapsed-semester information. Parameter counts and budgets are printed; exact parameter equivalence is not claimed. SSL tasks are grade-only, course-only and joint, with masking that removes the corresponding numeric hints.

The full defaults are three seeds 29/129/229; all discovered faculties; folds 1–7; three encoders; three SSL tasks; eight primary arms. This produces 36 model variants × faculties ×7 folds ×3 seeds (10,584 downstream cells for 14 faculties). Cutoff-matched SSL work is shared across arms and faculties. Source matrices load one cohort at a time. Repeated student/semester prefixes stay in a unique tensor bank with a compact row map. Frozen/evaluation encoders process each prefix once; trainable encoders expand only minibatches to retain enrollment weighting. Padding follows observed support within the 16-semester/32-course caps, and only masked tokens are sent to the SSL output heads.

For a separate small pilot, overrides are available without editing JSON:

```bash
./run_suite35.sh development --seeds 29 --encoders gru --tasks joint \
  --arms H0,H1,H2,HR --output-dir /root/disk_3tb/earlywarning/30072026/results/suite35_pilot
```

A pilot has its own freeze and must not use F6/F7 to choose the full study. Optional complete ablations use `--ssl-scope local` or `--chronology-placebo` with a separate output directory. See `python3 -m pace aq-run --help` for all overrides.

## Chronology and freezing

For target semester t, the latest usable earlier semester v is inner validation. Selection labels precede v; final-refit labels precede t. Each enrollment's history ends strictly before its own semester. SSL epoch selection uses student-heldout reconstruction before v, followed by a fresh full-support pre-v fit. Final SSL is independently initialized and fitted before t for the selected budget. Supervised models select on v and refit from scratch before t. Future events cannot enter vocabulary fitting, SSL, course-statistic reconstruction or enrollment prefixes.

F1–F5 determine the promoted architecture/task and per-arm F1/F2 thresholds. F6–F7 apply that freeze unchanged. Later expanding folds can train on earlier fold outcomes once the inherited availability rule admits them. These are retrospective folds already used in previous AQ research.

Separate-stage commands are also supported:

```bash
./run_suite35.sh development
./run_suite35.sh retrospective
```

## Logs, detailed evidence and insights

The master log includes source discovery and alignment, support counts, grade distributions, runtime/device, cohort cutoffs, epoch/selection metrics, pretext diagnostics and frequency baselines, every downstream cell result and replay status, complete metric tables, paired contrasts and interpretation. Repeated identical SSL reuse messages are summarized. Full phase-specific reports remain saved; the combined tables print once.

Saved outputs include:

- `aq_source_audit.json`, `aq_source_fingerprints.json`, resolved configuration, runtime, immutable run identity and protocol freeze.
- SSL checkpoints, vocabularies, epoch curves, grade-band recall, frequency/history strata and reconstruction baselines.
- Per-cell downstream checkpoints, epoch curves, target probabilities, metrics and artifact hashes.
- Full faculty/fold/seed and macro tables; AP/AUC/Brier/ECE15; frozen F1/F2 policies and confusion matrices; exact5/10/20% alert budgets.
- Matched H2-versus-H0/H1/HR contrasts, neural/task/architecture contrasts, descriptive faculty-fold bootstrap intervals, wins/harms, history/OOV/no-history subgroups and support audits.
- `report.md` and `report.txt` in `reports`, `development_reports` and `retrospective_reports`, with an evidence-based continuation decision.
- Automatically bundled historical Committee/prior-suite AP comparisons, matched by faculty/fold, with population-count differences explicit. Historical metric-only deltas never enter promotion or row-paired bootstrap evidence.

Seeds are averaged within each faculty/fold before equal-weight macro aggregation. AP is checked against saved probabilities. Promotion requires H2 development AP gain≥.01 over **each** H0/H1/HR and wins against the strongest control in≥60% of paired cells, with complete estimable support. Reconstruction gains alone do not justify continuation. Reports discuss where history, SSL, architecture or fine-tuning helps or harms; no performance gain is assumed.

## Verification and explicit synthetic runs

```bash
python3 -m unittest discover -s tests -v
python3 -m pace demo --directory demo_data --full
./run_suite35.sh demo_data/demo.json all
```

The JSON command above explicitly trains on synthetic demo data. **The no-argument command trains on actual AQ data.** The package also includes fixtures matching the actual canonical/sidecar/DDTBHP schemas; verification evidence identifies synthetic execution separately from research results. Your server's actual cache bytes, full AQ scores and CUDA execution cannot be verified in this local environment.

`configs/aq.json` is an optional native-mode configuration with the same known paths. Advanced normalized-input adapters remain for portability; their mapping examples are unrelated to the default AQ launch. Scientific details are in `docs/DESIGN.md`, `docs/METHODOLOGY.md` and `docs/AQ_NATIVE_REVISION.md`. Historical result provenance is documented in `reference/README.md`.
