Imported from yolkarian/SAPIEN (
AGENTS.md). Install upstream withnpx skills add yolkarian/SAPIEN. Copyright stays with the author.
AGENTS.md
First Message
If the user has not identified a concrete subsystem, read readme.md first, then ask which area to work on.
When the area is clear, read the relevant docs in parallel before editing:
- Basics:
docs/source/tutorial/basic/index.md - Rendering:
docs/source/tutorial/rendering/index.md - Robotics:
docs/source/tutorial/robotics/index.md - Reinforcement learning:
docs/source/tutorial/rl/index.md - Motion planning:
docs/source/tutorial/motion_planning/index.md - Migration and compatibility:
docs/source/tutorial/migration/index.md
If documentation and checked-in automation disagree, prefer the repository scripts and CI workflow over prose in readme.md.
Repo Overview
- SAPIEN is a C++20 robotics simulator with optional CUDA features and Python bindings distributed as the
sapienpackage. - Current documentation lives under
docs/source. docs/source-0.1is legacy documentation. Do not update it unless the task explicitly targets legacy docs.- Main code areas:
src/: core C++ implementation, includingphysx,sapien_renderer, and shared utilitiesinclude/sapien/: public C++ headerspython/pybind/: pybind11 bindingspython/py_package/: packaged Python API, wrappers, examples, utilities, and sensor assetspinocchio/: Pinocchio integrationcmake/: dependency and package config helpersvulkan_shader/andvulkan_library/: runtime rendering assets and bundled librariestest/: C++ unit testsunittest/: Pythonunittestsuitemanualtest/: interactive/manual validation scriptsassets/: bundled models, robots, and data files
Development Rules
- Ask the user and get approval before writing or modifying any
AGENTS.md, including documentation-sync edits. - Keep public C++ headers, C++ implementation, Python bindings, and Python wrappers in sync when an API crosses those layers.
- Every API change—including additions, removals, renames, signature/default changes, and behavior, lifecycle, or ownership changes—must update the checked-in SAPIEN skill under
docs/skills/sapien-simulation/in the same change. Keep its workflow guidance, API tables, anddocs/api/api-changes.mdconsistent with the source and stubs. - After updating the checked-in SAPIEN skill, sync it to
~/.agents/skills/sapien-simulation/only if that installed skill directory already exists; do not create it when absent. The checked-in directory remains the source of truth. - When adding a new feature, add appropriate automated tests with it. Prefer Python
unittest/coverage for Python-facing behavior and C++test/coverage for native behavior. - For Python-facing API changes, inspect all affected surfaces:
include/sapien/**src/**python/pybind/*.cpppython/py_package/**
- Preserve import paths and example module paths under
python/py_package. The documented smoke tests usesapien.example.*. - Treat
manualtest/as manual validation only. Many scripts require a GPU, Vulkan, and sometimes an onscreen display. - Do not casually remove or rewrite large assets, shader directories, bundled libraries, or legacy docs.
Style
- Follow
.editorconfig:*.h,*.cpp: 2 spaces*.rst: 3 spacesCMakeLists.txt: 4 spaces
- Follow
.clang-formatfor C++ changes. The configured column limit is 99. - Keep Python style consistent with surrounding files. This repo does not expose a stricter top-level formatter config in the checked-in docs.
- Python should be type-annotated and well-documented with comments.
Build And Install
- Local and agent validation builds must use at most 4 compile jobs.
- Apply the limit at invocation time with
CMAKE_BUILD_PARALLEL_LEVEL=4or--jobs 4. - Keep repository scripts caller-configurable; do not hard-code or default the scripts themselves to 4 jobs.
- Apply the limit at invocation time with
- Initialize submodules before any source build:
git submodule update --init --recursive
- Preferred wheel build in Docker:
- Use the latest
yolkarian/sapien-build-env:<tag>image used by the checked-in CI/scripts; check.github/workflows/build.ymlandscripts/docker_build_wheels.shbefore building. - If the Docker image is not present locally, pull it from the registry first, matching GitHub Actions' container behavior:
docker image inspect yolkarian/sapien-build-env:<tag> >/dev/null 2>&1 || docker pull yolkarian/sapien-build-env:<tag>
- Default new-feature wheel build: compile the Python 3.11 wheel with parallelism limited to 4:
CMAKE_BUILD_PARALLEL_LEVEL=4 ./scripts/docker_build_wheels.sh 311
- General form:
CMAKE_BUILD_PARALLEL_LEVEL=4 ./scripts/docker_build_wheels.sh [39|310|311|312|313]
- Use the latest
- Direct build script used by CI:
./scripts/build.sh [39|310|311|312|313] [--debug] [--profile] [--jobs N]- When compiling directly, limit parallelism to 4 by default for validation builds:
./scripts/build.sh 311 --jobs 4
- Local install helpers exist at
scripts/install.shandscripts/install_debug.sh, but CI does not use them. Inspect them before relying on them for validation automation. setup.pydrives the wheel build and invokes CMake for the native library.- Current PhysX baseline is
107.3-physx-5.6.1. - CUDA support is controlled by
CUDA_PATH. If it is unset,setup.pybuilds withSAPIEN_CUDA=OFF. - PhysX 5.6.1 GPU builds require a CUDA toolkit and driver stack compatible with CUDA
>= 12.8. - If the matching
sapien-sim/physx-precompiledrelease asset is unavailable, prefer settingSAPIEN_PHYSX5_DIRto a locally built PhysX tree instead of relying on FetchContent.
Validation
- Use the narrowest validation that matches the change. Full wheel builds are expensive.
- New features must include matching automated tests unless there is a clear documented reason they cannot be tested automatically.
- After adding a new feature, the default validation path is to build the Python 3.11 wheel in the latest
sapien-build-envimage with build parallelism limited to 4, then validate that wheel inside a fresh mamba environment. - Create a clean mamba environment for Python validation, install the newly built wheel, and run targeted tests/smoke tests there, for example:
mamba create -n sapien-wheel-py311 python=3.11 -ymamba run -n sapien-wheel-py311 python -m pip install wheelhouse/sapien-*-cp311-*.whlmamba run -n sapien-wheel-py311 bash -c 'cd unittest && python -m unittest discover .'
- Run Python tests from
unittest/: existing resource paths are relative to that directory. - On drivers with repeated Vulkan-instance initialization failures, run ordinary test modules in separate processes. OOM recovery validation must keep its entire recovery sequence in one process; separate processes do not validate recovery. Run deliberate VRAM-exhaustion tests separately from builds and other workloads.
test_gpu_oomis opt-in withSAPIEN_TEST_GPU_OOM=1and needs an isolated idle GPU plus a process timeout. It makes one device-memory reservation, leaves 128 MiB GPU headroom, and attempts one bounded 256 MiB PhysX heap. Use a memory-limited container and a process timeout; never exhaust memory by creating giant pinned-host heaps. - Python tests live under
unittest/and use the standard libraryunittestrunner. - C++ tests live under
test/and require configuring CMake with-DSAPIEN_BUILD_TEST=ON, then building thesapien_testtarget. - Documented runtime smoke tests:
python -m sapien.example.offscreenpython -m sapien.example.hello_world
- Be careful with rendering checks on headless machines:
- offscreen examples may emit display warnings but still succeed
- onscreen viewer checks require a display-capable environment
Documentation
- Build docs from
docs/:make -C docs htmlmake -C docs apidoc
docs/Makefileregenerates API docs from the installedsapienpackage, so doc builds that rely on API pages assume the package imports correctly.- If you change a public Python API, update the relevant tutorial or API-facing docs in
docs/source. - When examples or module names change, verify the docs still point at real files in
python/py_package/example/.
CI Notes
- GitHub Actions builds Linux wheels in
yolkarian/sapien-build-env:<tag>and Windows wheels separately. Check.github/workflows/build.ymlfor the current/latest image tag instead of relying on stale hard-coded values. - When build behavior, Python version support, or packaging details matter, check:
.github/workflows/build.ymlscripts/build.shscripts/docker_build_wheels.shsetup.py
- Prefer these files over older README snippets if they disagree.
Git Safety
- This repo may contain user changes, large binary assets, and initialized submodules. Do not use destructive cleanup commands unless explicitly asked.
- Keep commits and staging scoped to the files you actually changed.
