Represents a group of factors which will be processed together on the GPU. More...

#include <factor.hpp>

Inheritance diagram for graphite::FactorDescriptor< T, S, FTraits >:

Collaboration diagram for graphite::FactorDescriptor< T, S, FTraits >:

[legend]

Public Types
using	InvP = std::conditional_t< is_low_precision< S >::value, T, S >

using	Traits = FTraits

using	VertexDescriptorTuple = typename Traits::VertexDescriptors

using	VertexTypesTuple = transform_tuple_t< VertexDescriptorTuple, get_vertex_type >

using	VertexPointerTuple = transform_tuple_t< VertexDescriptorTuple, get_vertex_pointer_type >

using	VertexPointerPointerTuple = transform_tuple_t< VertexDescriptorTuple, get_vertex_pointer_pointer_type >

using	ObservationType = typename Traits::Observation

using	ConstraintDataType = typename Traits::Data

using	LossType = typename Traits::Loss

Public Types inherited from graphite::BaseFactorDescriptor< T, S >
using	InvP = std::conditional_t< is_low_precision< S >::value, T, S >

Public Member Functions
template<typename... VertexDescPtrs, typename = std::enable_if_t<sizeof...(VertexDescPtrs) == N>>
	FactorDescriptor (VertexDescPtrs... vertex_descriptors)
	Constructs a FactorDescriptor with the given vertex descriptors.

void	compute_error () override
	Computes the residuals across all factors in the descriptor.

void	compute_error_autodiff (StreamPool &streams) override
	Simultaneously computes the residuals and corresponding Jacobians using automatic differentiation.

void	compute_b_async (T b, const T jacobian_scales) override
	Computes the gradient vector b asynchronously.

void	compute_Jv (T out, T in, const T *jacobian_scales, StreamPool &streams) override
	Computes the product of the Jacobian matrix and a vector.

void	compute_Jtv (T out, T in, const T *jacobian_scales, StreamPool &streams) override
	Computes the product of the transposed Jacobian matrix and a vector.

void	flag_active_vertices_async (const uint8_t level) override

void	compute_jacobians (StreamPool &streams) override
	Computes the Jacobians using manual differentiation.

void	compute_hessian_block_diagonal_async (std::unordered_map< BaseVertexDescriptor< T, S > , thrust::device_vector< InvP > > &block_diagonals, const T jacobian_scales, cudaStream_t stream) override
	Computes the block diagonal of the Hessian matrix asynchronously.

void	compute_hessian_scalar_diagonal_async (T diagonal, const T jacobian_scales) override
	Computes the scalar diagonal of the Hessian matrix asynchronously.

size_t	get_num_descriptors () const override
	Returns the number of vertex descriptors (same as the number of vertices for each factor).

JacobianStorage< S > *	get_jacobians () override
	Returns the Jacobian storage for the factor.

void	reserve (size_t size)
	Reserves memory for the factor. Generally, you should always reserve the memory you need before adding factors, because reallocating GPU memory is expensive.

void	remove_factor (const size_t id)
	Removes a factor by its id.

size_t	add_factor (const std::array< size_t, N > &ids, const ObservationType &obs=ObservationType(), const S *precision_matrix=nullptr, const ConstraintDataType &constraint_data=ConstraintDataType(), const LossType &loss_func=LossType())
	Adds a factor to the descriptor.

void	set_active (size_t id, const uint8_t active_value)
	Sets the active state of a factor.

void	reset_active ()
	Resets the active state of all factors to 0x1.

size_t	internal_count () const
	Returns the number of all active and inactive factors.

size_t	active_count () const override
	Returns the number of active factors.

void	initialize_device_ids (const uint8_t optimization_level) override
	Initializes the device ids and a list of active factors.

void	to_device () override
	Prepares descriptor for GPU processing.

void	link_factors (const std::array< BaseVertexDescriptor< T, S > *, N > &vertex_descriptors)
	Links the factor to the given vertex descriptors. This is already called during construction.

template<std::size_t... I>
VertexPointerPointerTuple	get_vertices_impl (std::index_sequence< I... >)

VertexPointerPointerTuple	get_vertices ()
	Returns a tuple of vertex pointers.

void	initialize_jacobian_storage () override
	Allocates memory for the Jacobians.

virtual size_t	get_residual_size () const override
	Returns the size of the vector for all active and inactive residuals.

