Shortcuts

pypose.add

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

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.

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])

Docs

Access documentation for PyPose

View Docs

Tutorials

Get started with tutorials and examples

View Tutorials

Get Started

Find resources and how to start using pypose

View Resources