pypose.add

class pypose.add(input, other, alpha=1)

Adds other, scaled by alpha, to input LieTensor.

Parameters:

• input (LieTensor) – the input LieTensor (Lie Algebra or Lie Group).

• other (Tensor) – the tensor to add to input. The last dimension has to be no less than the shape of the corresponding Lie Algebra of the input.

• alpha (Number) – the multiplier for other.

Returns:

the output LieTensor.

Return type:

LieTensor

\[\bm{y}_i = \begin{cases} \alpha * \bm{a}_i + \bm{x}_i & \text{if}~\bm{x}_i~\text{is a Lie Algebra} \\ \mathrm{Exp}(\alpha * \bm{a}_i) \times \bm{x}_i & \text{if}~\bm{x}_i~\text{is a Lie Group} \end{cases} \]

where \(\bm{x}\) is the input LieTensor, \(\bm{a}\) is the other Tensor to add, and \(\bm{y}\) is the output LieTensor.

Warning

For better readability, we suggest calling a + b instead of a.add(b) or pypose.add(a, b), which have the same behaviors.

Note

A Lie Group normally requires a larger space than its corresponding Lie Algebra, thus the elements in the last dimension of the other Tensor (treated as a Lie Algebra in this function) beyond the expected shape of the Lie Algebra are ignored. This is because the gradient of a Lie Group is computed as a left perturbation (a Lie Algebra) in its tangent space and is stored in the LieGroup’s LieTensor.grad, which has the same storage space with the LieGroup.

\[\begin{align*} \frac{D f(\mathcal{X})}{D \mathcal{X}} & \overset{\underset{\mathrm{def}}{}}{=} \displaystyle \lim_{\bm{\tau} \to \bm{0}} \frac{f(\bm{\tau} \oplus \mathcal{X}) \ominus f(\mathcal{X})}{\bm{\tau}} \\ & = \left.\frac{\partial\mathrm{Log}(f(\mathrm{Exp}(\bm{\tau})\times\mathcal{X})) \times f(\mathcal{X})^{-1})}{\partial \bm{\tau}}\right|_{\bm{\tau=\bm{0}}} \end{align*}, \]

where \(\mathcal{X}\) is a Lie Group and \(\bm{\tau}\) is its left perturbation.

See Eq.(44) in Micro Lie theory for more details of the gradient for a Lie Group.

This provides convenience to work with PyTorch optimizers like torch.optim.SGD, which calls function add_() of a Lie Group to adjust parameters by gradients (LieTensor.grad, where the last element is often zero since tangent vector requires smaller storage space).

See LieTensor() for types of Lie Algebra and Lie Group.

See Exp() for Exponential mapping of Lie Algebra.

Examples

The following operations are equivalent.

>>> x = pp.randn_SE3()
>>> a = torch.randn(6)
>>> x + a
SE3Type LieTensor:
tensor([-1.6089,  0.4184,  0.6621, -0.2098,  0.5383,  0.4794,  0.6606])
>>> pp.add(x, a)
SE3Type LieTensor:
tensor([-1.6089,  0.4184,  0.6621, -0.2098,  0.5383,  0.4794,  0.6606])
>>> pp.se3(a).Exp() @ x
SE3Type LieTensor:
tensor([-1.6089,  0.4184,  0.6621, -0.2098,  0.5383,  0.4794,  0.6606])
>>> x + torch.cat([a, torch.randn(1)])
SE3Type LieTensor:
tensor([-1.6089,  0.4184,  0.6621, -0.2098,  0.5383,  0.4794,  0.6606])