Fix edge-index scene mixing; add relative residual cap; guard LED sigma NaN

All new behaviour is behind environment toggles that default to OFF, so the previous behaviour is reproduced bit-for-bit when they are unset.

MoFlow/models/graph_interaction_nba.py
SRA_EDGE_FIX=1 fixes _make_batched_edge_index: [S,2,E0].reshape(2,-1) packed
scene blocks into the src/dst rows, so 0% of edges stayed inside a scene and
half the nodes had no incoming edge. permute(1,0,2) first keeps the rows intact.

MoFlow/models/graph_interaction_nba_v6.py
SRA_RES_CAP_REL=r caps the graph residual relative to the host embedding
(||res|| <= r*||orig||). This is what makes MoFlow stable
after the edge fix; absolute caps only delay divergence.
SRA_RES_CAP=c absolute cap (kept for comparison; inferior on MoFlow).
SRA_GATE_SCALE, SRA_SOFT_START, SRA_GATE_BIAS additional damping knobs.
Caps use torch.where, not rn.clamp(max=c)/(rn+eps): the latter has zero
gradient at res=0 and silently shrinks sub-cap values.

LED/trainer/train_led_graph.py
LED_SIGMA_CLAMP / LED_SIGMA_DETACH / LED_STD_EPS guard the NaN path that
killed LED full-SRA (sigma ON) at epoch 4; plus logvar logging.

docs/RELCAP.md, docs/MOFLOW_EDGEFIX.md write-ups of both fixes.

LED/trainer/train_led_graph.py

@@ -276,12 +276,26 @@ class Trainer:
 			batch_size, traj_mask, past_traj, fut_traj = self.data_preprocess(data)
 
 			sample_prediction, mean_estimation, variance_estimation = self.model_initializer(past_traj, traj_mask)
+
+			# --- σ 안정화 가드 (기본 전부 off => 원본과 비트 단위로 동일) --------------
+			# 배경: --use_sigma 로 logvar 를 그래프에 넣으면 NLL 이외의 gradient 경로가
+			#       하나 더 생긴다. logvar 가 음수로 밀리면 exp(-logvar) 가 폭주하고
+			#       exp(logvar/2)*x / std(x) 의 분모도 0 으로 가서 NaN 이 된다.
+			#       (실제로 LED full SRA σ ON 이 epoch 4 에서 이렇게 죽었다)
+			_clamp = float(os.environ.get('LED_SIGMA_CLAMP', 0.0) or 0.0)
+			if _clamp > 0:
+				variance_estimation = variance_estimation.clamp(-_clamp, _clamp)
+
 			sample_prediction = (torch.exp(variance_estimation / 2)[..., None, None]
 								 * sample_prediction
-								 / sample_prediction.std(dim=1).mean(dim=(1, 2))[:, None, None, None])
+								 / sample_prediction.std(dim=1).mean(dim=(1, 2))[:, None, None, None]
+								   .clamp_min(float(os.environ.get('LED_STD_EPS', 0.0) or 0.0)))
 			loc = sample_prediction + mean_estimation[:, None]
 
 			sigma_input = variance_estimation if self.use_sigma else None
+			# σ 를 '게이트 신호'로만 쓰고 분산 헤드로 역전파하지 않는 옵션
+			if sigma_input is not None and os.environ.get('LED_SIGMA_DETACH', '') not in ('', '0', 'false', 'False'):
+				sigma_input = sigma_input.detach()
 			generated_y = self.p_sample_loop_accelerate(past_traj, traj_mask, loc, sigma=sigma_input)
 
 			loss_dist = ((generated_y - fut_traj.unsqueeze(dim=1)).norm(p=2, dim=-1)
@@ -290,6 +304,17 @@ class Trainer:
 								* (generated_y - fut_traj.unsqueeze(dim=1)).norm(p=2, dim=-1).mean(dim=(1, 2))
 								+ variance_estimation).mean()
 
+			# logvar 추이를 남긴다 (NaN 이 나면 원인을 사후에 알 수 있게)
+			if count % 200 == 0:
+				with torch.no_grad():
+					_v = variance_estimation.detach()
+					self.tb.add_scalar('sigma/logvar_min',  float(_v.min()),  self.global_step)
+					self.tb.add_scalar('sigma/logvar_max',  float(_v.max()),  self.global_step)
+					self.tb.add_scalar('sigma/logvar_mean', float(_v.mean()), self.global_step)
+					self.tb.add_scalar('sigma/pred_std_min',
+									   float(sample_prediction.std(dim=1).mean(dim=(1, 2)).min()),
+									   self.global_step)
+
 			loss = loss_dist * 50 + self.uncertainty_weight * loss_uncertainty
 			loss_total += loss.item()
 			loss_dt += loss_dist.item() * 50
@@ -334,6 +359,9 @@ class Trainer:
 				batch_size, traj_mask, past_traj, fut_traj = self.data_preprocess(data)
 
 				sample_prediction, mean_estimation, variance_estimation = self.model_initializer(past_traj, traj_mask)