virtual T	chi2 () override
	Computes the chi-squared value for all active and inactive factors.

T	chi2 (const size_t id) const
	Returns the chi-squared value for a specific factor.

ConstraintDataType *	get_constraint_data (const size_t id)
	Returns the constraint data for a specific factor.

std::array< size_t, N >	get_vertex_ids (const size_t id) const
	Returns the vertex ids connected to a specific factor.

virtual void	scale_jacobians_async (T *jacobian_scales) override
	Scales the Jacobians asynchronously.

virtual bool	use_autodiff () override
	Determines whether to use automatic differentiation based on the traits of the factor.

virtual void	set_jacobian_storage (const bool store)
	Sets whether to store the Jacobians. If false, Jacobians will be computed dynamically (on-the-fly), which requires manual differentiation.

virtual bool	store_jacobians () override
	Returns whether the Jacobians are stored.

virtual bool	supports_dynamic_jacobians () override
	Determines whether dynamic Jacobian computation is supported (only supported for manual differentiation).

virtual void	get_hessian_block_coordinates (thrust::device_vector< BlockCoordinates > &block_coords) override
	Determines which Hessian blocks are filled in (upper triangle).

virtual size_t	setup_hessian_computation (std::unordered_map< BlockCoordinates, size_t > &block_indices, thrust::device_vector< S > &d_hessian, size_t *h_block_offsets, StreamPool &streams) override
	Sets up data needed to compute the upper triangle of the Hessian matrix on the GPU.

virtual size_t	execute_hessian_computation (std::unordered_map< BlockCoordinates, size_t > &block_indices, thrust::device_vector< S > &d_hessian, size_t *d_block_offsets, StreamPool &streams) override
	Executes the Hessian block computations for this descriptor using the data from setup_hessian_computation.

void	clear ()
	Clears all data associated with this factor descriptor.

Static Public Member Functions
static constexpr size_t	get_num_vertices ()
	Returns the number of vertices connected to each factor.

template<std::size_t... I>
static constexpr std::array< size_t, N >	get_vertex_sizes_impl (std::index_sequence< I... >)

static constexpr std::array< size_t, N >	get_vertex_sizes ()
	Returns the sizes (dimensions) of the vertices.

Public Attributes
std::array< BaseVertexDescriptor< T, S > *, N >	vertex_descriptors

thrust::host_vector< size_t >	host_ids

thrust::device_vector< size_t >	device_ids

managed_vector< ObservationType >	device_obs

thrust::device_vector< T >	residuals

managed_vector< S >	precision_matrices

managed_vector< ConstraintDataType >	data

managed_vector< T >	chi2_vec

thrust::device_vector< S >	chi2_derivative

managed_vector< LossType >	loss

thrust::host_vector< uint8_t >	active

thrust::device_vector< uint8_t >	device_active

thrust::device_vector< size_t >	active_indices

std::array< JacobianStorage< S >, N >	jacobians

std::array< S, Traits::dimension *Traits::dimension >	default_precision_matrix

Static Public Attributes
static constexpr size_t	N

static constexpr size_t	error_dim = Traits::dimension

Static Private Member Functions
static constexpr std::array< S, error_dim *error_dim >	get_default_precision_matrix ()
	Gets the default precision matrix (identity matrix).

Private Attributes
std::vector< size_t >	global_ids

std::unordered_map< size_t, size_t >	global_to_local_map

std::vector< size_t >	local_to_global_map

HandleManager< size_t >	hm

bool	_store_jacobians

size_t	_active_count

Detailed Description

template<typename T, typename S, typename FTraits>
class graphite::FactorDescriptor< T, S, FTraits >

Represents a group of factors which will be processed together on the GPU.

Constructor & Destructor Documentation

◆ FactorDescriptor()

template<typename T , typename S , typename FTraits >

template<typename... VertexDescPtrs, typename = std::enable_if_t<sizeof...(VertexDescPtrs) == N>>

graphite::FactorDescriptor< T, S, FTraits >::FactorDescriptor ( VertexDescPtrs... vertex_descriptors )

inline

Constructs a FactorDescriptor with the given vertex descriptors.

Template Parameters

VertexDescPtrs Types of the vertex descriptor pointers.

Parameters

vertex_descriptors Pointers to the vertex descriptors.

Member Function Documentation

◆ active_count()

