Skip to content

CLAUDE.md

Latest commit

 

History

History
56 lines (47 loc) · 3.43 KB

CLAUDE.md

File metadata and controls

56 lines (47 loc) · 3.43 KB
Raw

MPCGPU agent guide

Read docs/README.md, docs/development.md and the local, gitignored docs/open-tasks/ (todo list, handoffs, audit and timing notes; not in clones). This repository contains MPCGPU. Model inputs, code generation and tests are self-contained. GBD-PCG, GRiD and GLASS are pinned submodules; do not edit their upstream code here. GBD-PCG is developed in A2R-Lab/GBD-PCG and compiled here against MPCGPU's top-level GLASS (-IGLASS); its nested GBD-PCG/GLASS pin must equal the top-level pin (host test), so bump both together. Change GBD-PCG upstream, then bump the pin here with a receipt.

Standing rules

  • Shared box: GPU correctness is allowed, timing requires an explicitly assigned exclusive window. No clocks/governors changes or benchmark launches by default.
  • Sequential nvcc only; use a 36 GiB/no-swap systemd scope for correctness builds: systemd-run --user --scope -p MemoryMax=36G -p MemorySwapMax=0 --same-dir ....
  • Preserve other agents' files/processes. Do not run sibling project workloads.
  • Short single-line commits, no Co-Authored-By. Hold pushes, PRs, main merges, releases and website deployment until explicitly cleared.
  • The project page is docs/index.html; GitHub Pages serves main /docs, so any push to main that touches docs/ republishes http://a2r-lab.org/MPCGPU/ (see docs/website.md).
  • Working notes, todo lists and handoffs go in the gitignored docs/open-tasks/; never commit them elsewhere under docs/, which is published. Current todo SSOT: docs/open-tasks/open_todos_2026-10-01.md.
  • Commit source -> full clean-source GPU receipt -> receipt commit -> authorized push -> green CI. Do not edit receipts, carry old results, or sign subsets.
  • Never reuse timing output after a failed run. Read the timing section of docs/development.md (and docs/open-tasks/timing.md, if present locally) before timing.

Architecture and traps

GRiD generation uses tools/iiwa14.urdf and an explicit minimal algorithm list, without collision/contact or an embedded GLASS copy. Check reproducibility with make check-codegen. Exactly pin dependencies in tools/dependencies.json; update the gitlinks too. Do not run parent submodule update before staging a new pin: it resets the submodule to the old index gitlink.

The SQP loop is shared (include/common/sqp.cuh); pcg/sqp.cuh and qdldl/sqp.cuh are linear-system backends. Keep backend slot order fixed and check state hashes after edits. Owned CUDA uses glass::block:: explicitly. GBD-PCG stays cooperative/grid-wide; GLASS's single-block PCG is not a replacement. Scratch includes all three halo slots, including N=1. Device launch dimensions are compile-time specializations.

Reusable SqpWorkspace owns streams, handle and fixed allocation slots per backend/dimensions/device. It is synchronous and cannot be shared concurrently. QDLDL's symbolic structure is reused, its numeric factorization is not. Keep fresh/reused state-hash parity gates when changing workspace layout.

Tracking uses L2 EE-position error throughout. Corrected dynamics, terminal-cost shared-memory alias fix and named EE frame invalidate comparisons with older fixtures/results. August historical numbers are not current performance claims. PCG eta can under-report true residual on poorly conditioned systems; do not silently loosen gates or describe eta convergence as a true-residual guarantee.

See docs/development.md for builds/receipt commands. Python is tooling, not a high-level solver wrapper.