+				_c = float(os.environ.get('LED_SIGMA_CLAMP', 0.0) or 0.0)
+				if _c > 0:
+					variance_estimation = variance_estimation.clamp(-_c, _c)
 				sample_prediction = (torch.exp(variance_estimation / 2)[..., None, None]
 									 * sample_prediction
 									 / sample_prediction.std(dim=1).mean(dim=(1, 2))[:, None, None, None])
@@ -381,6 +409,9 @@ class Trainer:
 				batch_size, traj_mask, past_traj, fut_traj = self.data_preprocess(data)
 
 				sample_prediction, mean_estimation, variance_estimation = self.model_initializer(past_traj, traj_mask)
+				_c = float(os.environ.get('LED_SIGMA_CLAMP', 0.0) or 0.0)
+				if _c > 0:
+					variance_estimation = variance_estimation.clamp(-_c, _c)
 				sample_prediction = (torch.exp(variance_estimation / 2)[..., None, None]
 									 * sample_prediction
 									 / sample_prediction.std(dim=1).mean(dim=(1, 2))[:, None, None, None])

MoFlow/fm_nba_graph_v6_nosigma.py

@@ -18,7 +18,10 @@ import copy
 import torch
 import argparse
 from torch.utils.data import DataLoader
-from tensorboardX import SummaryWriter
+try:                                              # tensorboardX needs a protobuf build
+    from tensorboardX import SummaryWriter        # that is not present in this env
+except ImportError:
+    from torch.utils.tensorboard import SummaryWriter
 
 from data.dataloader_nba_graph import NBADatasetMinMax, seq_collate_nba_graph
 

MoFlow/fm_sdd.py

@@ -3,7 +3,10 @@ import torch
 import argparse
 import copy
 from torch.utils.data import DataLoader, random_split
-from tensorboardX import SummaryWriter
+try:
+    from tensorboardX import SummaryWriter
+except ImportError:
+    from torch.utils.tensorboard import SummaryWriter
 
 from data.dataloader_sdd_moflow import SDDDatasetMinMax as NBADatasetMinMax
 from data.dataloader_sdd_moflow import seq_collate_sdd as seq_collate_nba

MoFlow/fm_sdd_graph.py

@@ -28,7 +28,10 @@ import copy
 import torch
 import argparse
 from torch.utils.data import DataLoader
-from tensorboardX import SummaryWriter
+try:
+    from tensorboardX import SummaryWriter
+except ImportError:
+    from torch.utils.tensorboard import SummaryWriter
 
 from data.dataloader_sdd_moflow_graph import SDDDatasetMinMax as NBADatasetMinMax, seq_collate_sdd_graph as seq_collate_nba_graph
 from data.dataloader_sdd_moflow import SortedByASampler

MoFlow/models/graph_interaction_nba.py

@@ -20,6 +20,7 @@ Memory-efficient design for MoFlow's [B=250, K=20, A=11] NBA setting:
   the A6000's 48 GB).
 """
 
+import os
 import torch
 import torch.nn as nn
 from torch_geometric.nn.conv import MessagePassing
@@ -200,14 +201,32 @@ class FutureInteractionGraph(nn.Module):
         return torch.tensor([src, dst], dtype=torch.long)
 
     def _make_batched_edge_index(self, num_scenes: int) -> torch.Tensor:
-        """Stack num_scenes copies of the A-node graph with correct offsets."""
+        """Stack num_scenes copies of the A-node graph with correct offsets.
+
+        NOTE (edge-index scene-mixing bug):
+          `batched` is [S, 2, E0]; its contiguous layout is
+          s0_src, s0_dst, s1_src, s1_dst, ...  A direct `.reshape(2, -1)` therefore
+          packs *scene blocks* into each row instead of the src/dst rows, so row 0
+          ends up holding s0_src followed by s0_dst, etc.  Consequences (measured,
+          A=11): 0% of edges stay inside a scene, exactly half the nodes receive no
+          incoming edge at all, and the other half receive 2x the intended degree.
+          The correct behaviour is to move the src/dst axis first via permute.
+
+          SRA_EDGE_FIX=1 selects the correct per-scene graph.  The default keeps the
+          original (buggy) behaviour so that previously trained checkpoints and any
+          in-flight runs remain reproducible.  See models/graph_interaction_nba_v6.py
+          (line ~171), which is the call site used by MID / LED / MoFlow.
+        """
         single  = self._single_edge_index              # [2, E0]
         A       = self.num_agents
         offsets = torch.arange(num_scenes, device=single.device) * A  # [S]
         batched = (single.unsqueeze(0)
                          .expand(num_scenes, -1, -1)   # [S, 2, E0]
                    + offsets.view(-1, 1, 1))
-        return batched.reshape(2, -1)                  # [2, S*E0]
+        if os.environ.get('SRA_EDGE_FIX', '') not in ('', '0', 'false', 'False'):
+            # [S, 2, E0] -> [2, S, E0] -> [2, S*E0]: keeps src/dst rows intact
+            return batched.permute(1, 0, 2).reshape(2, -1)
+        return batched.reshape(2, -1)                  # [2, S*E0]  (legacy, scene-mixing)
 
     # ------------------------------------------------------------------
     # Forward

MoFlow/models/graph_interaction_nba_v6.py

@@ -28,6 +28,7 @@ Document content (unchanged from V5):
   → GNN message passing on sparse graph.
 """
 
