PHASOR

PHASOR: Phase-Anchored Universal Action Representations for Humanoid Embodiments (arXiv:2606.01851)

Human 모션의 주기성(phase manifold)과 비주기 pose를 분리 학습한 뒤, 여러 휴머노이드 로봇을 frozen human oracle에 정렬(anchoring)하여 embodiment-agnostic action embedding을 만드는 파이프라인.

Stage 1 (dualpath/)         : Human-only DualPath — per-part PAE + PeriodicBottleneck (phase)
                              + pose branch, 양방향 FiLM coupling (film-via-encoder)
Stage 2 (multicrossalign/)  : Human 전 경로 frozen → 4 robots (G1/H12/T1/BHL) adapter +
                              alignment head 학습, soft-InfoNCE + LAMP soft target

Repository 구조

├── preprocess/        # AMASS human + robot retarget + paired dataset + LAMP feature 추출
├── dualpath/          # Stage 1: single-embodiment DualPath (models/, train.py, evaluation/)
├── crossalign/        # (레거시) human↔G1 단일 로봇 정렬 + ablation
├── multicrossalign/   # Stage 2: multi-robot 정렬 — 논문 메인
│   ├── models/        #   multi_cross_emb_model.py (OURS) + MLP/SONIC 베이스라인
│   ├── losses/        #   soft-InfoNCE alignment (LAMP), speed/shape loss
│   ├── train_multi.py #   Stage 2 학습 엔트리 (config_multi.py)
│   ├── evaluation/    #   eval_multi_crossemb.py (retrieval), viz_* (PCA/mujoco 렌더링)
│   └── results_stage2/PAPER_TABLE.md   # 논문 최종 테이블
├── PROVENANCE.md      # 파일 출처/통합 이력 (구 README)
└── RUN_PLAN.md        # 실험 플랜 이력

Setup

conda env: deephase (PyTorch)          # 학습/평가
# RL downstream(IsaacLab)은 별도 레포/환경 — 이 레포에는 포함되지 않음

외부 의존성 (환경변수로 오버라이드 가능)

env var	용도	필요 시점
PHASOR_DATA	DPAE_Dataset 루트 (paired dataset)	학습·평가 전부
PHASOR_GMR	YanjieZe/GMR clone 경로 (로봇 MJCF 에셋)	mujoco 시각화만
PHASOR_SMPL_GMR	SMPL-GMR retarget 레포	데이터 전처리 재생성만
PHASOR_WTD	walk-the-dog-robot 레포	preprocess_robot_v3만

mujoco 시각화를 쓰려면:

git clone https://github.com/YanjieZe/GMR.git third_party/GMR   # 또는 PHASOR_GMR로 기존 clone 지정

핵심 학습·평가 코드(train_multi.py, eval_multi_crossemb.py, models/, losses/)는 이 레포 + 데이터셋 외에 어떤 외부 코드에도 의존하지 않는다.

Checkpoints (git 미포함, runs/는 .gitignore)

로컬 기준 대표 체크포인트 4개가 runs/에 배치되어 있음:

모델	경로	비고
OURS (최종)	multicrossalign/runs/multi_A1B1_best/ckpt_epoch008.pt	A1(z_pose_mod align) + B1(via-encoder Stage1)
MLP 베이스라인	multicrossalign/runs/old_exp/mlp_C/ckpt_epoch026.pt
SONIC 베이스라인	multicrossalign/runs/old_exp/sonic_compact/ckpt_epoch011.pt
Stage 1 human oracle	dualpath/runs/dp_human_lambda_default/ckpt_epoch015.pt	Stage 2의 frozen anchor

Quickstart

ROOT=<repo root>; DATA=${PHASOR_DATA:-/path/to/DPAE_Dataset}

# Stage 2 retrieval 평가 (best 모델)
PYTHONPATH=$ROOT python -m multicrossalign.evaluation.eval_multi_crossemb \
    --ckpt $ROOT/multicrossalign/runs/multi_A1B1_best/ckpt_epoch008.pt \
    --lamp-feat-path $DATA/Paired_AMASS_G1_CMU_KIT/lamp_features.npz \
    --n-clips 100 --n-per-clip 20 --skip-recon \
    --out eval_out.json

# Stage 1 학습 (human)
bash dualpath/scripts/run_human_train.sh

# Stage 2 학습 (multi-robot)
bash multicrossalign/scripts/run_multi_train.sh

결과 (H→R retrieval mAP %, 4-robot 평균)

Model	clip	window	exact MRR
PHASOR (OURS, A1B1 ep8)	99.2	23.3	93.9
MLP	99.7	20.8	87.1
SONIC	99.1	20.9	55.1

Ablation ladder (window mAP): B2 3.3 → +B1 3.5 → +root_pos 5.9 → +z_pose(A1) 20.0 → A1+B1 23.2. 상세: multicrossalign/results_stage2/PAPER_TABLE.md, 구조 문서: multicrossalign/runs/multi_A1B1_best/README.md(로컬), multicrossalign/PIPELINE.md.