Implements IRLBA for approximate SVD. More...

Classes
class	Centered
	Wrapper for a centered matrix. More...

class	EigenThreadScope
	Restrict the number of available threads for Eigen. More...

struct	get_adjoint_workspace
	Get the type of workspace for `wrapped_adjoint_multiply()`. More...

struct	get_adjoint_workspace< Matrix_, decltype((void) std::declval< typename Matrix_::Index >(), 0)>
	Get the type of workspace for `wrapped_adjoint_multiply()`. More...

struct	get_workspace
	Get the type of workspace for `wrapped_multiply()`. More...

struct	get_workspace< Matrix_, decltype((void) std::declval< typename Matrix_::Index >(), 0)>
	Get the type of workspace for `wrapped_multiply()`. More...

class	MockMatrix
	Interface for a matrix to use in `compute()`. More...

struct	Options
	Options for the IRLBA algorithm. More...

class	ParallelSparseMatrix
	Sparse matrix with customizable parallelization. More...

struct	Results
	Result of the IRLBA-based decomposition. More...

class	Scaled
	Wrapper for a scaled matrix. More...

Typedefs
template<class Matrix_ >
using	WrappedWorkspace = typename get_workspace< Matrix_ >::type

template<class Matrix_ >
using	WrappedAdjointWorkspace = typename get_adjoint_workspace< Matrix_ >::type

Functions
template<class Matrix_ , class EigenMatrix_ , class EigenVector_ >
std::pair< bool, int >	compute (const Matrix_ &matrix, Eigen::Index number, EigenMatrix_ &outU, EigenMatrix_ &outV, EigenVector_ &outD, const Options &options)

template<class EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class Matrix_ >
Results< EigenMatrix_, EigenVector_ >	compute (const Matrix_ &matrix, Eigen::Index number, const Options &options)

template<class Matrix_ , class EigenMatrix_ , class EigenVector_ >
std::pair< bool, int >	compute (const Matrix_ &matrix, bool center, bool scale, Eigen::Index number, EigenMatrix_ &outU, EigenMatrix_ &outV, EigenVector_ &outD, const Options &options)

template<class EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class Matrix_ >
Results< EigenMatrix_, EigenVector_ >	compute (const Matrix_ &matrix, bool center, bool scale, Eigen::Index number, const Options &options)

template<typename Task_ , class Run_ >
void	parallelize (Task_ num_tasks, Run_ run_task)

template<class Matrix_ >
WrappedWorkspace< Matrix_ >	wrapped_workspace (const Matrix_ &matrix)

template<class Matrix_ >
WrappedAdjointWorkspace< Matrix_ >	wrapped_adjoint_workspace (const Matrix_ &matrix)

template<class Matrix_ , class Right_ , class EigenVector_ >
void	wrapped_multiply (const Matrix_ &matrix, const Right_ &rhs, WrappedWorkspace< Matrix_ > &work, EigenVector_ &out)

template<class Matrix_ , class Right_ , class EigenVector_ >
void	wrapped_adjoint_multiply (const Matrix_ &matrix, const Right_ &rhs, WrappedAdjointWorkspace< Matrix_ > &work, EigenVector_ &out)

template<class EigenMatrix_ , class Matrix_ >
EigenMatrix_	wrapped_realize (const Matrix_ &matrix)

template<bool column_, class Matrix_ , class EigenVector_ >
Scaled< column_, Matrix_, EigenVector_ >	make_Scaled (const Matrix_ &matrix, const EigenVector_ &scale, bool divide)

Detailed Description

Implements IRLBA for approximate SVD.

Typedef Documentation

◆ WrappedAdjointWorkspace

template<class Matrix_ >

using irlba::WrappedAdjointWorkspace = typedef typename get_adjoint_workspace<Matrix_>::type

Type of workspace for wrapped_adjoint_multiply(). This can be used to satisfy the MockMatrix::AdjointWorkspace interface, either directly or as a component of a larger workspace class.

Template Parameters

Matrix_ A floating-point Eigen::Matrix class, or a class satisfying the MockMatrix interface.

◆ WrappedWorkspace

template<class Matrix_ >

using irlba::WrappedWorkspace = typedef typename get_workspace<Matrix_>::type

Type of workspace for wrapped_multiply(). This can be used to satisfy the MockMatrix::Workspace interface, either directly or as a component of a larger workspace class.

Template Parameters

Matrix_ A floating-point Eigen::Matrix class, or a class satisfying the MockMatrix interface.

Function Documentation

◆ compute() [1/4]

template<class EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class Matrix_ >

Results< EigenMatrix_, EigenVector_ > irlba::compute	(	const Matrix_ &	matrix,
		bool	center,
		bool	scale,
		Eigen::Index	number,
		const Options &	options
	)

Convenient overload of compute() with centering and scaling, which allocates memory for the output matrices of the SVD.

Template Parameters

Matrix_	A floating-point `Eigen::Matrix` or equivalent sparse matrix class.
EigenMatrix_	A floating-point `Eigen::Matrix` class.
EigenVector_	A floating-point `Eigen::Vector` class, typically of the same scalar type as `EigenMatrix_`.

