exoskeleton/README.md

# Heterogeneous 7-DoF Bilateral Teleoperation

This repository contains the manuscript, canonical robot models, pre-prototype
closed-loop simulator, and reproducible evidence pipeline for heterogeneous
7-DoF master--slave teleoperation.

The current implementation supports numerical and simulation evidence only.
It must not be used to claim physical wrench accuracy, hardware stability, or
human-subject performance before the corresponding locked hardware studies are
completed.

## Repository layout

- `code/core/`: SEW retargeting, H1 baselines, wrench estimation, feedback
  mapping, network emulation, command allocation, and passivity supervision.
- `code/simulate_closed_loop.py`: rigid-body bilateral simulation using
  `master_7dof.urdf` and `real_slave_7dof.urdf`.
- `code/experiments/`: immutable plans, paired random streams, atomic trial
  logging, manifests, validation, and executable H1--H4 adapters.
- `code/analysis/`: independent endpoint reconstruction and paper source-data
  generation.
- `code/config/experiments/`: smoke, calibration, and locked-template study
  specifications.
- `docs/calibration/`: calibration policy, traceable audit, and machine-readable
  freeze decisions.
- `paper/exoskeleton/IEEEtran/main2.tex`: canonical manuscript source.

## Reproducible environment

Python 3.10 is required. From the repository root:

```bash
uv sync --locked
```

The lock file pins the Pinocchio-compatible `urdfdom` and `tinyxml2` ABIs.

## Verification

```bash
PYTHONDONTWRITEBYTECODE=1 \
MPLCONFIGDIR=/tmp/exoskeleton-mpl-cache \
XDG_CACHE_HOME=/tmp/exoskeleton-xdg-cache \
.venv/bin/python -m unittest discover -s code/test -p 'test_*.py' -v
```

## Minimal H1 smoke study

```bash
.venv/bin/exo-experiment plan \
  --spec code/config/experiments/h1_smoke.json \
  --output /tmp/h1-plan.json

.venv/bin/exo-experiment run \
  --plan /tmp/h1-plan.json \
  --batch-dir output/experiments/h1-smoke \
  --executor experiments.executors:execute_h1_retargeting

.venv/bin/exo-experiment validate \
  --batch-dir output/experiments/h1-smoke

.venv/bin/exo-paper-artifacts \
  --batch-dir output/experiments/h1-smoke \
  --metric-config code/config/experiments/metrics_h1_calibration.json
```

Equivalent executor/config pairs are documented in
`code/experiments/README.md`.

The current calibration decision is recorded in
`docs/calibration/CALIBRATION_AUDIT_2026-07-27.md`. It deliberately leaves H1
and the bilateral gain/energy settings unfrozen; calibration values are not
manuscript Results. The companion formula-linked workbook is
`outputs/calibration-20260727/calibration_audit_2026-07-27.xlsx`.

## Manuscript build

Compile from `paper/exoskeleton` so the `assets/` paths resolve:

```bash
cd paper/exoskeleton
latexmk -pdf -interaction=nonstopmode -halt-on-error IEEEtran/main2.tex
```

## Evidence locking

Calibration and pilot studies may run without Git provenance. A `locked` study
requires a clean Git worktree, an immutable commit, and matching hashes for the
environment lock and canonical URDFs. Restoring a locked batch from a different
commit or modified source files is rejected by design.