docs/MOFLOW_EDGEFIX.md

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 가 씬을 뒤섞음

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)

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 만 잘라낸다.

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. 재현

# 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	게이트 전역 축소 (실패한 처방, 코드만 잔존)