Parameters

[in]	matrix	Input matrix.
	center	Should the matrix be centered by column?
	scale	Should the matrix be scaled to unit variance for each column?
	number	Number of singular triplets to obtain.
	options	Further options.

Returns: A Results object containing the singular vectors and values, as well as some statistics on convergence.

◆ compute() [2/4]

template<class Matrix_ , class EigenMatrix_ , class EigenVector_ >

std::pair< bool, int > irlba::compute	(	const Matrix_ &	matrix,
		bool	center,
		bool	scale,
		Eigen::Index	number,
		EigenMatrix_ &	outU,
		EigenMatrix_ &	outV,
		EigenVector_ &	outD,
		const Options &	options
	)

Convenient overload of compute() that handles the centering and scaling.

Template Parameters

Matrix_	A floating-point `Eigen::Matrix` or equivalent sparse matrix class.
EigenMatrix_	A floating-point `Eigen::Matrix` class.
EigenVector_	A floating-point `Eigen::Vector` class, typically of the same scalar type as `EigenMatrix_`.

Parameters

[in]	matrix	Input matrix.
	center	Should the matrix be centered by column?
	scale	Should the matrix be scaled to unit variance for each column?
	number	Number of singular triplets to obtain.
[out]	outU	Output matrix where columns contain the first left singular vectors. Dimensions are set automatically on output; the number of columns is set to `number` and the number of rows is equal to the number of rows in `mat`.
[out]	outV	Output matrix where columns contain the first right singular vectors. Dimensions are set automatically on output; the number of columns is set to `number` and the number of rows is equal to the number of columns in `mat`.
[out]	outD	Vector to store the first singular values. The length is set to `number` on output.
	options	Further options.

Returns: A pair where the first entry indicates whether the algorithm converged, and the second entry indicates the number of restart iterations performed.

Centering is performed by subtracting each element of center from the corresponding column of mat. Scaling is performed by dividing each column of mat by the corresponding element of scale (after any centering has been applied). Note that scale=true requires center=true to guarantee unit variance along each column. No scaling is performed when the variance of a column is zero, so as to avoid divide-by-zero errors.

◆ compute() [3/4]

template<class EigenMatrix_ = Eigen::MatrixXd, class EigenVector_ = Eigen::VectorXd, class Matrix_ >

Results< EigenMatrix_, EigenVector_ > irlba::compute	(	const Matrix_ &	matrix,
		Eigen::Index	number,
		const Options &	options
	)

Convenient overload of compute() that allocates memory for the output matrices of the SVD.

Template Parameters

EigenMatrix_	A floating-point `Eigen::Matrix` class.
EigenVector_	A floating-point `Eigen::Vector` class, typically of the same scalar type as `EigenMatrix_`.
Matrix_	Class satisfying the `MockMatrix` interface, or a floating-point `Eigen:Matrix` class.

Parameters

[in]	matrix	Input matrix.
	number	Number of singular triplets to obtain.
	options	Further options.

Returns: A Results object containing the singular vectors and values, as well as some statistics on convergence.

◆ compute() [4/4]

template<class Matrix_ , class EigenMatrix_ , class EigenVector_ >

std::pair< bool, int > irlba::compute	(	const Matrix_ &	matrix,
		Eigen::Index	number,
		EigenMatrix_ &	outU,
		EigenMatrix_ &	outV,
		EigenVector_ &	outD,
		const Options &	options
	)

Implements the Implicitly Restarted Lanczos Bidiagonalization Algorithm (IRLBA) for fast truncated singular value decomposition. This is heavily derived from the C code in the irlba package, with refactoring into C++ to use Eigen instead of LAPACK for much of the matrix algebra.

Template Parameters

Matrix_	Class satisfying the `MockMatrix` interface, or a floating-point `Eigen:Matrix` class.
EigenMatrix_	A floating-point `Eigen::Matrix` class.
EigenVector_	A floating-point `Eigen::Vector` class, typically of the same scalar type as `EigenMatrix_`.

Parameters

[in]	matrix	Input matrix. Custom classes can also be used here to pass modified matrices that cannot be efficiently realized into the standard Eigen classes. See the `wrappers.hpp` file for more details, along with the `Centered` and `Scaled` classes.
	number	Number of singular triplets to obtain.
[out]	outU	Output matrix where columns contain the first left singular vectors. Dimensions are set automatically on output; the number of columns is set to `number` and the number of rows is equal to the number of rows in `mat`.
[out]	outV	Output matrix where columns contain the first right singular vectors. Dimensions are set automatically on output; the number of columns is set to `number` and the number of rows is equal to the number of columns in `mat`.
[out]	outD	Vector to store the first singular values. The length is set to `number` on output.
	options	Further options.

Returns: A pair where the first entry indicates whether the algorithm converged, and the second entry indicates the number of restart iterations performed.

◆ make_Scaled()

template<bool column_, class Matrix_ , class EigenVector_ >

