Files
SkillFactory/docs/contact_cycle_runtime.md
T
chenlin 9fe9d27865 feat: checkpoint contact-cycle evaluation and RootXY PPO progress
Consolidate next-stage docs, archive superseded narratives, and preserve frozen document inputs. Retain invalid P2 pairs, partial RootXY training, failed attempts and nonselectable checkpoints as explicit limitations.

Include supervised evaluation/training, desktop GPU admission, bounded evidence and atomic-publication monitor repairs with CPU regressions. Ignore local dotenv configuration.

Validation: 1403 passed, 6 skipped for contact-cycle and related contracts/CLI tests. Full-suite legacy ABI and registration tests require Python 3.12/Torch 2.10/pxr; no runtime checks relaxed. No new physical run or accepted skill.
2026-10-15 14:18:17 +08:00

83 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 接口与运行约束:Go2 FL参考+残差
## 当前契约
- 任务:`SkillFactory-Go2FL-ContactCycleSim-v1`。
- 特征:`contact-cycle-sim-truth-residual-46-v1`;46D、float32、有限值,不能载入旧32D策略。
- 名义9秒周期:承重3s、卸载1s、抬腿0.6s、摆动1.4s、落地0.8s、重新承重2.2s。
- 500Hz物理/失败检查,100Hz控制。默认位移`[0.025,0.02,0]`m,净空0.05m+0.01m拱高。
- 浮动根、3kg合成载荷/传感载体、真实接触/六维测力;当前有效系统质量约5.388kg,W指有效系统重量,不仅是3kg载荷重量。保留有界横向/转动辅助,竖直guide力必须为0。不是固定根,也不是无辅助平衡。
- 当前使用仿真真值,名义任务不接受旧课程采样器、stand-only、扰动或传感/执行器随机化的静默混入。
## 观察与动作
| 观察索引 | 含义 |
|---|---|
| 0–31 | 原传感/命令32D,包括上一步完整归一化关节动作 |
| 32–34 | root相对命令挂载点的位置误差,世界系m |
| 35–37 | root相对命令的线速度误差,世界系m/s |
| 38 / 39 | 真实地面法向力Fn(N)/真实足端gap(m) |
| 40–42 | 下一控制步的归一化参考动作 |
| 43–45 | 上一控制步夹紧后的请求残差,不是投影后的实际残差 |
参考由足端目标、阻尼IK和Jacobian载荷补偿生成,仅在reset或控制边界推进,不能因读取观察而推进。3维残差请求先夹到±1,每关节对应±0.05rad;合成目标再投影到原关节范围,投影只能缩小实际残差。
必须分别记录`reference_used_normalized`、`reference_next_normalized`、`residual_request_normalized`、`effective_residual_rad`和实际关节目标。PPO概率针对采样残差latent,不针对合成后的绝对关节动作。随机策略与确定性均值策略要明确区分。
checkpoint为`skillfactory.contact-cycle-sim-residual-ppo-checkpoint.v1`。原参考/零初始化actor成功不算学习;本轮已训练u256身份见[当前进度](current_status.md)。原task objective之外保留root位置/速度和残差成本,具体尺度以绑定配置为准,不能为了新实验原地改旧配置。
## 不可绕过的门禁
- 接触获取:200ms内达到至少0.5W并持续10ms、gap≤0.5mm;失败必须终止。
- 离地检测:on=1mm、off=0.5mm、dwell=10ms;保持真实起始阶段和首次失败来源。
- timeout bootstrap用reset前的终端观察;真实失败bootstrap为0;禁止跨reset串接回合。
- 有限性、关节/力矩/速度约束、辅助力边界及物理失败检查保持启用。非有限动作必须在污染动作历史前拒绝。
- 使用SI单位;项目对外四元数约定xyzw,与后端不同约定要显式转换。力/力矩坐标系与作用点必须明确,统一经唯一COM外力合成入口,不能重复叠加r×F或把辅助力冒充足端接触力。
- 功能门槛是开发阶段形成的判据,不是独立验收;不得删失败、放宽门槛或用autoreset后的轨迹补成功。
## 实现入口
| 用途 | 路径(仓库根目录相对路径) |
|---|---|
| 参考、模型、PPO、预算协议 | `source/SkillFactory/SkillFactory/legs/contact_cycle_sim/` |
| 仿真环境、动作、记录 | `source/SkillFactory/SkillFactory/tasks/manager_based/contact_cycle_sim/` |
| 任务/功能/训练配置 | `configs/contact_cycle/simulation_residual_v1.json`、`simulation_functional_v1.json`、`sim_training_v1.json` |
| 训练器(不是回放器) | `scripts/train_cycle_sim_residual.py` |
| 非优化接口/物理探针 | `scripts/verify_cycle_sim_residual.py`、`verify_cycle_sim_learning_runtime.py` |
| 功能审计 / Kit监督 | `scripts/audit_contact_cycle_functional.py` / `scripts/supervise_sim.py` |
旧`train_contact_cycle.py`仍属于32D路径;不要用于46D候选。已实现冻结回放`scripts/replay_cycle_sim_residual.py`,P1/P2准备与评估为`prepare_cycle_sim_binding.py`/`evaluate_cycle_sim_residual.py`。RootXY独立入口`train_cycle_sim_rootxy_v2.py`,同46D观察但独立task/checkpoint身份;仅XY奖励尺度变化,详见[配方](contact_cycle_rootxy_v2_plan.md)。新任务不得借用旧grant或用不可选取u64替换冻结u256。
## 安全运行
仓库根目录下执行。只读复核已有训练,不启动Kit:
```sh
python3 logs/contact_cycle/sim_residual_training_v1/verify_delivery.py
```
本机CPU测试解释器:`/home/cen/miniconda3/envs/linker_sim_isaac/bin/python`(Python3.11/Torch2.7);不要用缺Torch的系统Python跑学习测试。用以下文件映射跳过顶层Kit任务注册,**仅供CPU测试,不可用于运行绑定**:
```sh
CUDA_VISIBLE_DEVICES='' PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 \
/home/cen/miniconda3/envs/linker_sim_isaac/bin/python - <<'PY'
import importlib.util, sys
from pathlib import Path
root = Path.cwd()
spec = importlib.util.spec_from_file_location(
'SkillFactory', root / 'source/SkillFactory/SkillFactory/__init__.py',
submodule_search_locations=[str(root / 'source/SkillFactory/SkillFactory')])
sys.modules['SkillFactory'] = importlib.util.module_from_spec(spec)
sys.path.insert(0, str(root / 'scripts'))
import pytest
targets = [str(p) for p in sorted((root / 'tests').glob('test_contact_cycle*.py'))]
raise SystemExit(pytest.main(['-q', *targets]))
PY
```
上面只跑接触周期主线。全仓旧发布/ABI测试要求Python3.12+Torch2.10.0;任务注册另需pxr/Isaac运行依赖,不应在此3.11/Torch2.7环境期待全套通过,也不能放宽冻结包版本检查来凑通过。不少CPU回归读取本机冻结快照/安装文件;缺少时失败或显式skip不等于新机器获得资格。Isaac运行使用固定`/home/cen/IsaacLab`、`/home/cen/isaacsim-6.0.1`及RTX5080,不把CPU测试版本当实际Kit依赖版本。
默认测试中跳过的PhysX包装不算已执行物理验证。不要运行根目录`pytest`,它可能收集`logs/`中的归档测试;不要在根目录执行`uv sync`或修改外部Isaac Lab/Unitree资源。
当前RootXY和P1/P2必须使用各自认证受监督入口,不得用通用`supervise_sim.py`替代授权/绑定/归属检查。监督器使用`/usr/bin/python3.12`,真实worker在认证FD交接后加载AppLauncher。不得覆盖原证据、杀无关进程或把工具attention当作卡死。采用同一boot绝对`CLOCK_BOOTTIME`截止、rollout预扣、成功后提交;中断不退款,旧grant/目录不复用。配置准备不等于批准运行。详情见[启动合同](contact_cycle_rootxy_v2_launch.md)和[评估监控](contact_cycle_native_monitor_v3.md)。