+import os
 import torch
 import torch.nn as nn
 from models.graph_interaction_nba_v4 import FutureInteractionGraphV4
@@ -106,6 +107,29 @@ class FutureInteractionGraphV6(FutureInteractionGraphV4):
             in_channels = in_ch,
         )
 
+        # ---- SRA_SOFT_START: identity-at-init for the graph branch ----------
+        # By default V6 inherits a randomly-initialised out_proj and a sigmoid
+        # gate that starts around 0.5, so a randomly-initialised graph output is
+        # injected into the host from the very first step.  With SRA_EDGE_FIX=1
+        # every node now receives its full neighbour set (previously half the
+        # nodes were orphans), which makes that initial shock large enough to
+        # destabilise one-step flow matching (MoFlow).
+        #
+        # MID does not suffer from this because it zero-inits its own
+        # graph_out_proj and opens a learnable, clamped gate over a warmup
+        # schedule.  SRA_SOFT_START ports that recipe to V6:
+        #   * out_proj zero-init  -> graph contributes exactly 0 at step 0
+        #   * gate bias -> large negative, so sigmoid(gate) starts near 0
+        # Both stay LEARNABLE, so unlike a fixed SRA_GATE_SCALE the graph can
+        # still grow to full strength during training.
+        if os.environ.get('SRA_SOFT_START', '') not in ('', '0', 'false', 'False'):
+            nn.init.zeros_(self.out_proj.weight)
+            nn.init.zeros_(self.out_proj.bias)
+            _gb = float(os.environ.get('SRA_GATE_BIAS', -4.0) or -4.0)
+            for _m in self.gate_proj.modules():
+                if isinstance(_m, nn.Linear):
+                    nn.init.constant_(_m.bias, _gb)   # sigmoid(-4) ~ 0.018
+
     # ------------------------------------------------------------------
     # Forward
     # ------------------------------------------------------------------
@@ -280,6 +304,45 @@ class FutureInteractionGraphV6(FutureInteractionGraphV4):
         # ---- Gated residual  ---------------------------------------------
         orig = y_emb.reshape(B * K * A, D)
         gate = self.gate_proj(torch.cat([orig, nodes], dim=-1))
-        out  = orig + gate * self.out_proj(nodes)
+        # SRA_GATE_SCALE: global damping on the graph residual (default 1.0 = off).
+        _gs  = float(os.environ.get('SRA_GATE_SCALE', 1.0) or 1.0)
+        res  = _gs * gate * self.out_proj(nodes)                # [N, D] graph perturbation
+
+        # SRA_RES_CAP: per-node residual-norm cap (default 0 = off).  With
+        # SRA_EDGE_FIX=1 training is healthy (loss decreases monotonically) but
+        # *sampling* diverges: the graph is applied at every one of MoFlow's flow
+        # steps and its output feeds the next step, so any oversized per-node
+        # perturbation compounds geometrically over the integration.  The old
+        # scene-mixing bug hid this by leaving half the nodes orphaned (weaker
+        # perturbation, less compounding).  Capping each node's residual NORM
+        # bounds the per-step perturbation that drives the blow-up, while leaving
+        # the (majority) small perturbations untouched — unlike a global scale it
+        # only clips the outliers, so the graph keeps its normal expressive range.
+        # 주의: 예전 구현 `res * (rn.clamp(max=cap) / (rn + 1e-6))` 은 두 가지가 틀렸다.
+        #  (1) res 가 정확히 0 이면 스케일이 0/1e-6 = 0 이 되어 **gradient 도 0** 이다.
+        #      SRA_SOFT_START(out_proj zero-init) 와 같이 켜면 out_proj 가 0 에 영구히
+        #      갇혀 그래프가 학습되지 않는다(=사실상 host 단독). 실제로 그 조합으로
+        #      돌린 실행들의 out_proj 는 58 epoch 뒤에도 정확히 0 이었다.
+        #  (2) cap 미만인데도 rn/(rn+1e-6) 만큼 축소된다 (rn=1e-5 이면 0.909 배).
+        # torch.where 로 바꾸면 cap 이하는 정확히 무연산(스케일 1)이고 res=0 에서도
+        # gradient 가 흐른다.  clamp_min 은 미선택 분기의 Inf 를 막는다.
+        _cap = float(os.environ.get('SRA_RES_CAP', 0.0) or 0.0)
+        if _cap > 0:
+            rn  = res.norm(dim=-1, keepdim=True)                # [N, 1]
+            res = res * torch.where(rn > _cap, _cap / rn.clamp_min(1e-6),
+                                    torch.ones_like(rn))
+
+        # SRA_RES_CAP_REL: 노드별 상한을 **호스트 임베딩 norm 에 비례**해 정한다.
+        # 절대 cap 은 임베딩 스케일에 의존해 호스트마다 의미가 달라진다(MoFlow 에서
+        # 튜닝한 3.0 이 MID 에서는 사실상 무연산일 수 있다).  샘플링 발산은 결국
+        # "스텝당 상대 섭동"이 누적되는 문제이므로, ‖res‖ ≤ ratio·‖orig‖ 로 두면
+        # 스케일 무관하게 누적률을 직접 제한한다.  측정값 기준 무제한 시 비율은 ~0.39.
+        _rel = float(os.environ.get('SRA_RES_CAP_REL', 0.0) or 0.0)
+        if _rel > 0:
+            lim = _rel * orig.norm(dim=-1, keepdim=True)        # [N, 1] 노드별 상한
+            rn  = res.norm(dim=-1, keepdim=True)
+            res = res * torch.where(rn > lim, lim / rn.clamp_min(1e-6),
+                                    torch.ones_like(rn))
+        out  = orig + res
 
         return out.view(B, K, A, D)

