Base Lifters

Overview

There are a couple of lifters that serve as a basis for new lifters. The most basic one is StateLifter, which is generally the best starting point.

For specific problems, there are a couple of abstract classes that were developed to ease the development. In particular, we have:

Basics

Below are some general notes about terminology that may be useful in understanding the code and building your own lifters.

  • theta is the original (low-dimensional) state variable.

  • x is the lifted (higher-dimensional) state variable.

  • A are equality constraints

  • B are inequality constraints

  • var_dict refers to the dictionary of variable name - variable size pairs.

  • param_dict is used to factor out parameters when creating templates. It also comes in name - variable size pairs.

StateLifter

class popcor.base_lifters.StateLifter(level='no', param_level='no', d=2, variable_list=None, robust=False, n_outliers=0, n_parameters=1)[source]

Bases: BaseClass

get_A_known(add_redundant: bool = False, var_dict: dict | None = None, output_poly: bool = False) → list[source]

Construct the matrices defining the known equality constraints.

Parameters:

  • add_redundant – if True, add redundant constraints.

  • var_dict – if provided, return only the matrices that involve these variables.

  • output_poly – if True, return the matrices in PolyMatrix format.

get_B_known() → list[source]

Construct the matrices defining the known inequality constraints.

get_Q(output_poly: bool = False, noise: float | None = None)[source]

Construct the cost matrix Q.

Parameters:

  • noise – set the noise level, if appropriate.

  • output_poly – if True, return the matrix in PolyMatrix format.

Returns:

the cost matrix as a sparse matrix or PolyMatrix.

get_cost(theta, y: ndarray | None = None) → float[source]

Compute the cost of the given state theta. This uses the simple form x.T @ Q @ x. Consider overwriting this for more efficient computations.

get_theta(x)[source]

Inverse of get_x: given lifted vector x, extract elements corresponding to theta.

Note that x should not contain the homogeinized element x[0] = 1

get_x(theta: ndarray | None = None, var_subset: Iterable | None = None, **kwargs) → ndarray

Get the lifted state vector x.

Parameters:

  • theta – if given, use this theta instead of the ground truth one.

  • var_subset – list of parameter keys to use. If None, use all.

Returns:

lifted vector x

local_solver(t0, y: ndarray | list | None = None, *args, **kwargs)[source]

Default local solver that uses IPOPT to solve the QCQP problem defined by Q and the constraints matrices. Consider overwriting this for more efficient solvers.

sample_parameters(theta: ndarray | None = None) → dict[source]

Create random set of parameters. By default, there are no parameters so this function just returns {self.HOM: 1.0}.

abstract sample_theta() → ndarray[source]

Randomly sample a feasible state theta. This function must be implemented by the inheriting class.

StereoLifter

class popcor.base_lifters.StereoLifter(n_landmarks, d, level='no', param_level='no', variable_list=None)[source]

Bases: StateLifter, ABC

StereoLifter is a general lifter class for the stereo localization problem, supporting both 2D and 3D cases.

See Stereo2DLifter for 2D and Stereo3DLifter for 3D.

RobustPoseLifter

class popcor.base_lifters.RobustPoseLifter(n_outliers=0, level='no', param_level='no', d=2, n_landmarks=3, variable_list=None, robust=False, beta=0.1)[source]

Bases: StateLifter, ABC

RobustPoseLifter is a general class for point-to-point, point-to-line, and point-to-plane registration problems, with starndard or robust loss functions.

The goal is to regress an unknown pose based on extrinsic measurements.

See class:~popcor.examples.WahbaLifter for point-to-point registration and MonoLifter) for point-to-line registration.

Implemented lifting functions are:

  • xwT: \(x \otimes w\)

  • xxT: \(x \otimes x\)

RangeOnlyLifter

class popcor.base_lifters.RangeOnlyLifter(n_positions, n_landmarks, d, W=None, level='no', variable_list=None, param_level='no')[source]

Bases: StateLifter, ABC

Range-only localization base class, in 2D or 3D.

This is base class for different flavors of the range-only localization problem, where the goal is to estimate positions from distance measurements to fixed landmarks.

See RangeOnlyNsqLifter and RangeOnlySqLifter for concrete implementations.

PolyLifter

class popcor.base_lifters.PolyLifter(degree, param_level='no')[source]

Bases: StateLifter

Simple univariate polynomial lifter, mostly for testing and pedagogical purposes.