BRACE

Adapting Whole-Body References for Force and Terrain Aware Humanoid Motion Tracking

BRACE adapts a humanoid's whole-body motion reference to commanded hand forces, moments and terrain. Two privileged teachers transfer exertion and compensation behavior into one student. The student runs from proprioception and reference commands without terrain maps or measured hand wrenches.

This release contains all three trained checkpoints, their frozen configurations, SafeTensors weights, the student ONNX export, and a runnable source snapshot. The paper, project page and companion GitHub repository describe the method and demonstrations. The included source snapshot provides the same BRACE runtime and training entrypoints.

Model	Files	Observations and role
Student	artifacts/student/	Unified exertion/compensation; 25-frame proprioception/action history; flow student; 29 joint targets
Exertion teacher	artifacts/teachers/exert/	rich_obs, 8-frame histories, terrain/root/slope encoder; commanded force and moment
Compensation teacher	artifacts/teachers/comp/	rich_obs, 8-frame histories, privileged terrain/external-wrench encoder; force and moment disturbances

Download

Install huggingface_hub, then download the complete bundle:

from huggingface_hub import snapshot_download

snapshot_download(repo_id="sudarshanharithas/BRACE", local_dir="brace-models")

The layout matches BRACE's checkpoint interface. Every model folder contains last.ckpt, model.safetensors, resolved_configs_inference.pt, and resolved_configs_inference.yaml. The original checkpoint state, including optimizer state and normalizers, is preserved. SafeTensors files contain identical model tensors. Only run names and machine-specific paths in the companion configs were made portable. Checksums and sizes are recorded in artifact_manifest.json.

Use the student

Extract the bundled source and install the CPU simulation/export dependencies with Python 3.11:

tar -xzf brace-models/source/brace-source.tar.gz
cd brace
python3.11 -m venv .venv
source .venv/bin/activate
pip install -e '.[sim,export,deploy]'
pip install --no-deps -e vendor/ProtoMotions

For headless Ubuntu, install libosmesa6, libgl1, and libegl1 and set MUJOCO_GL=osmesa and PYOPENGL_PLATFORM=osmesa before simulation imports. For an execution check, use the included procedural standing fixture. The original recorded motion library is not distributed. From the extracted brace/ directory:

python -m brace_repro sim2sim --stage student --mode exert \
  --checkpoint ../brace-models/artifacts/student/last.ckpt \
  --motion ../brace-models/data/motions/smoke.pt \
  --force 3 0 0 --torque 0.1 0 0 \
  --steps 100 --output runs/student-exert

For compensation, use --mode comp. In this sim2sim command the force/moment arguments set physical disturbances in compensation mode. The real deployment runtime instead receives zero exertion commands in compensation mode.

The ONNX export is at artifacts/student/compiled_models/unified_pipeline.onnx. Keep its YAML and the parent model's resolved_configs_inference.yaml together. The online wrench-adapted reference and correctly timed histories are part of the controller; running the neural network alone does not reproduce BRACE. Preflight without opening a robot driver:

python -m brace_deploy --check \
  --onnx-path ../brace-models/artifacts/student/compiled_models \
  --pose-source vr

The source snapshot includes the deployment runtime, PICO/GMR interface and complete setup guides in docs/sim2real.md and docs/pico.md.

Use the teachers and train

Teachers require privileged observations and run in simulation. Use the corresponding stage, mode and checkpoint:

python -m brace_repro sim2sim --stage exert --mode exert \
  --checkpoint ../brace-models/artifacts/teachers/exert/last.ckpt \
  --motion ../brace-models/data/motions/smoke.pt \
  --force 3 0 0 --torque 0.1 0 0 \
  --steps 100 --output runs/teacher-exert

python -m brace_repro sim2sim --stage comp --mode comp \
  --checkpoint ../brace-models/artifacts/teachers/comp/last.ckpt \
  --motion ../brace-models/data/motions/smoke.pt \
  --force 3 0 0 --torque 0.1 0 0 \
  --steps 100 --output runs/teacher-comp

Teacher training scripts are scripts/train_exert_teacher.sh and scripts/train_comp_teacher.sh. Student distillation uses scripts/distill_student.sh with explicit --teacher-exert and --teacher-comp paths to these downloaded checkpoints. For fresh training or fine-tuning, follow docs/training.md in the source snapshot; training needs Isaac Sim 5.1.0, IsaacLab 2.3.0, and an NVIDIA GPU. Pretrained models do not require job runtime or another research checkout.

Data, validation and limitations

Training used a packed G1 locomotion/upper-body manipulation motion library with 58,028 clips, terrain variation, commanded hand wrenches and external disturbances. The full motion library is not included in this model release, and its redistribution rights remain unverified. The included data/motions/smoke.pt is a procedurally generated static standing reference, not a training-data subset. Its generator uses only the robot definition and standing joint targets and reads no recorded motions. It is provided under Apache-2.0 for execution checks, with provenance in data/motions/smoke.provenance.json. It is not a performance benchmark or a replacement training library. Replacing the original training data changes the training experiment. The original bundles retain inference configs, weights and training counters, rather than complete original training logs or simulator/RNG state; exact historical training replay is not established.

The cleaned public checkout passed 50 tests, 15 CPU pipeline cases with the procedural fixture, and six deployment simulation cases totaling 650 steps. Earlier runtime checks also included short GPU training in all three stages; those earlier checks used local training data that is not distributed. Checkpoint tensors are unchanged; the SafeTensors exports were checked tensor by tensor. The packaged student passed deployment preflight and a 100-step MuJoCo/ONNX combined-wrench check with the procedural fixture. These short checks do not establish held-out performance, complete retraining or physical robot readiness. See validation.json for the release record.

The robot is the 29-DoF Unitree G1. Teachers use privileged simulator inputs and are not hardware policies. Student deployment requires compatible robot assets, PD gains, motion references, online reference adaptation and state/history conventions. PyTorch checkpoint/config files use pickle; use the included BRACE loader for these trusted release files. SafeTensors provides a pickle-free copy of every model tensor.

License and citation

The BRACE model weights are released under Apache-2.0. The bundled source retains its Apache-2.0, MIT and CC-BY-4.0 third-party notices; see NOTICE and vendor licenses inside the source archive. Motion data and robot asset upstream terms remain separate.

Please cite the BRACE paper. BibTeX is provided in citation.bib.