template<typename T , typename S , typename FTraits >

size_t graphite::FactorDescriptor< T, S, FTraits >::active_count ( ) const

inlineoverridevirtual

Returns the number of active factors.

Returns: The count of active factors.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ add_factor()

template<typename T , typename S , typename FTraits >

size_t graphite::FactorDescriptor< T, S, FTraits >::add_factor	(	const std::array< size_t, N > &	ids,
		const ObservationType &	obs = `ObservationType()`,
		const S *	precision_matrix = `nullptr`,
		const ConstraintDataType &	constraint_data = `ConstraintDataType()`,
		const LossType &	loss_func = `LossType()`
	)

inline

Adds a factor to the descriptor.

Parameters

ids	The ids of the vertices connected to the factor. Note that later arguments have default values.
obs	The observation associated with the factor.
precision_matrix	The precision matrix for the factor (default nullptr is the identity matrix).
constraint_data	The constraint data for the factor.
loss_func	The loss function for the factor.

Returns: The id of the added factor.

◆ chi2() [1/2]

template<typename T , typename S , typename FTraits >

virtual T graphite::FactorDescriptor< T, S, FTraits >::chi2 ( )

inlineoverridevirtual

Computes the chi-squared value for all active and inactive factors.

Returns: The chi-squared value.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ chi2() [2/2]

template<typename T , typename S , typename FTraits >

T graphite::FactorDescriptor< T, S, FTraits >::chi2 ( const size_t id ) const

inline

Returns the chi-squared value for a specific factor.

Parameters

id	The id of the factor.

Returns: The chi-squared value for the specified factor.

◆ compute_b_async()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_b_async	(	T *	b,
		const T *	jacobian_scales
	)

inlineoverridevirtual

Computes the gradient vector b asynchronously.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ compute_error()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_error ( )

inlineoverridevirtual

Computes the residuals across all factors in the descriptor.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ compute_error_autodiff()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_error_autodiff ( StreamPool & streams )

inlineoverridevirtual

Simultaneously computes the residuals and corresponding Jacobians using automatic differentiation.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ compute_hessian_block_diagonal_async()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_hessian_block_diagonal_async	(	std::unordered_map< BaseVertexDescriptor< T, S > *, thrust::device_vector< InvP > > &	block_diagonals,
		const T *	jacobian_scales,
		cudaStream_t	stream
	)

inlineoverridevirtual

Computes the block diagonal of the Hessian matrix asynchronously.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ compute_hessian_scalar_diagonal_async()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_hessian_scalar_diagonal_async	(	T *	diagonal,
		const T *	jacobian_scales
	)

inlineoverridevirtual

Computes the scalar diagonal of the Hessian matrix asynchronously.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ compute_jacobians()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_jacobians ( StreamPool & streams )

inlineoverridevirtual

Computes the Jacobians using manual differentiation.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ compute_Jtv()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_Jtv	(	T *	out,
		T *	in,
		const T *	jacobian_scales,
		StreamPool &	streams
	)

inlineoverridevirtual

Computes the product of the transposed Jacobian matrix and a vector.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ compute_Jv()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::compute_Jv	(	T *	out,
		T *	in,
		const T *	jacobian_scales,
		StreamPool &	streams
	)

inlineoverridevirtual

Computes the product of the Jacobian matrix and a vector.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ execute_hessian_computation()

template<typename T , typename S , typename FTraits >

virtual size_t graphite::FactorDescriptor< T, S, FTraits >::execute_hessian_computation	(	std::unordered_map< BlockCoordinates, size_t > &	block_indices,
		thrust::device_vector< S > &	d_hessian,
		size_t *	d_block_offsets,
		StreamPool &	streams
	)

inlineoverridevirtual

Executes the Hessian block computations for this descriptor using the data from setup_hessian_computation.

Returns: The number of multiplications that were performed by this descriptor.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ flag_active_vertices_async()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::flag_active_vertices_async ( const uint8_t level )

inlineoverridevirtual

Implements graphite::BaseFactorDescriptor< T, S >.

◆ get_constraint_data()

template<typename T , typename S , typename FTraits >

ConstraintDataType * graphite::FactorDescriptor< T, S, FTraits >::get_constraint_data ( const size_t id )

inline

Returns the constraint data for a specific factor.

Parameters

id	The id of the factor.

