Matrix, vector and other products

Detailed Description

Various products involving matrices, vectors and more general arrays and views.

Functions
template<Vector X, Vector Y> requires (nda::mem::have_host_compatible_addr_space<X, Y>)
auto	nda::linalg::cross_product (X const &x, Y const &y)
	Compute the vector cross product.
template<typename X, typename Y> requires ((Scalar<X> and Scalar<Y>) or (Vector<X> and Vector<Y>))
auto	nda::linalg::dot (X const &x, Y const &y)
	Compute the dot product of two nda::vector objects or the product of two scalars.
template<bool star = false, Vector X, Vector Y> requires (Scalar<get_value_t<X>> and Scalar<get_value_t<Y>> and mem::have_host_compatible_addr_space<X, Y>)
auto	nda::linalg::dot_generic (X const &x, Y const &y)
	Generic loop-based dot product implementation for vectors.
template<typename X, typename Y> requires ((Scalar<X> and Scalar<Y>) or (Vector<X> and Vector<Y>))
auto	nda::linalg::dotc (X const &x, Y const &y)
	Compute the dotc (LHS operand is conjugated) product of two nda::vector objects or the product of two scalars.
template<Matrix A, Matrix B> requires (mem::have_compatible_addr_space<A, B>)
auto	nda::linalg::matmul (A &&a, B &&b)
	Compute the matrix-matrix product of two nda::Matrix objects.
template<Matrix A, Vector X> requires (mem::have_compatible_addr_space<A, X>)
auto	nda::linalg::matvecmul (A const &a, X const &x)
	Compute the matrix-vector product of an nda::Matrix and an nda::Vector object.
template<blas_lapack::BlasArray A, blas_lapack::BlasArrayFor< A > B> requires (blas_lapack::has_C_layout<A, B> or blas_lapack::has_F_layout<A, B>)
auto	nda::linalg::outer_product (A const &a, B const &b)
	Outer product of two arrays/views.

Function Documentation

cross_product()

template<Vector X, Vector Y>
requires (nda::mem::have_host_compatible_addr_space<X, Y>)

auto nda::linalg::cross_product	(	X const &	x,
		Y const &	y )

#include <nda/linalg/cross_product.hpp>

Compute the vector cross product.

It computes \( \mathbf{x} \times \mathbf{y} \) of two 3-dimensional vectors \( \mathbf{x} \) and \(\mathbf{y} \).

Note

\( \mathbf{x} \) and \( \mathbf{y} \) are required to satisfy nda::mem::have_host_compatible_addr_space.

Template Parameters

X	nda::Vector type.
Y	nda::Vector type.

Parameters

x	Input vector \( \mathbf{x} \).
y	Input vector \( \mathbf{y} \).

Returns

nda::vector containing the cross product of the two vectors.

Definition at line 39 of file cross_product.hpp.

dot()

template<typename X, typename Y>
requires ((Scalar<X> and Scalar<Y>) or (Vector<X> and Vector<Y>))

auto nda::linalg::dot	(	X const &	x,
		Y const &	y )

#include <nda/linalg/dot.hpp>

Compute the dot product of two nda::vector objects or the product of two scalars.

The behaviour of this function is identical to nda::blas::dot, except that it allows

• the two input objects to be scalars,
• lazy expressions as input vectors,
• the value types of the input vectors to be different from each other and
• the value types of the input vectors to be different from nda::is_blas_lapack_v.

For scalars, it performs simple scalar multiplication. For vectors, it calls nda::blas::dot if possible, otherwise it falls back to nda::linalg::dot_generic.

Note

The first argument is never conjugated. Use nda::linalg::dotc for that.

Template Parameters

X	nda::Vector or nda::Scalar type.
Y	nda::Vector or nda::Scalar type.

Parameters

x	Input vector/scalar.
y	Input vector/scalar.

Returns

Result of the dot product/scalar multiplication.

Definition at line 108 of file dot.hpp.

dot_generic()

template<bool star = false, Vector X, Vector Y>
requires (Scalar<get_value_t<X>> and Scalar<get_value_t<Y>> and mem::have_host_compatible_addr_space<X, Y>)

