123 lines
16 KiB
Markdown
123 lines
16 KiB
Markdown
# Go2 FL仿真功能接口:0.4.2(非严格accepted_skill)
|
||
|
||
## 当前0.4.2
|
||
|
||
公开命令/生命周期仍使用下述v4接口。高频GUI在每个已完成安全检查和同步证据的新物理状态后绘制,原render_interval20保留且不重复提交;headless不创建painter。实测解析S1 GUI/headless各六周期,旧0.4.1轨迹逐字节保持;完整矩阵/u256和新绘制节拍的原生故障注入未重验。真实GUI约34FPS但物理推进只有0.07060×,详见[实测结果](contact_cycle_sim_performance_v042_result.md)。独立包为`performance_v042/deliveries/go2_fl_contact_cycle_sim-0.4.2/`。
|
||
|
||
以下0.4.1段落解释继承的GUI契约及当时绘制频率,不代表0.4.2新增资格;当前状态以[交接摘要](current_status.md)为准。
|
||
|
||
## 继承的0.4.1契约:实时窗口与headless明确分开
|
||
|
||
公开Python增加严格布尔`gui=False`参数;CLI增加`--gui`。默认仍无窗口,控制/物理范围与0.4.0完全相同。示例:`start(NEW_OUTPUT, NEW_REGISTRATION, sequence='S1', controller='analytic', gui=True)`。`gui`进入精确spec、approval及认证FD,worker仅RUN使用`AppLauncher(visualizer='kit', headless=False)`;PREP始终headless/零环境/零物理。GUI依赖在PREP/RUN预导入并绑定,仅演示配置增加KitVisualizerCfg,不改物理参数、原render_interval20或控制步长。
|
||
|
||
独立新包的`bash demo_gui.sh`是一条实时GUI启动命令:真实Kit窗口,默认解析S1。`bash demo.sh`仍真实仿真但没有窗口;`bash verify_functional.sh`为原完整headless功能验证。`demo/measured_state_animation.gif`若查看0.4.0中的该文件,则只是**历史离线重建**,不是GUI也不是Kit摄像机录像;0.4.1真实截图/短录像路径见该包README。
|
||
|
||
界面显示真实模式、命令、6相位及进度、周期与tick、接触Fn/gap/足端位置。相机/灯光只修改新视觉prim;蓝色3kg载荷是原资产刚体,不额外创建假载荷。原500Hz安全/记录先于25Hz渲染更新,KitVisualizer在app.update期间禁用player物理,保持窗口响应而不额外步进。
|
||
|
||
完整序列或显式安全停止后,`query().state`在查看期为`viewing_final`;这不是最终监督通过。保留原场景/最终画面(最多10分钟),无额外物理步;关闭主窗口或Close按钮后才完成preclose身份核对、实际wait和清理。若先到600秒查看上限,则有界退出并报告`view_timeout`,不把它标成用户关窗;原总截止/存储等guard优先,若它们更早触发仍按原规则失败退出,不保证自动查看超时总会先到。提前关窗会中止并保存部分轨迹、非零退出,原因`gui_window_closed_before_completion`(不等待下一周期、不冒充protocol_complete)。显式公开`request_stop()`仍是原完整reload边界的安全停止,不等于关窗或完整矩阵通过。
|
||
|
||
GUI receipt单独记录真实render更新、完成标志、关闭原因、最终查看carry/counter不变;截图/桌面可见性仍须外部实测,receipt本身不证明窗口真的可见。启动早期AppLauncher尚未返回时的关窗尚未实测;任何缺失worker/完整证据均不能通过监督。0.4.0全部原包/证据保留;新版本只对本轮实际列出的结果重新验证,不自动继承为全部GUI命令/u256资格。
|
||
|
||
---
|
||
|
||
## 原有功能API与约束(继续保留)
|
||
|
||
This is the existing aided, floating-root Go2 FL single-leg simulation with the original IK, contact logic, residual bound, fixtures and functional/safety gates. Analytic is zero residual; u256 is the unchanged deterministic frozen actor **plus** that analytic reference. No training. CPU qualification is not physical validation.
|
||
|
||
## Public entrypoints (no Kit in caller)
|
||
|
||
From the repository or a same-layout independent copy:
|
||
|
||
```python
|
||
from scripts.go2_fl_skill import start, SkillRun
|
||
|
||
run = start('/absolute/NEW/run', '/absolute/current-task/registration.json',
|
||
command='x_bias-16mm', cycles=6, controller='analytic')
|
||
status = run.query() # detached JSON snapshot, no tensor aliases
|
||
request_id = run.queue('y_bias-24mm') # one outstanding request; may raise FileExistsError
|
||
stop_id = run.request_stop() # request, not immediate termination
|
||
exit_code = run.wait() # waits for supervisor, which waits/cleans Kit
|
||
# Existing process: SkillRun('/absolute/NEW/run').query()/queue()/request_stop()
|
||
```
|
||
|
||
`cycles` is an exact integer 1..20 (not bool). IDs are `validated_nominal` (+25,+20 mm) and `{x_bias,baseline_direction,y_bias}-{16,24}mm`. Directions are normalized world-XY ratios (25,10), (25,20), (15,20). No arbitrary vectors, durations, controllers, resets or randomization. Controllers are `analytic` or `u256`. Physical u256 execution requires complete current-source nominal20/S1/S2/S3 analytic successes supplied using `--analytics-evidence`. Prerequisites must have full requested counts and exact fixed pair-command history; an early safe stop or changed schedule never qualifies. Both controllers accept the same finite command/cycle interface. Historical 0.4.0 physically qualified u256 only on S1, not every combination or 20 cycles; 0.4.1 has not requalified u256/headless or u256/GUI. Its current-source analytic prerequisites remain mandatory.
|
||
|
||
`sequence=` supplies the entire initial command/cycles/queue; do not combine it with custom command/cycles/queue overrides. Frozen schedules:
|
||
|
||
- `nominal20`: nominal, 20 continuous cycles.
|
||
- `S1`: x_bias16 → baseline_direction24 → y_bias16, six cycles.
|
||
- `S2`: y_bias24 → x_bias24 → baseline_direction16, six cycles.
|
||
- `S3`: baseline_direction24 → y_bias24 → x_bias16, six cycles.
|
||
|
||
A is the initial **commanded** ground target, not measured landing; root target remains the initial commanded port. Each command owns an A→B(c)→A pair. Queued commands append FIFO (ten pending maximum) and apply only after an admitted return-to-A endpoint (completed cycles 2,4,...). Initial cycle zero is set by launch arguments; requests arriving during preparation queue for the next A endpoint, not an extra initial reference refresh. A pair's B never changes mid-pair, targets never accumulate, and history remains available for every recorded sample. Queueing never extends the requested cycle limit; stopping or reaching that limit can leave queued commands unexecuted. Stop is honored at **any** complete, audited, reloaded cycle endpoint, before seam admission/reference refresh; immediate safety failure always wins. Early completion is `requested_stop`, not `protocol_complete` for the requested maximum.
|
||
|
||
Invalid commands are rejected before any queue/control mutation. Runtime also validates exact mailbox fields. One atomic outstanding mailbox request, max 1024 input bytes, 64 receipts/run; malformed/overflow input cannot become control. Client rejection does not create mailbox files. Runtime rejection receipts may update audit metadata, never queue/control state. The mailbox is a bounded same-user local seam, not a hostile-user security sandbox.
|
||
|
||
`query()` reports state, authoritative global/cycle/local ticks, actual phase/progress, latched contact/normal force/gap, measured foot, commanded target/fixed anchors, pending/active IDs, stop request and failure. Physical status is copied every 500 physics ticks (one simulated second), at initialization, at endpoints and on failure; its tick identifies freshness. `receipt.json` records the latest consumed request immediately; `last_receipt` in status is sampled. Do not mistake `starting` for initialized physical state, or `stopped` for supervisor success. Final success needs `supervisor_success=true` and the successful waited campaign result; early stop retains requested/completed counts separately. If the API-owned supervisor exits before mailbox creation, its handle reports failure.
|
||
|
||
## CPU validation only
|
||
|
||
```sh
|
||
/usr/bin/python3.12 scripts/go2_fl_skill.py validate
|
||
CUDA_VISIBLE_DEVICES='' /home/cen/miniconda3/envs/linker_sim_isaac/bin/python \
|
||
scripts/go2_fl_skill.py validate --verify-frozen
|
||
```
|
||
|
||
The second command calls unchanged `replay.verify_bundle`, including all 134 immutable snapshots/live dependencies and the exact u256 hash; only the preexisting AGENT.md exception remains. Neither command queries GPU, creates authority, launches Kit or advances physics.
|
||
|
||
## Parent's real run commands (fresh authority generated automatically)
|
||
|
||
For a future explicit local invocation, create a fresh finite session first (CPU only, no GPU/Kit):
|
||
|
||
```sh
|
||
/usr/bin/python3.12 scripts/go2_fl_skill.py authorize --registration /absolute/NEW-session/registration.json
|
||
```
|
||
|
||
Python equivalent: `scripts.skill_launch_v4.new_registration(Path('/absolute/NEW-session/registration.json'))`. This is explicit caller authorization, not automatic reuse/extension of the development task. The new session is capped at12 hours and retains the same launch/call/storage limits. A new explicit invocation uses its own fresh registration and deadline. It does not revive the expired 0.4.0 task or the completed 0.4.1 development task.
|
||
|
||
Use system Python3.12 for supervision. Each `run` creates **NEW** `<output>-authority/approval.json`, binding exact current source hashes, spec, fixed limits, current boot, current allowed desktop identities, admission window, registration hash and deadline. It then runs a new zero-physics config-preparation Kit and one physical Kit, serially. No old approvals, binding preparations, failure directories, resumes or retries are reused. Preparation is not physical qualification.
|
||
|
||
Choose never-used output names; these are examples, **not an instruction to reuse an existing root**. Shared registration is the parent's current task registration, not an old physical grant. Keep it identical across repository and independent-copy runs so they share `skill-v4.lock`/`skill-v4-ledger.json` in its parent directory.
|
||
|
||
```sh
|
||
set -eu
|
||
REPO=/path/to/current/repository-or-independent-copy
|
||
REG=/absolute/NEW-session/registration.json
|
||
P=/home/cen/sf-runs/skill-v4-NEW-PREFIX
|
||
CLI="$REPO/scripts/go2_fl_skill.py"
|
||
/usr/bin/python3.12 "$CLI" run --registration "$REG" --output "$P-nominal20" --sequence nominal20
|
||
/usr/bin/python3.12 "$CLI" run --registration "$REG" --output "$P-S1" --sequence S1
|
||
/usr/bin/python3.12 "$CLI" run --registration "$REG" --output "$P-S2" --sequence S2
|
||
/usr/bin/python3.12 "$CLI" run --registration "$REG" --output "$P-S3" --sequence S3
|
||
# Parent reviews all analytics before executing this gated run:
|
||
/usr/bin/python3.12 "$CLI" run --registration "$REG" --output "$P-u256-S1" --sequence S1 --controller u256 \
|
||
--analytics-evidence "$P-nominal20" --analytics-evidence "$P-S1" \
|
||
--analytics-evidence "$P-S2" --analytics-evidence "$P-S3"
|
||
# Public transport safety-stop probe: request after first 5 ticks, reserve 3 cycles; expect endpoint1.
|
||
/usr/bin/python3.12 "$CLI" run --registration "$REG" --output "$P-stop" --cycles 3 --stop-at-tick 5
|
||
# Public invalid-send probe: records unchanged metadata and enumerated carry/RNG digests; expect cycle1.
|
||
/usr/bin/python3.12 "$CLI" run --registration "$REG" --output "$P-invalid" --cycles 1 --reject-at-tick 5
|
||
```
|
||
|
||
For external live control from another CPU process:
|
||
|
||
```sh
|
||
/usr/bin/python3.12 "$CLI" status --output "$P-S1"
|
||
/usr/bin/python3.12 "$CLI" queue --output "$P-S1" x_bias-24mm
|
||
/usr/bin/python3.12 "$CLI" stop --output "$P-S1"
|
||
```
|
||
|
||
Do not inject external commands into frozen matrix evidence runs; use a separately reserved run for custom live-command evidence. For independent-copy S1 reproduction, change REPO to that copy and use another never-used output, same registration. Source hashes do not embed the development repository path; actual runtime binding captures the current copy's absolute paths.
|
||
|
||
## Limits, evidence and dependencies
|
||
|
||
- Whole task shared ledger pre-reserves 2 Kit launches/run and `4500*requested_cycles+250` physics calls, never refunds failed/unrun slots; maximum 24 launches/650000 calls. It holds the existing-task lock through cleanup to prevent parallel public runs. A fresh finite authority registration is required; its boottime deadline and the per-run deadline apply, never an unbounded grant. The historical 0.4.0 task registration expired2026-10-16 05:38:07 +08:00 and is not extended. The separate 0.4.1 GUI task records its own scope beginning2026-10-16 09:51:52 +08:00, with the same finite whole-task caps; its independent demo trials use fresh bounded sessions, additionally accounted together by the parent. Future user-invoked `authorize` creates a different bounded session without launching simulation.
|
||
- Preparation: 360s total, zero physics. Physical run: ≤6 cycles1200s, >6 up to20 cycles2400s, stop probe900s; each includes120s cleanup. Calls: nominal20 ≤90250, six-cycle ≤27250, three-cycle stop ≤13750. One env/RTX5080, optimizer0.
|
||
- Existing process identity, fail-closed NVML, observed GPU diagnostics, stdout cap, native monitor, storage checks, authenticated worker FD, preclose same-object config binding, wait and owned cleanup are reused. Per-run owned cap4GiB and free headroom8GiB; shared ledger checks actual run/authority directory bytes against24GiB. Parent must additionally account for its package/analysis outputs outside those run directories. Native growth monitoring remains sampled, not a hard quota; existing coverage gaps remain reported.
|
||
- Automatic desktop admission uses only exact parent-approved executable PATH+SHA256 pairs in `configs/contact_cycle/skill_v4_desktop_allowlist.json`; fresh PID/birth/argv/inode/hash captured each run, any compute or unapproved graphics rejects. Optional expert `--gpu-identity` supplies an explicit current desktop identity JSON, never an old physical grant; existing GPUOwnership still rechecks every identity/client.
|
||
- Results: `prepare/{binding,inventory}.json`, `preparation-reviewed.json`, source snapshot, per-slot reservation/stdout/worker/supervisor results; `run/{trace.pt,initial-state.pt,events-and-seams.json}`, cycle audits, actual/requested counts and live receipts/pair history; `mailbox/{status,receipt}.json`; native/GPU observations; final waited `campaign-result.json`. Full500Hz samples and100Hz controls, integer local-cycle windows, no thinning/splicing/reset/reanchor. Evidence distinguishes physical functional gates and runtime/supervisor integrity.
|
||
- Required same-layout repository files include all current `validate` source entries, original functional v2/v3 configs, frozen candidate `logs/contact_cycle/sim_residual_training_v1/prepared01/candidate_u0256.pt`, its exact `manifest.json` and complete134-file `source_snapshot/`, all corresponding live frozen files/assets/configs, and the replay source hashes. Parent assembles this snapshot; do not regenerate its manifest. Candidate SHA256 `c088bb3aecaca751867118858626fd508f7a3983303802d7524353f80802cf99`.
|
||
- Installed runtime remains the pinned `/home/cen/IsaacLab`, `/home/cen/isaacsim-6.0.1`, native numerical dependencies and RTX5080. Repository ROOT is relocatable; those installed dependencies are intentionally not made portable or re-pinned. The v4 runner explicitly sets `SKILLFACTORY_GO2_ASSET_DIR=<this ROOT>/assets/generated/go2_fl` and `SKILLFACTORY_LEG_BUNDLE=<this ROOT>/assets/generated/legs/go2_fl` before frozen import-time defaults run; retain the complete generated base Go2 FL, support and leg assets (including conversion.json/manifest.json/USD dependencies) and installed source pins. See `contact_cycle_runtime.md` for CPU namespace mapping and runtime constraints.
|
||
|
||
Historical 0.4.0 primary runs passed analytic20 continuous cycles, S1/S2/S3 six-cycle switches, u256 S1, requested stop at cycle1 and live invalid-command rejection, including preclose/GPU/exit/cleanup. Those are not a new-source/full-GUI matrix qualification for 0.4.1. See the separate v4 result/evidence index for independent-directory reproduction and precise acceptance; this interface document does not itself confer acceptance or general robustness/full-robot/real-world capability.
|