---

name: lie-tensor description: "Use for PyPose LieTensor and manifold computation: choose SO3, SE3, Sim3, or RxSO3 group/algebra representations; construct, batch, convert, compose, act, retract, differentiate, and diagnose their operations." disable-model-invocation: true metadata: disco-role: operating license: Apache 2.0

PyPose LieTensor

Use this skill when a task needs differentiable 3D transformation or tangent-space math with PyPose: rotations, rigid poses, similarity transforms, scaled rotations, Lie algebra perturbations, coordinate conversions, manifold batching, or gradients. Start by deciding whether each value is a group element (a transform that can compose and act on points) or an algebra element (a local/tangent vector that can be exponentiated).

This skill is intentionally limited to the LieTensor surface. Route second-order optimizer orchestration, GN/LM/solver/scheduler/kernel workflows to optimization; route EKF/UKF/PF, dynamics, controls, IMU, EPnP, and ICP to robotics-modules; route projection, splines, filtering/downsampling, trajectory metrics, and evaluation to geometry-evaluation.

Operating contract

• Import with import torch and import pypose as pp.
• Keep the final dimension as the representation embedding dimension and use lshape for the batch/item shape.
• Use the matching group and algebra type; do not infer an algebra from an ordinary tensor after .tensor() has removed its ltype.
• Keep inputs on one device and in one floating dtype before calling manifold operations. Use the bundled scripts/lietensor_smoke.py for a small, deterministic sanity check before a larger experiment.
• Treat a raw constructor as a typed view of supplied data, not as a validation or optimization recipe. Prefer identity_*, randn_*, or Exp for values with known manifold semantics.

Representation and shape rules

A LieTensor has ordinary shape == lshape + (embedding_dimension,). Its ltype carries the embedding dimension (storage), the manifold dimension (local coordinates), and whether it is a group or algebra. For example, a batch of N x M SE(3) items has lshape == (N, M) and shape == (N, M, 7). lview(*new_lshape) changes only the hidden batch shape and retains the type; ordinary view exposes the final representation dimension.

Object	Kind	Stored final coordinates	Embedding	Manifold/algebra dimension
SO3 / SO3_type	group	[qx, qy, qz, qw] unit quaternion	4	3
so3 / so3_type	algebra	axis-angle [phi_x, phi_y, phi_z]	3	3
SE3 / SE3_type	group	[tx, ty, tz, qx, qy, qz, qw]	7	6
se3 / se3_type	algebra	[tau_x, tau_y, tau_z, phi_x, phi_y, phi_z]	6	6
Sim3 / Sim3_type	group	[tx, ty, tz, qx, qy, qz, qw, s]	8	7
sim3 / sim3_type	algebra	[tau_x, tau_y, tau_z, phi_x, phi_y, phi_z, sigma]	7	7
RxSO3 / RxSO3_type	group	[qx, qy, qz, qw, s]	5	4
rxso3 / rxso3_type	algebra	[phi_x, phi_y, phi_z, sigma]	4	4

For group types, quaternions are stored in xyzw order. se3 and sim3 translation coordinates are Lie-algebra coordinates: Exp applies the relevant left Jacobian (or Sim(3) W matrix) before producing group translation. For rxso3 and sim3, the final algebra scale coordinate is log-scale and the group scale is positive after Exp (s = exp(sigma)). Sim(3) matrices follow [s R, t; 0, 1], not the alternate convention with 1/s in the last entry.

Core API

Construct, identify, and sample

Use either the explicit constructor or the aliases:

x = pp.LieTensor(data, ltype=pp.se3_type)  # exact typed construction
x = pp.se3(data)                            # preferred algebra alias
X = pp.SE3(data)                            # preferred group alias
I = pp.identity_SE3(2, 3, dtype=torch.float64, device=device)
z = pp.randn_so3(4, requires_grad=True, dtype=dtype, device=device)
Z = pp.randn_SE3(4, dtype=dtype, device=device)
I_like = pp.identity_like(Z)
Z_like = pp.randn_like(Z)

