2cf9927647
Replaces half = max(10*q_gap, 3*std_ema, floor) tuned constants with quantile-based: half = max(|q_p95 - v_center|, |v_center - q_p5|) clamped to [min_half_floor, abs_half]. Covers observed Q distribution directly. New GPU kernel q_quantile_reduce reads per-sample Q-values from q_out_buf, sorts per branch (bitonic for power-of-2 N, quickselect otherwise), writes ISV[Q_P05_*=47..51) and ISV[Q_P95_*=51..55). Cold-path per-epoch (4 blocks, 1 thread each). No atomicAdd. ISV slots 47-54 added at tail (8 total). Fingerprint shifted to 55-56. ISV_TOTAL_DIM grows 49 -> 57. Fingerprint seed updated; recomputes hash at compile time (new value: 0xbf6c400c026d77e3). Launch order: reduce_current_q_stats (populates q_out_buf) -> q_quantile_reduce (writes ISV P5/P95) -> reduce_current_q_stats_per_branch -> update_eval_v_range (reads ISV P5/P95 for half-width). Bootstrap: q_p05 = v_min, q_p95 = v_max (matches current atom range at cold start). FoldReset: isv_q_quantiles dispatch arm resets to bootstrap values at fold boundary. StateResetRegistry: isv_q_quantiles as FoldReset; dispatch arm added in training_loop.rs::reset_named_state. Docs: isv-slots.md rows [47..57) updated, fingerprint tail reference corrected to [55..57). dqn-wire-up-audit.md: q_quantile_kernel.cu added. Plan 2 Task 1. Spec §4.C.1. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
7.2 KiB
7.2 KiB
ISV Slot Allocation Registry
Source of truth for ISV bus slot allocations. Every slot has a named constant in gpu_dqn_trainer.rs. This doc is the cross-reference.
Design: layout fingerprint, not schema version. ISV[37..39) carries a compile-time structural hash of the slot layout. Checkpoint load is fail-fast; no migration functions exist. Backward compat is structurally unwritable (there is no ordered version space to pair migrations against). See spec §4.A.2.
Tail placement rationale: The fingerprint occupies the tail ([55..57)) rather
than the head because isv_signals[0] and isv_signals[1] are actively written
by isv_signal_update (Q-drift EMA and gradient-norm EMA respectively). Inserting
at the head would displace those live signals and require shifting every upstream
literal in experience_kernels.cu. The fingerprint moves to the new tail each time
new slots are appended to the bus.
Current ISV_TOTAL_DIM: 57 (Plan 1 + Plan 2 Task 1 C.1 quantile slots). Post-full DQN v2 rollout: 72.
| Index | Name constant | Type | Producer | Consumers | Reset-category | Notes |
|---|---|---|---|---|---|---|
| [0] | SLOT_0_Q_DRIFT (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | isv_signals[0] = (q_mean − q_ema) / max( |
| [1] | SLOT_1_GRAD_NORM_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | EMA of sqrt(grad_norm²) |
| [2] | SLOT_2_TD_ERR_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | EMA of TD-error scalar |
| [3] | SLOT_3_ENS_VAR_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | C51 Q-distribution variance EMA (batch-mean atom-spread) |
| [4] | SLOT_4_ENS_VAR_VEL (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | Delta of slot 3 (variance velocity) |
| [5] | SLOT_5_REWARD_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | EMA of per-batch mean reward |
| [6] | SLOT_6_ATOM_UTIL_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | EMA of atom utilization fraction |
| [7] | SLOT_7_LOSS_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | EMA of total training loss |
| [8] | SLOT_8_ADX_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | Batch-mean ADX EMA (regime velocity indicator) |
| [9] | SLOT_9_REGIME_DISAGREE (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | |
| [10] | SLOT_10_REGIME_VEL_EMA (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | EMA of regime transition velocity (ADX + CUSUM delta) |
| [11] | SLOT_11_REGIME_STABILITY (seed only) |
f32 | isv_signal_update | ISV encoder | FoldReset | 1 − sigmoid(5 × regime_vel); high = stable regime |
| [12] | LEARNING_HEALTH_INDEX |
f32 | isv_signal_update | many | FoldReset | health score ∈ [0, 1] |
| [13..17) | Q_MAG_MEAN_*_INDEX |
f32 | q_mag_means_reduce | c51 kernels | FoldReset | Quarter/Half/Full mag Q-mean EMAs + |Q| ref |
| [17..22) | Q_DIR_MEAN_*_INDEX |
f32 | q_dir_means_reduce | c51 kernels | FoldReset | Short/Hold/Long/Flat dir Q-mean EMAs + |Q| ref |
| [22] | SHARPE_EMA_INDEX |
f32 | training_loop host | isv_signal_update | FoldReset | Training Sharpe EMA |
| [23..31) | V_{CENTER,HALF}_{DIR,MAG,ORD,URG}_INDEX |
f32 | update_eval_v_range | adaptive_atoms, warm_start | FoldReset | Per-branch Q-support |
| [31..35) | GRAD_NORM_TARGET_*_INDEX |
f32 | grad_balance_isv_update | branch_grad_rescale | SoftReset(decay_bars=500) | Per-branch grad-norm target |
| [35] | GRAD_SCALE_LIMIT_INDEX |
f32 | grad_balance_isv_update | branch_grad_rescale | SoftReset(decay_bars=500) | Scale clamp limit |
| [36] | IQL_BRANCH_SCALE_FLOOR_INDEX |
f32 | construct (static) | iql_per_branch_advantage | SchemaContract | Per-sample branch_scales floor; safety bound |
| [37..39) | (gap — fingerprint moved to tail) | — | — | — | — | Previously [37..39); fingerprint promoted to [47..49) by Plan 1 C.6 expansion. Slots unused; zero-filled. |
| [39] | EPOCH_IDX_INDEX |
f32 (int cast) | CPU epoch-loop (follow-up task) | GPU adaptive kernels | FoldReset | Current epoch index; 0 at construction, CPU writes at each epoch boundary |
| [40] | TOTAL_EPOCHS_INDEX |
f32 (int cast) | construct (CPU static) | GPU adaptive kernels | SchemaContract | Total epoch count for this run; written at construction from config.total_epochs |
| [41] | EPSILON_EFF_INDEX |
f32 | GPU epsilon-adaptive kernel (follow-up) | epsilon-greedy action select | FoldReset | Effective epsilon; 0 at construction; GPU fills each step |
| [42] | TAU_EFF_INDEX |
f32 | GPU tau-adaptive kernel (follow-up) | target-net Polyak update | FoldReset | Effective tau; 0 at construction; GPU fills each step |
| [43] | GAMMA_EFF_INDEX |
f32 | GPU gamma-adaptive kernel (follow-up) | Bellman target kernel | FoldReset | Effective gamma; 0 at construction; GPU fills each step |
| [44] | KELLY_CAP_EFF_INDEX |
f32 | GPU kelly-cap-adaptive kernel (follow-up) | experience_env_step | FoldReset | Effective Kelly cap; 0 at construction; GPU fills each step |
| [45] | CQL_ALPHA_INDEX |
f32 | construct (CPU static) | CQL adaptive formula in Rust | SchemaContract | CQL pessimism base coefficient; written from config.cql_alpha; read in compute_cql_logit_gradients |
| [46] | PLAN_THRESHOLD_INDEX |
f32 | construct (CPU static) | experience_kernels.cu, backtest_plan_kernel.cu |
SchemaContract | Plan-MLP activation threshold; 0.5f at construction; read via ISV_PLAN_THRESHOLD_IDX in both kernels |
| [47] | Q_P05_DIR_INDEX |
f32 | q_quantile_reduce GPU kernel (cold-path per-epoch) | update_eval_v_range | FoldReset | Direction-branch 5th-percentile Q EMA. Bootstrap: v_min. |
| [48] | Q_P05_MAG_INDEX |
f32 | q_quantile_reduce | update_eval_v_range | FoldReset | Magnitude-branch 5th-percentile Q EMA. Bootstrap: v_min. |
| [49] | Q_P05_ORD_INDEX |
f32 | q_quantile_reduce | update_eval_v_range | FoldReset | Order-branch 5th-percentile Q EMA. Bootstrap: v_min. |
| [50] | Q_P05_URG_INDEX |
f32 | q_quantile_reduce | update_eval_v_range | FoldReset | Urgency-branch 5th-percentile Q EMA. Bootstrap: v_min. |
| [51] | Q_P95_DIR_INDEX |
f32 | q_quantile_reduce GPU kernel (cold-path per-epoch) | update_eval_v_range | FoldReset | Direction-branch 95th-percentile Q EMA. Bootstrap: v_max. |
| [52] | Q_P95_MAG_INDEX |
f32 | q_quantile_reduce | update_eval_v_range | FoldReset | Magnitude-branch 95th-percentile Q EMA. Bootstrap: v_max. |
| [53] | Q_P95_ORD_INDEX |
f32 | q_quantile_reduce | update_eval_v_range | FoldReset | Order-branch 95th-percentile Q EMA. Bootstrap: v_max. |
| [54] | Q_P95_URG_INDEX |
f32 | q_quantile_reduce | update_eval_v_range | FoldReset | Urgency-branch 95th-percentile Q EMA. Bootstrap: v_max. |
| [55] | ISV_LAYOUT_FINGERPRINT_LO_INDEX |
u32 bits (in f32) | construct | check_layout_fingerprint | SchemaContract | Low 32 bits of u64 FNV-1a structural hash. Fail-fast on mismatch — NOT a version number, no migration path. |
| [56] | ISV_LAYOUT_FINGERPRINT_HI_INDEX |
u32 bits (in f32) | construct | check_layout_fingerprint | SchemaContract | High 32 bits of u64 FNV-1a structural hash. |
| [57..72) | (reserved for DQN v2) | Allocated incrementally by Plans 2-5 |