robotics-modules
Use PyPose's differentiable robotics modules for discrete dynamics, Bayesian state estimation, LQR/MPC control, IMU preintegration, PnP/ICP pose solving, and rotation geodesic loss; choose constructors and tensor contracts from the bundled references, validate shapes/covariances/units, and compose modules without confusing them with primitive manifold math, generic optimization, or geometry metrics.
- License 许可
- Apache-2.0
- 最近更新
- 2026-09-03
- Stars
- ★ 351
- Forks
- 27
01 前言 Front Matter
- name
- robotics-modules
- license
- Apache 2.0
- metadata
- { "disco-role": "operating" }
- description
- Use PyPose's differentiable robotics modules for discrete dynamics, Bayesian state estimation, LQR/MPC control, IMU preintegration, PnP/ICP pose solving, and rotation geodesic loss; choose constructors and tensor contracts from the bundled references, validate shapes/covariances/units, and compose modules without confusing them with primitive manifold math, generic optimization, or geometry metrics.
- disable-model-invocation
- true
02 资源文件 7
- 参考文档references/api-reference.md7.4 KB
- 参考文档references/control-and-dynamics.md5.7 KB
- 参考文档references/imu-and-geometric-solvers.md6.6 KB
- 参考文档references/state-estimation.md6.9 KB
- 参考文档references/troubleshooting.md5.9 KB
- 脚本scripts/filter_smoke.py3.3 KB
- 脚本scripts/icp_smoke.py1.8 KB
03 SKILL.md 正文
PyPose robotics-modules
Use this skill when a Researcher needs PyPose's high-level robotics modules in
pypose.module: system models (System, LTI, LTV, NLS), EKF/UKF/PF,
LQR/MPC, IMUPreintegrator, EPnP, ICP, or GeodesicLoss. The module
implementations are differentiable PyTorch nn.Modules, but several modules
also mutate a clock, integration state, or stopping planner. Treat those state
and shape contracts as part of the API.
Scope boundary
- Included: constructors, forward signatures, rightmost feature dimensions, leading-batch broadcasting, time and reset behavior, covariance contracts, dynamics/filter/control composition, IMU units and frame conventions, PnP and ICP initialization, and solver-stepper diagnostics.
- Excluded: primitive LieTensor/manifold algebra (
lie-tensor), generic Gauss--Newton/Levenberg--Marquardt optimization (optimization), and geometry/spline/trajectory metrics (geometry-evaluation).EPnP(refine=True)may call its own internal refinement; use the PnP contract here rather than treating that implementation detail as a general optimizer workflow.
Read the smallest relevant reference before writing code:
- api-reference.md for verified signatures and exact call/return contracts.
- state-estimation.md for
System/NLSmodels and EKF/UKF/PF covariance and shape rules. - control-and-dynamics.md for LTI/LTV, LQR, MPC, horizon layouts, and stepper behavior.
- imu-and-geometric-solvers.md for IMU, EPnP, ICP, and geodesic rotation loss.
- troubleshooting.md for failure diagnosis and safe recovery.
Operating workflow
-
Identify the module boundary. Decide whether the task needs a dynamic model, a state estimator, a controller, sensor preintegration, a geometric solver, or a rotation loss. Do not replace a module with primitive manifold operations unless the task explicitly needs those primitives.
-
Normalize shapes before constructing modules. Put features in the last dimension, matrices in the last two dimensions, and batch/time axes in leading positions. Make
dtypeanddeviceconsistent across model, covariance, costs, and observations. Do not rely on accidental broadcasting for state versus time axes. -
Build the dependency chain. A normal filtering chain is
NLS -> (EKF | UKF | PF); a control chain isNLS -> set_refpoint -> LQRinsideMPC; a sensor chain isIMUPreintegrator -> pose/velocity/positionconsumers.EPnPandICPeach return anSE3pose for a separate geometry-registration branch, whileGeodesicLosscompares rotations. -
Make mutable state explicit. Reset a dynamic model before replaying a trajectory. Reuse an IMU integrator only when its accumulation semantics are intended. Reuse a
ReduceToBason-like stepper only after itsreset(). Avoid concurrent calls through one mutable module. -
Check outputs, not just execution. Assert expected trailing shapes, finiteness, covariance symmetry/positive semidefiniteness within numerical tolerance, plausible units, and an error or cost that improves on a deterministic fixture. Use the bundled scripts for a quick CPU check:
From the
pyposeskill directory, run:python sub-skills/robotics-modules/scripts/filter_smoke.py python sub-skills/robotics-modules/scripts/icp_smoke.pyThe helpers can also be invoked by absolute path from any working directory.
Composition patterns
Dynamics and filtering
Subclass NLS, implement pure state_transition(state, input, t) and
observation(state, input, t), and call the model with (state, input) for one
step. NLS.forward evaluates both functions at the current clock and its hook
increments the clock afterwards. Call set_refpoint before reading A, B,
C, D, c1, or c2; this computes Jacobians at the selected state/input/time.
Then give the same model to one filter and call it with an estimate, a
measurement, an input, and a covariance. The filter's direct model evaluations
are not a substitute for adding process/measurement noise to the actual data.
For a linear problem, use LTI or a time-indexed LTV instead of making a
linear NLS; their matrices can be fed directly to LQR. See the exact time
semantics and observation timing in the references.
Control
Use LQR(system, Q, p, T) for one finite-horizon solve. Q covers the
concatenated [state, input] vector and p has the same final feature size.
Use MPC around the same system and costs when nonlinear dynamics require
relinearization. MPC.forward performs iterative LQR under no_grad, selects a
best iterate using its mutable stepper, and makes a final LQR call; set a small,
explicit stepper for tests and deterministic examples.
Sensor and pose branches
IMUPreintegrator consumes body-frame angular rates/accelerations and positive
finite time intervals, returning incrementally propagated pose, velocity,
position, and optionally a 9x9 covariance. EPnP estimates an SE3 from at
least four 3D/2D correspondences and camera intrinsics. ICP estimates an SE3
from source/target point clouds by nearest-neighbor matching and SVD; it is
local and initialization-sensitive. Keep these frame conventions documented at
call sites instead of silently composing poses in an inverse order.
Verification gates
Before handing off code that uses this skill:
- import and constructor signatures match api-reference.md;
- a minimal deterministic call succeeds from a clean current working directory;
- all tensors have declared trailing shapes and common dtype/device;
- filter
P,Q, andRare square in their intended state/observation spaces; - dynamics clock/reset and IMU accumulation/reset behavior are tested;
- LQR/ICP/MPC stepper limits are explicit for tests;
- geometric inputs meet point-count, intrinsics, non-degeneracy, and initialization requirements; and
- no smoke helper downloads data, plots, writes outside an explicitly selected output, or depends on the caller's working directory.
The references summarize the verified public module contracts and synthetic smoke scripts; a Researcher does not need the original source checkout or example files to use this sub-skill.
04 同仓库更多 Skills
passnet-triton-opt
Make a single PassNet Triton kernel fast AND numerically faithful: performance model (when a replacement can win at all), block/grid/warp tuning, autotune policy, launch overhead, and per-op numeric recipes to pass the dtype baseline tolerances. Use when a pass matches and is correct but speedup below expected, or when correctness fails by small numeric margins.
passnet-solve
END-TO-END playbook for solving one PassNet sample: analyze the computation graphs, decide the optimization strategy (what to fuse, what to replace, what to leave alone), drive the iteration loop, and maximize the sample score. This is the ENTRY skill — invoke it first for any PassNet optimization task; it tells you when to use passnet-pattern-fusion, passnet-triton-opt and passnet-feedback.
passnet-skill
PassNet GPU kernel optimization via compiler passes. Design and implement Triton-based optimization passes, create pass files under ./pass_dir/, self-evaluate with pass_evaluator, and iterate to maximize GPU speedup.
passnet-pattern-fusion
Author PassNet pass files: write patterns that actually MATCH the FX graph, pick fusion regions (which ops to absorb into one Triton kernel), and structure multi-pass submissions with the mandatory shared-dispatch architecture. Use when creating or fixing pattern()/replacement_args()/replacement_func() files, when a pass "failed to match", or when deciding how to fuse multiple kernels/ops.
passnet-orchestrate
Round/batch planning and decision support for PassNet graph optimization. Use for multi-sample triage, worker allocation, eval-budget policy, and post-eval keep/revert decisions. For solving one concrete sample end to end, use passnet-solve as the entry skill; consult this skill only when you need broader planning or a specific decision gate.
passnet-feedback
Fast, deterministic feedback for PassNet work: pre-flight pattern/match verification WITHOUT burning a GPU evaluation, per-node bottleneck analysis of a sample's graphs, and eval-log parsing into per-variant status + estimated score + failure classification. Use BEFORE every GPU evaluation (check_pattern), at the START of a sample (analyze_graph), and AFTER every evaluation (parse_eval_log).