Files
SkillFactory/docs/contact_cycle_runtime.md
T
chenlin c528dd268f feat: checkpoint Go2 FL simulation performance v0.4.2
Include callable skill and live-GUI prerequisites, epoch sensor reads, packed snapshots, sampled bit-exact kinematics, and verified-tick rendering without changing the physical/control schedule.

Record bounded analytic S1 GUI/headless qualification, original failures and CPU evidence (1557 passed, 6 skipped). Preserve accepted_skill=false and sub-real-time limitations. Exclude native authorities, caches, large media and local delivery copies; retain sealed artifact digest.
2026-10-16 15:46:01 +08:00

113 lines
11 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参考+残差
## 当前0.4.1:真实GUI与headless分开
[0.4.1实际结果](contact_cycle_sim_gui_v041_result.md):公开`start(..., gui=True)`/CLI `--gui`贯穿approval、监督和认证worker,默认仍headless。独立包`/home/cen/sf-deliveries/go2_fl_contact_cycle_sim-0.4.1/`中`bash demo_gui.sh`真实解析S1开窗;原`demo.sh`和`verify_functional.sh`保留。当前源码GUI/headless S1各六周期原物理/完整性通过;活跃GUI提前关闭2040tick按预期中止,exit2不算完成。
GUI仅新camera/light/UI,原负载及控制/物理/辅助不变;完整后只render保留原场景(最多10分钟),关闭后才完成身份/wait/清理。真实截图和原始录像/原速剪辑在包demo,不是FK动画,Kit约2–3FPS、不保证墙钟1×实时。原0.4.0全部字节/校验保留;0.4.1未重验其完整矩阵/u256或GUI安全停止/超时/极早启动关闭,不继承新资格。所有旧严格失败/accepted_skill=false保持。
---
## 历史可调用仿真功能版0.4.0
新公开接口/CLI已真实仿真验证,见[API及生命周期](go2_fl_skill_v4_api.md)与[本轮实际结果](contact_cycle_sim_skill_v4_result.md)。`scripts/go2_fl_skill.py`提供start/query/queue/request_stop/wait及authorize/validate/run/status/queue/stop;复用原解析IK/接触/保护,u256仍为可选冻结残差,不是通用adapter。
独立包`/home/cen/sf-deliveries/go2_fl_contact_cycle_sim-0.4.0/`:`bash demo.sh`真实启动S1;`bash verify_functional.sh`串行真实验证20周期/三序列/u256/停止拒绝。每次新有限登记/新grant/新目录;本轮当前登记已消费,不重跑旧例名。
原名义解析20周期、S1/S2/S3各6周期、u256 S1、边界停止/非法拒绝、独立目录公开CLI和外部实时Python队列均通过。目标为固定世界A去/回成对,命令仅A边界生效,不累积或测量重锚。保持原辅助/真值/单seed限制;30mm根XY只诊断,历史accepted_skill=false/严格失败不改写。下列v2/v3及冻结v1约束作为复用/历史继续保留,不取代当前API说明。
---
## 本轮独立功能版本(先于下列冻结v1合同阅读)
当前优先级已由RootXY精度优化改为完整功能流程。新判据与预算见[功能流程v2](contact_cycle_functional_flow_v2.md),配置`configs/contact_cycle/functional_flow_v2.json`;原v1/严格P1/P2/RootXY配置和失败结果不变。30mm根XY在新功能版本中只记录,旧严格验收仍按原门槛判失败。
新增`legs/contact_cycle_sim/functional_flow_v2.py`只准备独立协议,复用整数时钟/固定A-B-A-B命令;原相位终止和全部安全保护初版不动。本轮复用无autoreset的`EvaluationContactCycleEnv`,两次接缝禁止reset、pose写入、测量落点重锚及拼接。分别报告零残差解析控制与解析参考+原冻结u256确定性残差。
`scripts/audit_cycle_functional_flow.py`是CPU只读审计,输出`trace_functional_passed`,**不授予运行许可、不证明运行期连续性**;全局时钟重启、失败标记及不足3周期均不能通过。实际受监督入口现为`scripts/evaluate_cycle_functional_flow.py`,新绑定在`functional_flow_binding_v2.py`,同步完整记录/接缝核对在`functional_flow_recording_v2.py`。它们使用独立用户批准,不通过旧P1/P2/RootXY授权绕过门禁。
本轮新授权已执行且消费:解析单周期及连续3周期连同监督检查通过,u256单周期通过;u256三周期物理完成但监督器GPU归属检查失败,**原campaign失败保持**。实际36000物理调用/初始化额外0/优化0,无重试;参见[完整结果与启动命令](contact_cycle_functional_flow_v2_result.md)。该次运行后未重试,不追加RootXY试训。
用户新批准的[功能补验v3已实际全部通过](contact_cycle_functional_followup_v3_result.md):同入口`--followup-v3`、新协议/绑定及原检查决策不变的GPU观测;新0物理准备后,先u256原命令3周期完整通过,再六组解析/u256成对3周期全通过,6对初态一致。175500共享调用、39周期、3585.201s、0训练/0重试;GPU/退出清理正常,旧失败仍保留、未查明具体原因。源码/权重/功能阈值/辅助不变,双方功能通过率6/6,不声称学习必要或全域鲁棒。用户另授[持续预算权限](execution_authority.md),后续自主预设护栏并新绑定/独立登记,不再逐次请批、不复用旧grant。原计划与CPU准备为[历史记录](contact_cycle_functional_followup_v3.md)。
## 原冻结v1契约(历史与复用边界保持)
- 任务:`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)。