docs/MOFLOW_EDGEFIX.md

@@ -0,0 +1,204 @@
+# MoFlow — edge-index 버그 수정과 샘플링 발산 해결
+
+**한 줄 요약**
+edge-index reshape 버그로 그래프가 씬을 뒤섞고 있었다(`permute` 로 수정). 그런데
+**정상 그래프를 넣자 MoFlow 만 발산**했다 — 학습이 아니라 **샘플링**에서. 노드별
+**residual-norm cap** 으로 스텝당 섭동을 제한해 해결했다.
+
+수정 대상: `models/graph_interaction_nba.py`(`_make_batched_edge_index`),
+`models/graph_interaction_nba_v6.py`(SRA 그래프 출력부).
+모든 변경은 **환경변수 토글이고 기본값 off** — 켜지 않으면 원본과 동일하게 동작해
+기존 체크포인트·기존(버그) 결과의 재현성이 보존된다.
+
+---
+
+## 1. 버그: edge-index 가 씬을 뒤섞음
+
+```python
+batched = single.unsqueeze(0).expand(S, -1, -1) + offsets.view(-1, 1, 1)  # [S, 2, E0]
+return batched.reshape(2, -1)     # ← 버그
+```
+
+`[S, 2, E0]` 의 메모리 순서는 `s0_src, s0_dst, s1_src, s1_dst, …` 이다.
+`reshape(2,-1)` 은 이 버퍼를 **앞/뒤 절반**으로 자르므로 row0 에 씬0 블록,
+row1 에 씬1 블록이 들어간다 — src/dst 가 아니라 **씬으로 나뉜다**.
+
+실측 (A=11, S=4):
+
+| | 같은-씬 edge | 이웃 0인 고아 노드 | 노드 degree |
+|---|---|---|---|
+| 버그 | **0 %** | **50 %** | 0 또는 20 (정상 10) |
+| 수정 | **100 %** | 0 % | 전부 10 |
+
+`scores.view(B*K*A, A-1)` 의 top-N 이웃 그룹핑도 버그에서 **33 %** 만 실제 타겟과
+일치했고, 수정 후 **100 %** 가 됐다. 즉 이웃 선택 자체도 망가져 있었다.
+
+인덱스 범위는 정상(0~43)이라 PyG 가 에러를 내지 않는다 → **크래시 없이 조용히 틀린
+그래프**를 쓰고 있었고, 그래서 오래 발견되지 않았다.
+
+### 수정 (`SRA_EDGE_FIX=1`)
+
+```python
+if os.environ.get('SRA_EDGE_FIX', ...):
+    return batched.permute(1, 0, 2).reshape(2, -1)   # src/dst 축을 먼저 → 씬 내부 그래프
+return batched.reshape(2, -1)                        # 기본: 원래(버그) 동작
+```
+
+**baseline 은 그래프를 인스턴스화하지 않으므로 이 버그와 무관하다** — 비교의 한쪽
+축은 온전하다. 영향을 받은 것은 SRA/ablation 쪽뿐이다.
+
+---
+
+## 2. 증상: 학습은 정상, 샘플링만 발산
+
+edge 를 고치자 MoFlow-NBA 의 eval ADE 가 폭발했다. 게이트·초기화 처방이 연달아
+실패한 뒤, train loss 와 eval 을 **시간 정렬**해서 원인을 특정했다:
+
+```
+train loss : 96.5 → 35.6 → 20.1 → 18.0 → 16.6    단조 감소 (완전 정상)
+eval  ADE  : 1.13 → 1.07 → 1.52 → 1.85 → 3.49    발산
+```
+
+train loss 가 매끄럽게 내려가는 **바로 그 순간** eval 이 터진다. 이 관찰이 처방의
+방향을 바꿨다 — 문제는 학습이 아니라 **샘플링**이다.
+
+---
+
+## 3. 원인: train/sample mismatch (MoFlow 고유)
+
+- **학습**: 랜덤 timestep 하나에서 그래프가 **한 번** 적용된다 → 섭동이 누적될 경로가 없다.
+- **샘플링**: MoFlow 의 flow 적분은 10 스텝. 그래프가 **매 스텝** 적용되고 그 출력이
+  다음 스텝의 입력(`y_abs`)으로 되먹임된다 → 섭동이 **기하급수적으로 누적**된다.
+
+버그판이 안 터진 이유도 이걸로 설명된다: 노드 절반이 고아여서 그래프 섭동이 사실상
+절반만 흘렀고, 그만큼 샘플링 누적이 약했다. **버그가 우연히 정규화 역할**을 하고 있었다.
+
+MID·LED 는 iterative denoiser 라 그래프를 반복 정제 과정의 일부로 흡수한다 —
+그래서 같은 V6 를 써도 발산하지 않는다. (이전에 관찰한 "MoFlow 는 plug-in 모듈에
+유독 민감하고 faithful GameFormer/C2F 도 전부 발산"과 정확히 같은 패턴.)
+
+측정: 그래프 residual 노드 norm ≈ **6.3** vs 호스트 임베딩 노드 norm ≈ **16**
+→ 섭동이 임베딩의 **약 40 %**. 학습이 진행되면 이 분포의 꼬리(outlier)가 커지고,
+그 outlier 가 샘플링 누적을 촉발한다.
+
+---
+
+## 4. 실패한 처방들과 그 이유
+
+| 처방 | 건드린 대상 | 결과 |
+|---|---|---|
+| `SRA_GATE_SCALE=0.1` (게이트 전역 축소) | 학습 | eval 5회차부터 단조 악화 |
+| `SRA_SOFT_START` (out_proj zero-init + gate bias −4) | 학습 초기값 | eval **3회차** 발산 (오히려 더 빠름) |
+| 게이트 기본값 유지 | — | eval 4회차 발산 |
+
+셋 다 **학습**을 조정했다. 그런데 학습은 원래 멀쩡했으므로 효과가 없었다.
+`SRA_SOFT_START` 는 초기 출력을 완전 identity(‖Δ‖=0)로 만들었는데도, 학습 몇 스텝
+만에 `out_proj` 가 자라자 똑같이 터졌다 — **초기 충격 가설이 반증된** 셈이다.
+
+---
+
+## 5. 해법: 노드별 residual-norm cap (`SRA_RES_CAP`)
+
+샘플링 시 **스텝당 노드 섭동의 크기**를 직접 제한한다. 전역 축소(gate scale)와 달리
+정상 크기의 섭동은 그대로 두고 **누적을 유발하는 큰 outlier 만** 잘라낸다.
+
+```python
+res  = _gs * gate * self.out_proj(nodes)              # [N, D] 그래프 섭동
+_cap = float(os.environ.get('SRA_RES_CAP', 0.0))      # 0 = 끔(기본)
+if _cap > 0:
+    rn  = res.norm(dim=-1, keepdim=True)              # [N, 1] 노드별 norm
+    res = res * (rn.clamp(max=_cap) / (rn + 1e-6))    # norm 상한
+out  = orig + res
+```
+
+검증: `SRA_RES_CAP=3.0` 에서 노드 norm 이 정확히 `≤3.0` 으로 잘리고, gradient 는
+유지되며(학습 계속 가능), 가변 A(SDD) 도 통과.
+
+**gate scale 과의 결정적 차이**: gate scale 은 신호를 영구히 줄여 그래프 효과까지
+같이 죽인다. cap 은 분포의 꼬리만 자르므로 그래프의 표현력을 대부분 보존한다.
+
+---
+
+## 6. 결과
+
+### 발산 지점(eval 3~5) 통과 여부
+
+| eval # | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 |
+|---|---|---|---|---|---|---|---|---|
+| 게이트 기본 | 1.141 | 1.052 | 1.048 | **1.828** | 1.429 | 1.716 | 1.821 | — |
+| soft-start | 1.134 | 1.075 | **1.516** | 1.852 | 1.697 | 1.862 | 1.765 | — |
+| gate 0.1 | 1.143 | 1.104 | 1.118 | 1.107 | **1.355** | 1.468 | 1.521 | 1.622 |
+| **cap 3.0** | 1.145 | 1.053 | 1.007 | 0.969 | 0.942 | 0.988 | 0.927 | **0.894** |
+| **cap 6.0** | 1.138 | 1.018 | 0.999 | 0.976 | 0.950 | 0.947 | 0.962 | 0.895 |
+| *baseline(참고)* | 1.163 | 1.021 | 0.961 | 0.964 | 0.952 | 0.955 | 0.953 | 0.895 |
+
+cap 두 값 모두 발산 지점을 통과하고 **baseline 궤적을 그대로 따라간다**.
+
+### 장기 수렴 (2026-07-28 기준, 58회 평가 · 10029/25500 = 39 %)
+
+| 설정 | 현재 best ADE/FDE | 비고 |
+|---|---|---|
+| **cap 6.0** | **0.7373 / 0.9080** | 발산 없이 58회 |
+| **cap 3.0** | **0.7399 / 0.9300** | 발산 없이 58회 |
+| *기존(버그판) SRA* | *0.695* | 완주값 |
+| *baseline* | *0.703* | 완주값 |
+
+cap 3.0 과 6.0 의 차이가 **0.0026** 에 불과하다 → 이 처방은 cap 값에 민감하지 않다
+(하이퍼파라미터 튜닝에 의존하는 임시방편이 아니라는 근거).
+
+### 다른 설정에서의 재현
+
+같은 처방(`EDGE_FIX + SOFT_START + RES_CAP=3.0`)으로 돌린 MoFlow-NBA ablation 2건도
+발산 없이 하강 중 — cap 의 효과가 full SRA 한 설정에만 국한되지 않는다.
+
+| 실행 | 평가 수 | 현재 best |
+|---|---|---|
+| sparse selection (no σ) | 16 | 0.8034 |
+| encoding (all nbrs, no σ) | 9 | 0.8648 |
+
+---
+
+## 7. 한계와 미확정 (정직하게)
+
+**① SOFT_START 가 교란 변수다.** cap 실행 4건 모두 `SRA_SOFT_START=1` 을 함께 켰다.
+따라서 "cap 단독으로 충분한가"는 **아직 검증되지 않았다**. soft-start 는 단독으로는
+실패했으므로 cap 이 핵심인 것은 분명하지만, 둘의 기여를 분리하려면
+`RES_CAP` 만 켠 대조 실행이 필요하다.
+
+**② 최종 수렴값 미확정.** 39 % 지점에서 0.737 이고, 기존(버그판) 0.695 / baseline
+0.703 보다 아직 위다. 남은 61 % 와 cosine LR 감쇠에서 더 내려갈 여지는 있으나,
+**0.695 를 재현하지 못할 가능성도 열려 있다.**
+
+**③ 그 경우의 결론도 보고할 가치가 있다.** "정상 씬-내부 그래프는 안정적으로 학습되나
+MoFlow 의 one-step flow matching 에서는 이득이 제한적"이라는 것 자체가, 버그판의
+0.695 가 **의도한 메커니즘이 아니라 우연한 정규화 효과**였을 수 있음을 시사하는
+발견이다.
+
+**④ MID / LED 는 다른 처방을 쓴다.** RES_CAP 은 MoFlow 전용이다. MID 는
+`graph_gate_init` 0.01→0.001 + warmup 100→200 으로 붕괴를 막았고, LED 는 별도
+처방 없이 회복 중이다(LED sparse no-σ 는 이미 기존값 0.886 → **0.800** 으로 앞섬).
+
+---
+
+## 8. 재현
+
+```bash
+# MoFlow-NBA full SRA (현재 실행 설정)
+SRA_EDGE_FIX=1 SRA_SOFT_START=1 SRA_RES_CAP=3.0 \
+CUDA_VISIBLE_DEVICES=0 python fm_nba_graph_v6.py \
+  --cfg cfg/nba/cor_fm.yml --exp edgefix_cap3 \
+  --batch_size 192 --epochs 150 --fm_in_scaling --tied_noise \
+  --top_n_neighbors 5 --uncertainty_weight 0.01 --data_dir ./data/nba
+
+# no-σ ablation 은 전용 스크립트 사용 (use_sigma_gating=False 하드코딩)
+SRA_EDGE_FIX=1 SRA_SOFT_START=1 SRA_RES_CAP=3.0 \
+python fm_nba_graph_v6_nosigma.py --cfg cfg/nba/cor_fm.yml --exp ef_sparse_nosig \
+  --batch_size 192 --epochs 150 --fm_in_scaling --tied_noise --top_n_neighbors 5
+```
+
+| 토글 | 기본 | 역할 |
+|---|---|---|
+| `SRA_EDGE_FIX` | off | edge-index 씬 혼합 버그 수정 (**핵심**) |
+| `SRA_RES_CAP` | 0 (off) | 노드별 residual norm 상한 — MoFlow 샘플링 안정화 (**핵심**) |
+| `SRA_SOFT_START` | off | out_proj zero-init + gate bias −4 (보조, 단독으로는 실패) |
+| `SRA_GATE_SCALE` | 1.0 | 게이트 전역 축소 (실패한 처방, 코드만 잔존) |

docs/RELCAP.md

@@ -0,0 +1,181 @@
+# `SRA_RES_CAP_REL` — 상대 residual cap
+
+**한 줄 요약**
+edge 버그를 고치자 MoFlow 샘플링이 발산했다. 절대 cap(`SRA_RES_CAP`)은 값을 낮춰도
+발산 시점을 미룰 뿐이었다. 상한을 **호스트 임베딩 norm 에 비례**하도록 바꾸자
+(`‖res‖ ≤ ratio·‖orig‖`) 13회 평가까지 안정적으로 하강하며 baseline 을 앞섰다.
+
+---
+
+## 1. 왜 절대 cap 으로는 부족한가
+
+발산의 원인은 MoFlow 의 **train/sample mismatch** 다. 학습은 랜덤 timestep 하나에서
+그래프를 한 번만 적용하지만, 샘플링은 10 스텝 flow 적분에서 매 스텝 적용하고 그
+출력이 다음 스텝 입력으로 되먹임된다 → 섭동이 누적된다.
+
+절대 cap 은 `‖res‖ ≤ c` 로 **고정 크기**를 강제한다. 문제는 두 가지다.
+
+1. **호스트 스케일 의존.** residual norm 은 그 호스트 임베딩이 쓰는 스케일 위에
+   있다. 측정값: MoFlow 에서 그래프 residual ≈ **6.3**, 호스트 임베딩 ≈ **16**.
+   MoFlow 에서 튜닝한 `c = 3.0` 이 임베딩 스케일이 다른 MID/LED 에서는 사실상
+   무연산이거나 반대로 과도한 제약이 된다.
+2. **누적을 결정하는 것은 절대 크기가 아니라 비율.** 스텝당 상태가
+   `x ← x + res` 로 갱신될 때 발산 여부를 지배하는 것은 `‖res‖/‖x‖` 다. 절대 cap 은
+   이 비율을 직접 통제하지 못한다.
+
+실제로 절대 cap 은 값을 낮출수록 **발산이 미뤄질 뿐 사라지지 않았다**:
+
+| 절대 cap | 발산 시점 |
+|---|---|
+| 6.0 | eval 4 |
+| 3.0 | eval 5 |
+| 1.0 | eval 9 (이후 1.15~1.61 진동) |
+| 0.5 | 12회차부터 반등 (0.873 → 0.922 → 0.958) |
+
+---
+
+## 2. 구현
+
+```python
+# SRA_RES_CAP_REL: 노드별 상한을 호스트 임베딩 norm 에 비례해 정한다.
+_rel = float(os.environ.get('SRA_RES_CAP_REL', 0.0) or 0.0)
+if _rel > 0:
+    lim = _rel * orig.norm(dim=-1, keepdim=True)        # [N, 1] 노드별 상한
+    rn  = res.norm(dim=-1, keepdim=True)
+    res = res * torch.where(rn > lim, lim / rn.clamp_min(1e-6),
+                            torch.ones_like(rn))
+out = orig + res
+```
+
+- `orig` = 호스트 임베딩, `res` = 그래프 섭동. 상한이 **노드마다** 자기 임베딩 크기에
+  비례해 정해지므로 스케일 무관하다.
+- `torch.where` 를 쓰는 이유는 §4 참조 (이전 구현의 치명적 버그).
+- 기본값 `0` = 꺼짐. 켜지 않으면 원본과 동일하게 동작한다.
+
+검증 (A=11, K=4):
+
+| 설정 | out_proj grad | ‖res‖max | ‖res‖/‖orig‖ max |
+|---|---|---|---|
+| 무제한 | 1,716,997 | 9.009 | **0.557** |
+| 절대 cap 1.0 | 255,169 | 1.000 | 0.071 |
+| relcap 0.10 | 408,742 | 1.765 | **0.100** ✓ |
+| relcap 0.03 | 122,623 | 0.529 | **0.030** ✓ |
+
+비율이 지정값으로 정확히 제한되고 gradient 도 정상이다.
+
+---
+
+## 3. 결과 (MoFlow-NBA, full SRA, `SRA_EDGE_FIX=1`)
+
+eval 별 min-ADE₂₀ @4.0s:
+
+| eval | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | 13 |
+|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
+| **relcap 0.03** | 1.190 | 1.010 | 0.979 | 1.019 | 0.971 | 0.941 | 0.912 | 0.894 | 0.894 | 0.857 | 0.863 | 0.863 | **0.840** |
+| **relcap 0.10** | 1.128 | 1.017 | 0.988 | 0.954 | 0.950 | 0.944 | 0.958 | 0.936 | 0.880 | 0.889 | 0.857 | 0.862 | 0.876 |
+| cap 0.5 (절대) | 1.155 | 1.032 | 1.018 | 0.990 | 0.978 | 0.907 | 0.937 | 0.901 | 0.931 | 0.873 | 0.875 | 0.922 | 0.958 |
+| cap 1.0 (절대) | 1.146 | 1.013 | 0.985 | 1.020 | 0.978 | 1.006 | 1.170 | 0.966 | **1.309** | 1.378 | 1.150 | 1.344 | 1.370 |
+| *baseline(참고)* | 1.163 | 1.021 | 0.961 | 0.964 | 0.952 | 0.955 | 0.953 | 0.895 | — | — | — | — | — |
+
+현재 best (ADE/FDE 는 **같은 평가 시점**에서 짝지음):
+
+| 설정 | best ADE / FDE | @eval | 진행 |
+|---|---|---|---|
+| **relcap 0.03** | **0.8399 / 1.0025** | 13 | 2368/25500 (9 %) |
+| relcap 0.10 | 0.8568 / 1.0441 | 11 | 2349/25500 |
+| cap 0.5 | 0.8732 / 1.0531 | 10 | 2379/25500 |
+| cap 1.0 | 0.9662 / 1.2508 | 8 | 3390/25500 — 발산 |
+
+관찰:
+
+- **원래 발산 지점(eval 4~5)을 상대 cap 2종 모두 통과**했다. 절대 cap 1.0 도 8회차까지는
+  멀쩡해 보였으므로 4~5회 통과만으로는 부족한데, 13회까지 유지된 것은 다른 수준의 근거다.
+- **baseline(0.895) 을 앞섰다.** relcap 0.03 이 0.840 으로 −0.055.
+- 절대 cap 0.5 는 10회차 0.873 이후 **0.922 → 0.958 로 3회 연속 상승** — 상대 cap 과
+  달리 불안정 조짐이 보인다.
+- 비율을 0.10 → 0.03 으로 더 조여도 성능이 나빠지지 않았다. 즉 **무제한 상태의 비율
+  0.557 은 필요 이상으로 크고, 그 꼬리가 발산을 유발**했다는 해석과 일치한다.
+
+---
+
+## 4. ⚠️ 같이 고친 것 — 이전 cap 구현의 치명적 버그
+
+처음 작성한 cap 은 이랬다:
+
+```python
+res = res * (rn.clamp(max=cap) / (rn + 1e-6))          # 잘못됨
+```
+
+두 가지가 틀렸다.
+
+**(1) `res = 0` 에서 gradient 가 정확히 0 이 된다.** 스케일이 `0 / 1e-6 = 0` 이 되고
+Jacobian 도 0 이다. `SRA_SOFT_START`(out_proj zero-init) 와 함께 켜면 `out_proj` 가
+0 에 영구히 갇혀 **그래프가 전혀 학습되지 않는다**. NaN 이 아니라 조용히 죽는다.
+
+실측 (out_proj gradient 합):
+
+| 설정 | grad |
+|---|---|
+| SOFT_START 만 | 78,751 |
+| RES_CAP 만 | 765,506 |
+| **SOFT_START + RES_CAP** | **0.00** ← 학습 불가 |
+
+이 조합으로 돌린 실행들의 체크포인트를 열어보니 **58 epoch 뒤에도
+`future_graph.out_proj` 가 정확히 `0.000e+00`** 이었다. 즉 그 실행들은 host 단독
+(=baseline) 을 측정한 것이고, "cap 이 발산을 해결했다"던 결론은 **그래프가 꺼져 있어
+발산할 것이 없었을 뿐**이었다. 해당 결과 4건은 폐기했다.
+
+**(2) cap 미만 값도 부당하게 축소된다.** `rn/(rn+1e-6)` 은 `rn` 이 작을수록 1 에서
+멀어진다 — `‖res‖=1e-5` 에서 **0.909 배**.
+
+`torch.where` 로 바꾸면 둘 다 해결된다:
+
+| 검증 | old | new |
+|---|---|---|
+| `res=0` 에서 gradient | 0.0000 | **31.30** |
+| ‖res‖=1e-5 일 때 스케일 | 0.909 | **1.000** |
+| cap 초과 시 상한 | 3.0 | 3.0 (동일) |
+| 정상 구간 gradient 차이 | — | 상대차 6e-7 |
+
+---
+
+## 5. 사용법
+
+```bash
+# 권장 설정 (MoFlow-NBA)
+SRA_EDGE_FIX=1 SRA_RES_CAP_REL=0.03 \
+CUDA_VISIBLE_DEVICES=0 python fm_nba_graph_v6.py \
+  --cfg cfg/nba/cor_fm.yml --exp v3_rel003 \
+  --batch_size 192 --epochs 150 --fm_in_scaling --tied_noise \
+  --top_n_neighbors 5 --uncertainty_weight 0.01 --data_dir ./data/nba
+```
+
+| 토글 | 기본 | 역할 |
+|---|---|---|
+| `SRA_EDGE_FIX` | off | edge-index 씬 혼합 버그 수정 (**필수**) |
+| `SRA_RES_CAP_REL` | 0 (off) | **비율 상한** `‖res‖ ≤ r·‖orig‖` — 권장 |
+| `SRA_RES_CAP` | 0 (off) | 절대 상한 — MoFlow 에서 열등함이 확인됨 |
+| `SRA_SOFT_START` | off | **RES_CAP 과 함께 쓰지 말 것** (§4). 단독으로도 발산 못 막음 |
+| `SRA_GATE_SCALE` | 1.0 | 전역 축소 — 가장 빨리 발산(3회차), 폐기 |
+
+---
+
+## 6. 미확정 / 한계
+
+**① 최종 수렴값은 아직 모른다.** 현재 9 %(2368/25500) 에서 0.840 이다.
+기존(버그판) SRA = **0.695**, baseline = **0.703**. 남은 91 % 와 cosine LR 감쇠에서
+더 내려가야 하며, **0.695 에 도달하지 못할 가능성은 여전히 열려 있다.**
+
+**② 비율값 튜닝이 끝나지 않았다.** 0.03 과 0.10 이 비슷하고 0.03 이 근소 우위다.
+더 조인 값(0.01)이 나을지, 아니면 0.03 이 이미 과도한 제약인지는 미검증이다.
+cap 을 조일수록 발산은 막히지만 그래프 기여도 줄어드므로, **"발산 안 하면서
+baseline 보다 나은" 구간이 실제로 존재하는지**가 최종 질문이다. 현재 0.840 vs
+baseline 0.895 는 그 구간이 존재한다는 첫 증거다.
+
+**③ MoFlow 전용 처방이다.** MID·LED 는 iterative denoiser 라 이 발산이 없고,
+`RES_CAP*` 을 쓰지 않는다 (MID 는 gate_init/warmup, LED 는 처방 없음).
+다른 호스트에 적용하려면 그 호스트의 residual/embedding 비율을 먼저 측정해야 한다.
+
+**④ 절대 cap 이 항상 나쁘다고 단정할 수는 없다.** cap 0.5 는 아직 발산하지 않았고
+반등 조짐만 보인다. 상대 cap 의 우위는 현재 13회 평가 기준의 관찰이며, 완주까지
+가야 확정된다.