Returns: A pointer to the constraint data for the specified factor, or nullptr if not found. The memory can be accessed on both the host and the device.

◆ get_default_precision_matrix()

template<typename T , typename S , typename FTraits >

static constexpr std::array< S, error_dim *error_dim > graphite::FactorDescriptor< T, S, FTraits >::get_default_precision_matrix ( )

inlinestaticconstexprprivate

Gets the default precision matrix (identity matrix).

Returns: An array representing the default precision matrix.

◆ get_hessian_block_coordinates()

template<typename T , typename S , typename FTraits >

virtual void graphite::FactorDescriptor< T, S, FTraits >::get_hessian_block_coordinates ( thrust::device_vector< BlockCoordinates > & block_coords )

inlineoverridevirtual

Determines which Hessian blocks are filled in (upper triangle).

Parameters

block_coords A vector to be filled with the coordinates of the Hessian blocks that are filled in by this factor descriptor.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ get_jacobians()

template<typename T , typename S , typename FTraits >

JacobianStorage< S > * graphite::FactorDescriptor< T, S, FTraits >::get_jacobians ( )

inlineoverridevirtual

Returns the Jacobian storage for the factor.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ get_num_descriptors()

template<typename T , typename S , typename FTraits >

size_t graphite::FactorDescriptor< T, S, FTraits >::get_num_descriptors ( ) const

inlineoverridevirtual

Returns the number of vertex descriptors (same as the number of vertices for each factor).

Implements graphite::BaseFactorDescriptor< T, S >.

◆ get_residual_size()

template<typename T , typename S , typename FTraits >

virtual size_t graphite::FactorDescriptor< T, S, FTraits >::get_residual_size ( ) const

inlineoverridevirtual

Returns the size of the vector for all active and inactive residuals.

Returns: The size of the residuals.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ get_vertex_ids()

template<typename T , typename S , typename FTraits >

std::array< size_t, N > graphite::FactorDescriptor< T, S, FTraits >::get_vertex_ids ( const size_t id ) const

inline

Returns the vertex ids connected to a specific factor.

Parameters

id	The id of the factor.

Returns: An array containing the vertex ids connected to the specified factor.

◆ get_vertex_sizes()

template<typename T , typename S , typename FTraits >

static constexpr std::array< size_t, N > graphite::FactorDescriptor< T, S, FTraits >::get_vertex_sizes ( )

inlinestaticconstexpr

Returns the sizes (dimensions) of the vertices.

Returns: An array containing the sizes of the vertices.

◆ get_vertices()

template<typename T , typename S , typename FTraits >

VertexPointerPointerTuple graphite::FactorDescriptor< T, S, FTraits >::get_vertices ( )

inline

Returns a tuple of vertex pointers.

Returns: A tuple containing pointers to the vertex data for each vertex descriptor.

◆ initialize_device_ids()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::initialize_device_ids ( const uint8_t optimization_level )

inlineoverridevirtual

Initializes the device ids and a list of active factors.

Parameters

optimization_level The optimization level to use.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ initialize_jacobian_storage()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::initialize_jacobian_storage ( )

inlineoverridevirtual

Allocates memory for the Jacobians.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ internal_count()

template<typename T , typename S , typename FTraits >

size_t graphite::FactorDescriptor< T, S, FTraits >::internal_count ( ) const

inline

Returns the number of all active and inactive factors.

Returns: The internal count of all factors.

◆ link_factors()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::link_factors ( const std::array< BaseVertexDescriptor< T, S > *, N > & vertex_descriptors )

inline

Links the factor to the given vertex descriptors. This is already called during construction.

Parameters

vertex_descriptors The array of vertex descriptors to link.

◆ remove_factor()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::remove_factor ( const size_t id )

inline

Removes a factor by its id.

Parameters

id	The id of the factor to remove (i.e. the id returned by add_factor).

◆ reserve()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::reserve ( size_t size )

inline

Reserves memory for the factor. Generally, you should always reserve the memory you need before adding factors, because reallocating GPU memory is expensive.

Parameters

size	The number of factors to reserve memory for.

◆ scale_jacobians_async()

template<typename T , typename S , typename FTraits >

virtual void graphite::FactorDescriptor< T, S, FTraits >::scale_jacobians_async ( T * jacobian_scales )

inlineoverridevirtual

Scales the Jacobians asynchronously.

Parameters

