Files
SkillFactory/scripts/audit_contact_cycle_functional.py
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

159 lines
9.3 KiB
Python

#!/usr/bin/env python3
"""Offline, nominal simulation-function check. Never runs Kit, a policy or an optimizer."""
import argparse
import hashlib
import json
import math
from pathlib import Path
import torch
ROOT = Path(__file__).resolve().parents[1]
DEFAULT_CONFIG = ROOT / 'configs/contact_cycle/simulation_functional_v1.json'
def longest_run(mask):
longest = current = 0
for value in mask.tolist():
current = current + 1 if value else 0
longest = max(longest, current)
return longest
def evaluate(trace, cfg, controller_kind):
"""One actual first episode, [T,1,...]. Early stops/resets cannot be repaired by relabeling."""
if controller_kind not in ('analytic_reference', 'learned_policy'):
raise ValueError('Declare the controller evidence type')
if (cfg['format'] != 'skillfactory.contact-cycle-simulation-functional.v1'
or len(cfg['phase_durations_s']) != 6
or any(type(x) not in (int, float) or not math.isfinite(x) or x <= 0
for x in [cfg['physics_dt_s'], *cfg['phase_durations_s'], *cfg['gates'].values()])
or type(cfg['gates']['minimum_complete_cycles']) is not int):
raise ValueError('Invalid functional contract')
required = {'time', 'phase', 'scenario', 'weight', 'normal', 'foot', 'target', 'gap',
'signed_height_error', 'tilt', 'external', 'guide', 'auxiliary', 'joint_excess',
'limit_ratio', 'contact_acquired', 'actor_metadata_available', 'control_action_available'}
out = {'controller_kind': controller_kind, 'sim_functional_passed': False,
'accepted_skill': False, 'gates': {}, 'metrics': {}}
if not required <= trace.keys():
out['missing_fields'] = sorted(required - trace.keys())
return out
n = len(trace['time'])
if not n or any(v.shape[:2] != (n, 1) for v in trace.values()):
out['error'] = 'Require nonempty single-episode [T,1,...] arrays'
return out
gates, metrics = out['gates'], out['metrics']
gates['finite'] = all(bool(torch.isfinite(v).all()) for v in trace.values())
if not gates['finite']:
return out
d = {k: v[:, 0] for k, v in trace.items()}
t, dt, g = d['time'], cfg['physics_dt_s'], cfg['gates']
duration = sum(cfg['phase_durations_s'])
expected = torch.arange(1, round(duration / dt) + 1, dtype=t.dtype, device=t.device) * dt
gates['complete_clock_without_reset'] = n == len(expected) and bool(torch.allclose(t, expected, atol=1e-5, rtol=0))
gates['nominal_only'] = bool((d['scenario'] == cfg['nominal_scenario_id']).all())
gates['no_external_disturbance'] = bool((d['external'].abs() <= 1e-6).all())
gates['actions_recorded'] = bool(d['control_action_available'].all())
gates['controller_metadata'] = (bool(d['actor_metadata_available'].all()) if controller_kind == 'learned_policy'
else not bool(d['actor_metadata_available'].any()))
if not gates['complete_clock_without_reset']:
metrics['actual_end_s'] = float(t[-1])
return out
ends = t.new_tensor(cfg['phase_durations_s']).cumsum(0)
phase = torch.bucketize(t.contiguous(), ends[:-1], right=True)
gates['six_command_phases'] = bool(torch.equal(d['phase'], phase)) and set(phase.tolist()) == set(range(6))
if not gates['six_command_phases']:
return out
normal, weight = d['normal'][:, 2], d['weight']
gates['positive_weight'] = bool((weight > 0).all())
if not gates['positive_weight']:
return out
windows = {'support': (phase == 0) & (t >= ends[0] - g['support_final_window_s']),
'unload': (phase == 1) & (t >= ends[1] - g['unload_final_window_s']),
'reload': (phase == 5) & (t >= duration - g['reload_final_window_s'])}
for name, mask in windows.items():
contact = float((normal[mask] > g['contact_force_on_N']).float().mean())
load = float((normal[mask] / weight[mask]).mean())
metrics[name + '_contact_fraction'] = contact
metrics[name + '_load_fraction'] = load
if name != 'unload':
gates[name + '_ground_support'] = (contact >= g['support_reload_contact_fraction_min']
and load >= g['support_reload_load_fraction_min'])
else:
metrics['unload_remaining_support_fraction'] = load / max(metrics['support_load_fraction'], 1e-6)
gates['unloaded'] = (metrics['unload_remaining_support_fraction']
<= g['unload_remaining_support_fraction_max'])
air = (d['gap'] >= g['swing_gap_m_min']) & (normal <= g['contact_force_on_N'])
swing = phase == 3
metrics['swing_air_fraction'] = float(air[swing].float().mean())
metrics['swing_contiguous_air_s'] = longest_run(air[swing]) * dt
gates['real_flight'] = (metrics['swing_air_fraction'] >= g['swing_air_fraction_min']
and metrics['swing_contiguous_air_s'] >= g['swing_contiguous_air_s_min'])
pre, post = (phase == 2).nonzero()[-1, 0], swing.nonzero()[-1, 0]
requested = d['target'][post, :2] - d['target'][pre, :2]
actual = d['foot'][post, :2] - d['foot'][pre, :2]
gates['three_dimensional_command'] = bool((requested.abs() > .001).all())
progress = actual * requested.sign() / requested.abs().clamp_min(1e-6)
metrics['swing_xy_progress_fraction'] = progress.tolist()
gates['xy_swing_motion'] = bool((progress >= g['swing_xy_progress_fraction_min']).all())
landing_error = (d['foot'][windows['reload']] - d['target'][windows['reload']]).norm(dim=-1)
metrics['landing_error_m'] = float(landing_error.mean())
gates['landing_position'] = metrics['landing_error_m'] <= g['landing_position_error_m_max']
gates['contact_acquired'] = bool(d['contact_acquired'].any())
gates['no_gross_collapse'] = (float(d['signed_height_error'].abs().max()) <= g['root_height_error_m_max']
and float(d['tilt'].max()) <= g['root_tilt_rad_max'])
gates['unilateral_contact'] = float(normal.min()) >= -g['normal_force_negative_tolerance_N']
gates['no_gross_penetration'] = float(d['gap'].min()) >= -g['ground_penetration_m_max']
gates['actuator_joint_bounds'] = (float(d['limit_ratio'].max()) <= g['normalized_effort_velocity_max']
and float(d['joint_excess'].max()) <= g['joint_limit_excess_rad_max'])
auxiliary = d['auxiliary']
# A point-applied vertical force can have COM-reduced x/y moments, but no free couple.
# The declared payload COM offset has norm .06m; do not blanket-zero valid r x F.
moment_bound = auxiliary[..., 2].clamp_min(0) * g['auxiliary_lever_arm_m_max'] + 1e-6
gates['declared_fixture'] = (float(d['guide'][..., 2].abs().max()) <= g['guide_vertical_N_max']
and float(auxiliary[..., :2].abs().max()) <= 1e-6
and float(auxiliary[..., 2].min()) >= -1e-6
and float(auxiliary[..., 2].sum(-1).max()) <= g['auxiliary_vertical_N_max']
and float(auxiliary[..., 5].abs().max()) <= 1e-6
and bool((auxiliary[..., 3:].norm(dim=-1) <= moment_bound).all())
and float(auxiliary[phase == 0].abs().max()) <= 1e-6)
out['sim_functional_passed'] = all(gates.values())
return out
def main():
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument('--trace', type=Path, required=True)
parser.add_argument('--config', type=Path, default=DEFAULT_CONFIG)
parser.add_argument('--controller-kind', choices=['analytic_reference', 'learned_policy'], required=True)
parser.add_argument('--output', type=Path, required=True)
args = parser.parse_args()
if args.output.exists():
raise FileExistsError('Never overwrite an earlier audit')
cfg = json.loads(args.config.read_text())
raw = torch.load(args.trace, map_location='cpu', weights_only=True)
if 'time' in raw:
traces = {str(e): {k: v[:, e:e+1] for k, v in raw.items()}
for e in range(raw['time'].shape[1])}
else:
traces = raw # saved validation subsets keyed by environment
rows = {e: evaluate(d, cfg, args.controller_kind) for e, d in traces.items()}
passed = sum(r['sim_functional_passed'] for r in rows.values())
result = {'format': cfg['format'], 'controller_kind': args.controller_kind,
'sim_functional_passed': passed >= cfg['gates']['minimum_complete_cycles'],
'trace_path': str(args.trace), 'trace_sha256': hashlib.sha256(args.trace.read_bytes()).hexdigest(),
'config_sha256': hashlib.sha256(args.config.read_bytes()).hexdigest(),
'audit_source_sha256': hashlib.sha256(Path(__file__).read_bytes()).hexdigest(), 'rows': rows,
'functional_cycles_passed': passed,
'accepted_skill': False, 'new_simulation_steps': 0, 'new_optimizer_steps': 0,
'note': 'Retrospective development replay. Non-nominal rows are outside this scope; '
'no learned claim from analytic control.'}
args.output.parent.mkdir(parents=True, exist_ok=True)
args.output.write_text(json.dumps(result, indent=2, allow_nan=False) + '\n')
print(json.dumps({k: v for k, v in result.items() if k != 'rows'}, indent=2))
raise SystemExit(0 if result['sim_functional_passed'] else 1)
if __name__ == '__main__':
main()