Skip to content

Commit 295e225

Browse files
LemonPiclaude
andcommitted
Document analytical FK backward and escape hatch in README
Adds a section explaining the analytical geometric Jacobian used by forward_kinematics_tensor for ~9x faster backward on GPU, its torch.compile compatibility, and the analytical_grad=False escape hatch for higher-order gradients or chain parameter differentiation. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent b22e68b commit 295e225

1 file changed

Lines changed: 35 additions & 1 deletion

File tree

README.md

Lines changed: 35 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -149,6 +149,39 @@ pos.norm().backward()
149149
# now th.grad is populated
150150
```
151151

152+
### Analytical FK Backward
153+
154+
`forward_kinematics_tensor` uses an **analytical geometric Jacobian** for the backward pass by default.
155+
Instead of replaying all the forward ops through autograd, it computes `d(transform)/d(joint_angles)`
156+
directly from joint axes and the kinematic tree structure. This is ~9x faster than standard autograd
157+
on GPU for large batch sizes.
158+
159+
```python
160+
import torch
161+
import pytorch_kinematics as pk
162+
163+
chain = pk.build_serial_chain_from_urdf(open("kuka_iiwa.urdf").read(), "lbr_iiwa_link_7")
164+
165+
th = torch.randn(1000, 7, requires_grad=True)
166+
T_all = chain.forward_kinematics_tensor(th) # (num_frames, 1000, 4, 4)
167+
168+
# backward uses the analytical Jacobian automatically
169+
loss = T_all.sum()
170+
loss.backward() # th.grad is populated, ~9x faster than autograd on GPU
171+
```
172+
173+
The analytical backward is compatible with `torch.compile(fullgraph=True)` — all arguments crossing the
174+
autograd boundary are plain tensors.
175+
176+
**Escape hatch**: set `analytical_grad=False` when you need:
177+
- **Higher-order gradients** (`create_graph=True` / double backward)
178+
- **Gradients w.r.t. chain parameters** (e.g. differentiating through link offsets for calibration)
179+
180+
```python
181+
# Standard autograd — supports create_graph=True and parameter gradients
182+
T_all = chain.forward_kinematics_tensor(th, analytical_grad=False)
183+
```
184+
152185
We can load SDF and MJCF descriptions too, and pass in joint values via a dictionary (unspecified joints get th=0) for non-serial chains
153186
```python
154187
import math
@@ -186,7 +219,8 @@ The FK computation can be compiled with `torch.compile(fullgraph=True)` for sign
186219
especially for applications that call FK thousands of times (e.g. inverse kinematics, trajectory optimization).
187220

188221
Use `forward_kinematics_tensor`, a compile-friendly variant that accepts and returns raw tensors
189-
instead of dicts and `Transform3d` objects:
222+
instead of dicts and `Transform3d` objects. The analytical FK backward (see above) works under
223+
`torch.compile` — both forward and backward are fully traced:
190224

191225
```python
192226
import torch

0 commit comments

Comments
 (0)