jacobian_scales Pointer to the array of scales for the Jacobians.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ set_active()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::set_active	(	size_t	id,
		const uint8_t	active_value
	)

inline

Sets the active state of a factor.

Parameters

id	The id of the factor.
active_value	The active state value to set (e.g 0).

◆ set_jacobian_storage()

template<typename T , typename S , typename FTraits >

virtual void graphite::FactorDescriptor< T, S, FTraits >::set_jacobian_storage ( const bool store )

inlinevirtual

Sets whether to store the Jacobians. If false, Jacobians will be computed dynamically (on-the-fly), which requires manual differentiation.

Parameters

store True to store the Jacobians (default mode), false to compute them dynamically.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ setup_hessian_computation()

template<typename T , typename S , typename FTraits >

virtual size_t graphite::FactorDescriptor< T, S, FTraits >::setup_hessian_computation	(	std::unordered_map< BlockCoordinates, size_t > &	block_indices,
		thrust::device_vector< S > &	d_hessian,
		size_t *	h_block_offsets,
		StreamPool &	streams
	)

inlineoverridevirtual

Sets up data needed to compute the upper triangle of the Hessian matrix on the GPU.

Returns: The number of multiplications that will be performed by this descriptor.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ store_jacobians()

template<typename T , typename S , typename FTraits >

virtual bool graphite::FactorDescriptor< T, S, FTraits >::store_jacobians ( )

inlineoverridevirtual

Returns whether the Jacobians are stored.

Returns: True if the Jacobians are stored, false otherwise.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ supports_dynamic_jacobians()

template<typename T , typename S , typename FTraits >

virtual bool graphite::FactorDescriptor< T, S, FTraits >::supports_dynamic_jacobians ( )

inlineoverridevirtual

Determines whether dynamic Jacobian computation is supported (only supported for manual differentiation).

Returns: True if dynamic Jacobian computation is supported, false otherwise.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ to_device()

template<typename T , typename S , typename FTraits >

void graphite::FactorDescriptor< T, S, FTraits >::to_device ( )

inlineoverridevirtual

Prepares descriptor for GPU processing.

Implements graphite::BaseFactorDescriptor< T, S >.

◆ use_autodiff()

template<typename T , typename S , typename FTraits >

virtual bool graphite::FactorDescriptor< T, S, FTraits >::use_autodiff ( )

inlineoverridevirtual

Determines whether to use automatic differentiation based on the traits of the factor.

Returns: True if automatic differentiation should be used, false otherwise.

Implements graphite::BaseFactorDescriptor< T, S >.

Member Data Documentation

◆ N

template<typename T , typename S , typename FTraits >

constexpr size_t graphite::FactorDescriptor< T, S, FTraits >::N

staticconstexpr

Initial value:

=

std::tuple_size<typename Traits::VertexDescriptors>::value

The documentation for this class was generated from the following file:

/home/runner/work/graphite/graphite/include/graphite/factor.hpp

Public Types

Public Member Functions

Static Public Member Functions

Public Attributes

Static Public Attributes

Static Private Member Functions

Private Attributes

Detailed Description

Constructor & Destructor Documentation

◆ FactorDescriptor()

Member Function Documentation

◆ active_count()

◆ add_factor()

◆ chi2() [1/2]

◆ chi2() [2/2]

◆ compute_b_async()

◆ compute_error()

◆ compute_error_autodiff()

◆ compute_hessian_block_diagonal_async()

◆ compute_hessian_scalar_diagonal_async()

◆ compute_jacobians()

◆ compute_Jtv()

◆ compute_Jv()

◆ execute_hessian_computation()

◆ flag_active_vertices_async()

◆ get_constraint_data()

◆ get_default_precision_matrix()

◆ get_hessian_block_coordinates()

◆ get_jacobians()

◆ get_num_descriptors()

◆ get_residual_size()

◆ get_vertex_ids()

◆ get_vertex_sizes()

◆ get_vertices()

◆ initialize_device_ids()

◆ initialize_jacobian_storage()

◆ internal_count()

◆ link_factors()

◆ remove_factor()

◆ reserve()

◆ scale_jacobians_async()

◆ set_active()

◆ set_jacobian_storage()

◆ setup_hessian_computation()

◆ store_jacobians()

◆ supports_dynamic_jacobians()

◆ to_device()

◆ use_autodiff()

Member Data Documentation

◆ N