The *lsize arguments describe lshape, not the final embedding. Thus pp.identity_SE3(2, 3) has shape (2, 3, 7), while a single identity has shape (7,). Explicit SO3/SE3/Sim3/RxSO3 data should already have a final dimension of 4/7/8/5. Explicit algebra data should have 3/6/7/4.

Maps and group operations

• a.Exp() or pp.Exp(a) maps algebra to the corresponding group and changes final dimension (3→4, 6→7, 7→8, 4→5).
• X.Log() or pp.Log(X) maps group to algebra and reverses that dimension. The operation is differentiable and uses stable small-angle branches.
• X.Inv() or pp.Inv(X) computes a group inverse. a.Inv() is the convenient algebra negation, not a group-theoretic inverse.
• X @ Y or pp.Mul(X, Y) composes two matching group types. X * Y is also supported for matching group LieTensors. Algebra a * scalar is elementwise tangent scaling; do not use group * as a substitute for a scalar update.
• X @ p, X.Act(p), or pp.Act(X, p) acts on a tensor whose final coordinate dimension is 3 (Euclidean point) or 4 (homogeneous point). A 4-vector keeps its homogeneous final coordinate. Batch dimensions broadcast, so one transform can act on many points or many transforms can act on one point.
• X.Retr(a) / pp.Retr(X, a) returns a.Exp() @ X and requires a group X with its corresponding algebra direction a.
• X.Adj(a) transports a matching tangent vector and satisfies X @ a.Exp() == X.Adj(a).Exp() @ X (up to numerical tolerance). X.AdjT(a) satisfies a.Exp() @ X == X @ X.AdjT(a).Exp().
• X.Jinvp(a) applies the inverse left Jacobian to a matching algebra vector. It is useful for local/BCH-style tangent calculations; it is not a generic matrix inverse. In the inspected release, Jr() is implemented for so3 and SO3 and returns their right-Jacobian matrix; verify availability before requesting it on the other Lie types.
• pp.add(X, delta) / X + delta is a left tangent perturbation for a group; for an algebra it is ordinary addition. The group's embedded storage is wider than its tangent dimension, so the unused tail of a group perturbation is ignored by the manifold update.

Use @ for group composition and point action when the operand type makes the intent clear; use .Act() when an explicit point-action call improves readability. Group-group composition requires matching Lie types; convert explicitly rather than relying on a raw tensor or an accidental quaternion/scale layout.

Conversions and views

• .tensor() / pp.tensor(X) returns the underlying ordinary tensor and removes LieTensor semantics. Re-wrap it with the correct alias or LieTensor(..., ltype=...) before calling manifold methods.
• .matrix() / pp.matrix(X) returns a batched matrix. SO3/so3 use (*, 3, 3); SE3/se3, Sim3/sim3, and RxSO3/rxso3 use (*, 4, 4). For algebra inputs, matrix() exponentiates first.
• .translation(), .rotation(), and .scale() return the corresponding parts while preserving batch shape. Translation has final size 3, rotation is an SO3 LieTensor with final size 4, and scale has final size 1. Types without a part return a documented neutral value: zero translation for SO3/RxSO3 and unit scale for SO3/SE3.
• .euler() returns roll, pitch, yaw in radians using x-y-z order. Euler angles are not unique and are singular near gimbal lock; use the rotation/group representation for stable storage.
• pp.euler2SO3(euler) maps (*, 3) roll/pitch/yaw to (*, 4) SO3. pp.quat2unit normalizes a group quaternion and rejects an all-zero quaternion.
• pp.mat2SE3(mat, check=True, rtol=1e-5, atol=1e-5) accepts (*,3,3), (*,3,4), or (*,4,4), takes the top-left rotation and the translation column when present, and returns (*,7) SE3. The related mat2SO3, mat2Sim3, mat2RxSO3, and from_matrix(mat, ltype=...) select other group types. Keep check=True for untrusted matrices; check=False only when the upstream invariant has already been established. A noncanonical last row in a 4x4 input is warned about, not used to compute the pose.
• pp.vec2skew(v) maps (*,3) to (*,3,3). pp.is_lietensor and pp.is_SE3 are checks for typed objects; call them only after establishing that the value is a LieTensor.