auto nda::linalg::dot_generic	(	X const &	x,
		Y const &	y )

#include <nda/linalg/dot.hpp>

Generic loop-based dot product implementation for vectors.

Computes the dot product of two vector objects, \( \mathbf{x} \) and \( \mathbf{y} \), with optional conjugation:

• For star = false, it returns \( \mathbf{x}^T \mathbf{y} \).
• For star = true, it returns \( \mathbf{x}^H \mathbf{y} \).

Note

\( \mathbf{x} \) and \( \mathbf{y} \) are required to satisfy nda::mem::have_host_compatible_addr_space and to have nda::Scalar value types.

Template Parameters

star	If true, conjugate the first operand (for complex types only).
X	nda::Vector type.
Y	nda::Vector type.

Parameters

x	Input vector \( \mathbf{x} \).
y	Input vector \( \mathbf{y} \).

Returns

Result of the dot product.

Definition at line 49 of file dot.hpp.

dotc()

template<typename X, typename Y>
requires ((Scalar<X> and Scalar<Y>) or (Vector<X> and Vector<Y>))

auto nda::linalg::dotc	(	X const &	x,
		Y const &	y )

#include <nda/linalg/dot.hpp>

Compute the dotc (LHS operand is conjugated) product of two nda::vector objects or the product of two scalars.

The behaviour of this function is identical to nda::blas::dotc, except that it allows

• the two input objects to be scalars,
• lazy expressions as input vectors,
• the value types of the input vectors to be different from each other and
• the value types of the input vectors to be different from nda::is_blas_lapack_v.

For scalars, it performs simple scalar multiplication (with the first operand conjugated if it is complex). For vectors, it calls nda::blas::dotc if possible, otherwise it falls back to nda::linalg::dot_generic.

Template Parameters

X	nda::Vector or nda::Scalar type.
Y	nda::Vector or nda::Scalar type.

Parameters

x	Input vector/scalar.
y	Input vector/scalar.

Returns

Result of the dotc product/scalar multiplication.

Definition at line 139 of file dot.hpp.

matmul()

template<Matrix A, Matrix B>
requires (mem::have_compatible_addr_space<A, B>)

auto nda::linalg::matmul	(	A &&	a,
		B &&	b )

#include <nda/linalg/matmul.hpp>

Compute the matrix-matrix product of two nda::Matrix objects.

This function computes the matrix-matrix product

\[ \mathbf{C} = \mathbf{A} \mathbf{B} \; , \]

where \( \mathbf{A} \), \( \mathbf{B} \) and \( \mathbf{C} \) are \( m \times k \), \( k \times n \) and \( m \times n \) matrices, respectively.

The behaviour of this function is similar to nda::blas::gemm, except that it allows

• lazy expressions as input,
• the value types of the input matrices to be different from each other and
• the value types of the input matrices to be different from nda::is_blas_lapack_v.

We try to call nda::blas::gemm whenever possible, i.e. when the value type of the result is compatible with nda::is_blas_lapack_v, even if this requires to make copies of the input arrays/views. Otherwise, we perform a very naive and inefficient matrix-matrix multiplication manually.

Therefore, if performance is important, users should make sure to pass input arrays/views which are compatible with nda::blas::gemm.

The resulting nda::matrix has

• its value type deduced from the multiplication of the value types of the input matrices,
• nda::F_layout if both inputs are in F-layout and nda::C_layout otherwise and
• its address space set to the nda::mem::common_addr_space of the input matrices.

This function might make copies of the input arrays/views. When working on the device memory space, this may lead to runtime errors if the copying fails.

Note

\( \mathbf{A} \) and \( \mathbf{B} \) are required to satisfy nda::mem::have_compatible_addr_space.

Template Parameters

A	nda::Matrix type.
B	nda::Matrix type.

Parameters

a	Input matrix \( \mathbf{A} \) of size \( m \times k \).
b	Input matrix \( \mathbf{B} \) of size \( k \times n \).

Returns

Resulting nda::matrix \( \mathbf{C} \) of size \( m \times n \).