Scaled< column_, Matrix_, EigenVector_ > irlba::make_Scaled	(	const Matrix_ &	matrix,
		const EigenVector_ &	scale,
		bool	divide
	)

A convenient maker function to enable partial template deduction on the Scaled class.

Template Parameters

column_	Whether to scale the columns. If `false`, scaling is applied to the rows instead.
Matrix_	Class satisfying the `MockMatrix` interface, or a floating-point `Eigen::Matrix`.
EigenVector_	A floating-point `Eigen::Vector` class for the scaling factors and matrix-vector product.

Parameters

matrix	Underlying matrix to be column-scaled (if `by_column_ = true`) or row-scaled (otherwise).
scale	Vector of length equal to the number of columns (if `by_column_ = true`) or rows (otherwise) of `m`, containing the scaling factor to divide (if `divide = true`) or multiply (otherwise) to each column/row.
divide	Whether to divide by the supplied scaling factors.

Returns: A Scaled object.

◆ parallelize()

template<typename Task_ , class Run_ >

void irlba::parallelize	(	Task_	num_tasks,
		Run_	run_task
	)

Template Parameters

Task_	Integer type for the number of tasks.
Run_	Function to execute each task.

Parameters

num_tasks	Number of tasks. This is equal to the number of threads in the context of `ParallelSparseMatrix`.
run_task	Function to execute each task within its own worker.

By default, this is an alias to subpar::parallelize_simple(). However, if the IRLBA_CUSTOM_PARALLEL function-like macro is defined, it is called instead. Any user-defined macro should accept the same arguments as subpar::parallelize_simple().

◆ wrapped_adjoint_multiply()

template<class Matrix_ , class Right_ , class EigenVector_ >

void irlba::wrapped_adjoint_multiply	(	const Matrix_ &	matrix,
		const Right_ &	rhs,
		WrappedAdjointWorkspace< Matrix_ > &	work,
		EigenVector_ &	out
	)

Template Parameters

Matrix_	Class satisfying the `MockMatrix` interface, or a floating-point `EigenMatrix`.
Right_	A floating-point `Eigen::Vector` or equivalent expression.
EigenVector_	A floating-point `Eigen::Vector` class

Parameters

[in]	matrix	Pointer to the wrapped matrix instance.
[in]	rhs	The right-hand side of the matrix product.
	work	Workspace for the adjoint matrix multiplication.
[out]	out	The output vector to store the matrix product. This is filled with the product of this matrix and `rhs`.

◆ wrapped_adjoint_workspace()

template<class Matrix_ >

WrappedAdjointWorkspace< Matrix_ > irlba::wrapped_adjoint_workspace ( const Matrix_ & matrix )

Template Parameters

Matrix_ A floating-point Eigen::Matrix class, or a class satisfying the MockMatrix interface.

Parameters

matrix Instance of a matrix.

Returns: Workspace to use in adjoint_multiply().

◆ wrapped_multiply()

template<class Matrix_ , class Right_ , class EigenVector_ >

void irlba::wrapped_multiply	(	const Matrix_ &	matrix,
		const Right_ &	rhs,
		WrappedWorkspace< Matrix_ > &	work,
		EigenVector_ &	out
	)

Template Parameters

Matrix_	Class satisfying the `MockMatrix` interface, or a floating-point `EigenMatrix`.
Right_	A floating-point `Eigen::Vector` or equivalent expression.
EigenVector_	A floating-point `Eigen::Vector` class.

Parameters

[in]	matrix	Pointer to the wrapped matrix instance.
[in]	rhs	The right-hand side of the matrix product.
	work	Workspace for the matrix multiplication.
[out]	out	The output vector to store the matrix product. This is filled with the product of this matrix and `rhs`.

◆ wrapped_realize()

template<class EigenMatrix_ , class Matrix_ >

EigenMatrix_ irlba::wrapped_realize ( const Matrix_ & matrix )

Template Parameters

EigenMatrix_	A floating-point `Eigen::Matrix`.
Matrix_	Class satisfying the `MockMatrix` interface, or a floating-point `Eigen::Matrix`.

Parameters

[in] matrix Pointer to the wrapped matrix instance.

Returns: A dense Eigen matrix containing the realized contents of mat.

◆ wrapped_workspace()

template<class Matrix_ >

WrappedWorkspace< Matrix_ > irlba::wrapped_workspace ( const Matrix_ & matrix )

Template Parameters

Matrix_ A floating-point Eigen::Matrix class, or a class satisfying the MockMatrix interface.

Parameters

matrix Instance of a matrix.

Returns: Workspace to use in multiply().

Classes

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ WrappedAdjointWorkspace

◆ WrappedWorkspace

Function Documentation

◆ compute() [1/4]

◆ compute() [2/4]

◆ compute() [3/4]

◆ compute() [4/4]

◆ make_Scaled()

◆ parallelize()

◆ wrapped_adjoint_multiply()

◆ wrapped_adjoint_workspace()

◆ wrapped_multiply()

◆ wrapped_realize()

◆ wrapped_workspace()