Autograd, parameters, dtype, and device

All ordinary PyTorch tensor attributes and autograd operations are supported. Create differentiable leaves with requires_grad=True in a factory or typed algebra tensor, then call backward() on a scalar loss. The gradient of a group is represented in its embedding storage; tangent updates use the corresponding manifold coordinates rather than treating quaternion storage as four independent rotation degrees of freedom.

pp.Parameter(data=None, requires_grad=True, sjac=False) is a PyTorch parameter wrapper. If data is a LieTensor, it retains its ltype; if data is a regular Tensor, it is an ordinary nn.Parameter. sjac=True is only for sparse Jacobian tracing and requires the optional backend; route sparse GN/LM construction to optimization instead of implementing optimizer orchestration here. A LieTensor parameter can still be used in a normal differentiable module without sjac.

Select one floating dtype and device for all related values:

device = torch.device("cuda" if torch.cuda.is_available() else "cpu")
dtype = torch.float64
xi_data = torch.tensor([0.1, -0.2, 0.05, 0.02, 0.03, -0.01],
                       device=device, dtype=dtype, requires_grad=True)
xi = pp.se3(xi_data)
X = xi.Exp()
points = torch.randn(8, 3, device=device, dtype=dtype)
loss = X.Act(points).square().mean()
loss.backward()  # xi_data is the differentiable leaf

Factories accept PyTorch dtype, device, requires_grad, and generator-like arguments. CUDA LieTensor operations are supported when the installed PyTorch build and device support them; the bundled smoke defaults to CPU and exits with a clear error if an explicitly requested device is unavailable. Avoid mixing CPU and CUDA operands or float32 and float64 operands in one operation. Float16 on CPU and near-singular conversions are not general-purpose validation targets.

Avoid in-place writes on leaves or tensors needed by autograd. For identity updates use identity_() only on a safe mutable buffer. For repeated or batched operations prefer non-in-place cumprod, cummul, or cumops; their _ variants mutate the input. torch.cat, stack, split, indexing, to, view, reshape, and lview preserve LieTensor type where PyPose supports the operation, but inspect isinstance(out, pp.LieTensor) and out.ltype after unfamiliar PyTorch transforms.

Verification checklist

Before handing a LieTensor workflow to a downstream task:

1. Assert the selected final representation dimension and lshape; check that group/algebra types are paired (SE3 with se3, etc.).
2. Run Log(Exp(a)) or Exp(Log(X)) on a small, non-singular, deterministic fixture. Compare typed tensor values with a tolerance appropriate to dtype.
3. Check composition/inverse with the identity and, when relevant, check the adjoint identity stated above.
4. Check point action with both a broadcast Euclidean point and a homogeneous point if the workflow uses both. Verify the output's final dimension.
5. Check matrix conversion with mat2SE3(..., check=True) or the matching converter and verify rotation orthogonality/determinant and translation.
6. Backpropagate a scalar point-action or map loss and assert finite, expected gradient shapes. If using Parameter, assert it remains a typed LieTensor.
7. Repeat the smallest check on the requested dtype/device; do not claim CUDA or optional sparse support from a CPU-only run.

Run the bundled scripts/lietensor_smoke.py --help through the resolved skill path from the skill root or any other working directory. The helper has no network, file-write, random-data, or optimizer dependency.

Evidence boundary and routing

This skill captures the public PyPose LieTensor API, typed representations, conversion rules, differentiable operations, and safe synthetic checks. It does not prescribe optimizer loops, sparse backend setup, robot-state module composition, projection/trajectory metrics, spline fitting, or evaluation protocols. Those tasks belong to the sibling ids named at the top of this file.