docs/RELCAP.md

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

# 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 은 이랬다:

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. 사용법

# 권장 설정 (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회 평가 기준의 관찰이며, 완주까지 가야 확정된다.