Definition at line 137 of file matmul.hpp.

matvecmul()

template<Matrix A, Vector X>
requires (mem::have_compatible_addr_space<A, X>)

auto nda::linalg::matvecmul	(	A const &	a,
		X const &	x )

#include <nda/linalg/matvecmul.hpp>

Compute the matrix-vector product of an nda::Matrix and an nda::Vector object.

This function computes the matrix-vector product

\[ \mathbf{y} = \mathbf{A} \mathbf{x} \; , \]

where \( \mathbf{A} \) is an \( m \times n \) matrix and \( \mathbf{x} \) and \( \mathbf{y} \) are vectors of size \( n \) and \( m \), respectively.

The behaviour of this function is similar to nda::blas::gemv, except that it allows

• lazy expressions as input,
• the value types of the input matrix and vector to be different from each other and
• the value types of the input matrix and vector to be different from nda::is_blas_lapack_v.

We try to call nda::blas::gemv whenever possible, i.e. when the value type of the result is compatible with nda::is_blas_lapack_v, even if this requires to make copies of the input arrays/views. Otherwise, we perform a very naive and inefficient matrix-vector multiplication manually.

Therefore, if performance is important, users should make sure to pass input arrays/views which are compatible with nda::blas::gemv.

The value type of the resulting nda::vector is deduced from the multiplication of the value types of the input arguments and its address space is set to their nda::mem::common_addr_space.

This function might make copies of the input arrays/views. When working on the device memory space, this may lead to runtime errors if the copying fails.

Note

\( \mathbf{A} \) and \( \mathbf{x} \) are required to satisfy nda::mem::have_compatible_addr_space.

Template Parameters

A	nda::Matrix type.
X	nda::Vector type.

Parameters

a	Input matrix \( \mathbf{A} \) of size \( m \times n \).
x	Input vector \( \mathbf{x} \) of size \( n \).

Returns

Resulting nda::vector \( \mathbf{y} \) of size \( m \).

Definition at line 130 of file matvecmul.hpp.

outer_product()

template<blas_lapack::BlasArray A, blas_lapack::BlasArrayFor< A > B>
requires (blas_lapack::has_C_layout<A, B> or blas_lapack::has_F_layout<A, B>)

auto nda::linalg::outer_product	(	A const &	a,
		B const &	b )

#include <nda/linalg/outer_product.hpp>

Outer product of two arrays/views.

It calculates the outer product \( \mathbf{C} = \mathbf{A} \otimes \mathbf{B} \), such that

\[ \mathbf{C}_{i_1 \ldots i_k j_1 \ldots j_l} = \mathbf{A}_{i_1 \ldots i_k} \mathbf{B}_{j_1 \ldots j_l} \; . \]

Here, \( \mathbf{A} \) and \( \mathbf{B} \) are the input arrays with shape \( (m_1, \ldots, m_k) \) and \((n_1, \ldots, n_l) \), respectively. The resulting array \( \mathbf{C} \) has shape \( (m_1, \ldots, m_k, n_1, \ldots, n_l) \).

The outer product is performed by calling nda::blas::ger, which imposes various constraints on the supported input arrays/views, e.g.

• their memory layouts have to be the same and either nda::C_layout or nda::F_layout,
• they have to be contiguous in memory,
• their value types have to be the same and satisfy nda::is_blas_lapack_v,
• etc.

The resulting array will have

• algebra 'M' if both input arrays have algebra 'V', and 'A' otherwise,
• the same address space and value type as the input arrays and
• the same memory layout as the input arrays, except when one or both of them are 1-dimensional. If only one of them is 1-dimensional, the memory layout of the other array is used. If both are 1-dimensional, the resulting array will have nda::C_layout.

Template Parameters

A	nda::blas_lapack::BlasArray type.
B	nda::blas_lapack::BlasArrayFor type.

Parameters

a	Input array/view \( \mathbf{A} \).
b	Input array/view \( \mathbf{B} \).

Returns

Outer product \( \mathbf{C} \).

Definition at line 62 of file outer_product.hpp.