Skip to content

Commit

Permalink
Miscellaneous docstring fixes and updates (#944)
Browse files Browse the repository at this point in the history
  • Loading branch information
@msimberg
msimberg authored Sep 13, 2023
1 parent a9b539d commit e1694e8
Show file tree
Hide file tree
Showing 18 changed files with 439 additions and 178 deletions.
6 changes: 3 additions & 3 deletions include/dlaf/auxiliary/norm.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -27,9 +27,9 @@ namespace dlaf::auxiliary {
///
/// @note @p uplo == blas::uplo::Upper not yet implemented
///
/// @pre `A.blockSize().rows() == A.blockSize().cols()`,
/// @pre @p A is distributed according to @p grid,
/// @pre @p A has equal tile and block sizes,
/// @pre @p A is distributed according to @p grid
/// @pre @p A has blocksize (NB x NB)
/// @pre @p A has tilesize (NB x NB)
/// @return the max norm of the Matrix @p A or 0 if `A.size().isEmpty()`
template <Backend backend, Device device, class T>
dlaf::BaseType<T> max_norm(comm::CommunicatorGrid grid, comm::Index2D rank, blas::Uplo uplo,
Expand Down
22 changes: 12 additions & 10 deletions include/dlaf/eigensolver/band_to_tridiag.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -65,11 +65,12 @@ namespace dlaf::eigensolver::internal {
/// Implementation on local memory.
///
/// @param mat_a contains the Hermitian band matrix A (if A is real, the matrix is symmetric).
/// @pre mat_a has a square size,
/// @pre mat_a has a square block size,
/// @pre band_size is a divisor of mat_a.blockSize().cols(), and band_size >= 2
/// @pre mat_a is not distributed,
/// @pre mat_a has equal tile and block sizes.
/// @pre @p mat_a is not distributed
/// @pre @p mat_a has size (N x N)
/// @pre @p mat_a has blocksize (NB x NB)
/// @pre @p mat_a has tilesize (NB x NB)
///
/// @pre @p band_size is a divisor of `mat_a.blockSize().cols()`, and @p band_size >= 2
template <Backend B, Device D, class T>
TridiagResult<T, Device::CPU> band_to_tridiagonal(blas::Uplo uplo, SizeType band_size,
Matrix<const T, D>& mat_a) {
Expand Down Expand Up @@ -138,11 +139,12 @@ TridiagResult<T, Device::CPU> band_to_tridiagonal(blas::Uplo uplo, SizeType band
/// Implementation on distributed memory.
///
/// @param mat_a contains the Hermitian band matrix A (if A is real, the matrix is symmetric).
/// @pre mat_a has a square size,
/// @pre mat_a has a square block size,
/// @pre band_size is a divisor of mat_a.blockSize().cols() and band_size >= 2,
/// @pre mat_a is distributed according to grid,
/// @pre mat_a has equal tile and block sizes.
/// @pre @p mat_a is distributed according to @p grid
/// @pre @p mat_a has size (N x N)
/// @pre @p mat_a has blocksize (NB x NB)
/// @pre @p mat_a has tilesize (NB x NB)
///
/// @pre @p band_size is a divisor of `mat_a.blockSize().cols()`, and @p band_size >= 2
template <Backend backend, Device device, class T>
TridiagResult<T, Device::CPU> band_to_tridiagonal(comm::CommunicatorGrid grid, blas::Uplo uplo,
SizeType band_size, Matrix<const T, device>& mat_a) {
Expand Down
106 changes: 72 additions & 34 deletions include/dlaf/eigensolver/bt_band_to_tridiag.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,40 +19,42 @@

namespace dlaf::eigensolver::internal {

// Eigenvalue back-transformation implementation on local memory, which applies the inverse of the
// transformation used to get a tridiagonal matrix from a band one.
//
// It computes E -= V T V* E, applying to a general matrix E the inverse of the transformation described
// by the reflectors in V (block-wise, so T represents the T factor which embeds the information about
// taus), which are the ones used to transform a band matrix to a tridiagonal matrix.
//
// In particular, V and T are obtained using data about reflectors and taus passed via @p mat_hh
// where they are stored using following compact representation
//
// compact extended
// AT BT CT DT 1 0 0 0
// A1 B1 C1 D1 A1 1 0 0
// A2 B2 C2 D2 A2 B1 1 0
// A3 B3 C3 D3 A3 B2 C1 1
// 0 B3 C2 D1
// 0 0 C3 D2
// 0 0 0 D3
//
// where A, B, C and D refers to distinct reflectors, with their components numbered and their taus
// identified by the letter T.
//
// @param mat_hh matrix containing reflectors together with taus (compact form see representation above)
// @param mat_e matrix to which the inverse transformation is applied to
// @param band_size size of the reflectors (normal one, not constrained by any matrix size limit)
// @pre mat_hh has a square size
// @pre mat_hh has a square block size
// @pre mat_e and mat_hh share the same number of rows
// @pre mat_e block size and mat_hh block size share the same number of rows
// @pre band_size is a divisor of mat_hh.blockSize().cols()
// @pre mat_e is not distributed
// @pre mat_hh is not distributed
// @pre mat_e has equal tile and block sizes
// @pre mat_hh has equal tile and block sizes
/// Eigenvalue back-transformation implementation on local memory, which applies the inverse of the
/// transformation used to get a tridiagonal matrix from a band one.
///
/// It computes E -= V T V* E, applying to a general matrix E the inverse of the transformation described
/// by the reflectors in V (block-wise, so T represents the T factor which embeds the information about
/// taus), which are the ones used to transform a band matrix to a tridiagonal matrix.
///
/// In particular, V and T are obtained using data about reflectors and taus passed via @p mat_hh
/// where they are stored using following compact representation
///
/// compact extended
/// AT BT CT DT 1 0 0 0
/// A1 B1 C1 D1 A1 1 0 0
/// A2 B2 C2 D2 A2 B1 1 0
/// A3 B3 C3 D3 A3 B2 C1 1
/// 0 B3 C2 D1
/// 0 0 C3 D2
/// 0 0 0 D3
///
/// where A, B, C and D refers to distinct reflectors, with their components numbered and their taus
/// identified by the letter T.
///
/// @param mat_hh matrix containing reflectors together with taus (compact form see representation above)
/// @pre @p mat_hh is not distributed
/// @pre @p mat_hh has size (N x N)
/// @pre @p mat_hh has blocksize (NB x NB)
/// @pre @p mat_hh has tilesize (NB x NB)
///
/// @param mat_e matrix to which the inverse transformation is applied to
/// @pre @p mat_e is not distributed
/// @pre @p mat_e has size (N x M)
/// @pre @p mat_e has blocksize (NB x MB)
/// @pre @p mat_e has tilesize (NB x MB)
///
/// @param band_size size of the reflectors (normal one, not constrained by any matrix size limit)
/// @pre @p band_size is a divisor of `mat_hh.blockSize().cols()`
template <Backend B, Device D, class T>
void bt_band_to_tridiagonal(const SizeType band_size, matrix::Matrix<T, D>& mat_e,
matrix::Matrix<const T, Device::CPU>& mat_hh) {
Expand All @@ -74,6 +76,42 @@ void bt_band_to_tridiagonal(const SizeType band_size, matrix::Matrix<T, D>& mat_
BackTransformationT2B<B, D, T>::call(band_size, mat_e, mat_hh);
}

/// Eigenvalue back-transformation implementation, which applies the inverse of the transformation used
/// to get a tridiagonal matrix from a band one.
///
/// It computes E -= V T V* E, applying to a general matrix E the inverse of the transformation described
/// by the reflectors in V (block-wise, so T represents the T factor which embeds the information about
/// taus), which are the ones used to transform a band matrix to a tridiagonal matrix.
///
/// In particular, V and T are obtained using data about reflectors and taus passed via @p mat_hh
/// where they are stored using following compact representation
///
/// compact extended
/// AT BT CT DT 1 0 0 0
/// A1 B1 C1 D1 A1 1 0 0
/// A2 B2 C2 D2 A2 B1 1 0
/// A3 B3 C3 D3 A3 B2 C1 1
/// 0 B3 C2 D1
/// 0 0 C3 D2
/// 0 0 0 D3
///
/// where A, B, C and D refers to distinct reflectors, with their components numbered and their taus
/// identified by the letter T.
///
/// @param mat_hh matrix containing reflectors together with taus (compact form see representation above)
/// @pre @p mat_hh is distributed according to @p grid
/// @pre @p mat_hh has size (N x N)
/// @pre @p mat_hh has blocksize (NB x NB)
/// @pre @p mat_hh has tilesize (NB x NB)
///
/// @param mat_e matrix to which the inverse transformation is applied to
/// @pre @p mat_e is distributed according to @p grid
/// @pre @p mat_e has size (N x M)
/// @pre @p mat_e has blocksize (NB x MB)
/// @pre @p mat_e has tilesize (NB x MB)
///
/// @param band_size size of the reflectors (normal one, not constrained by any matrix size limit)
/// @pre @p band_size is a divisor of `mat_hh.blockSize().cols()`
template <Backend B, Device D, class T>
void bt_band_to_tridiagonal(comm::CommunicatorGrid grid, const SizeType band_size,
matrix::Matrix<T, D>& mat_e, matrix::Matrix<const T, Device::CPU>& mat_hh) {
Expand Down
26 changes: 17 additions & 9 deletions include/dlaf/eigensolver/bt_reduction_to_band.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -28,14 +28,18 @@ namespace dlaf::eigensolver::internal {
/// defined by the j-th element of tau and the HH reflector stored in the j-th column of the matrix V.
///
/// @param mat_c contains the (m x n) matrix C (blocksize (mb x nb)), while on exit it contains Q C.
/// @pre @p mat_c is not distributed
/// @pre @p mat_c has blocksize (NB x NB)
/// @pre @p mat_c has tilesize (NB x NB)
///
/// @param mat_v is (m x m) matrix with blocksize (mb x mb), which contains the Householder reflectors.
/// The j-th HH reflector is v_j = (1, V(mb + j : n, j)).
/// @pre @p mat_v is not distributed
/// @pre @p mat_v has blocksize (NB x NB)
/// @pre @p mat_v has tilesize (NB x NB)
///
/// @param mat_taus is the tau vector as returned by reductionToBand. The j-th element is the scaling
/// factor for the j-th HH tranformation.
/// @pre mat_c is not distributed,
/// @pre mat_v is not distributed,
/// @pre mat_c has equal tile and block sizes,
/// @pre mat_v has equal tile and block sizes.
template <Backend backend, Device device, class T>
void bt_reduction_to_band(const SizeType b, Matrix<T, device>& mat_c, Matrix<const T, device>& mat_v,
Matrix<const T, Device::CPU>& mat_taus) {
Expand Down Expand Up @@ -64,15 +68,19 @@ void bt_reduction_to_band(const SizeType b, Matrix<T, device>& mat_c, Matrix<con
/// (HH(j) is the House-Holder transformation (I - v tau vH)
/// defined by the j-th element of tau and the HH reflector stored in the j-th column of the matrix V.
///
/// @param mat_c contains the (m x n) matrix C (blocksize (mb x nb)), while on exit it contains Q C.
/// @param mat_c contains the (m x n) matrix C (blocksize (mb x nb)), while on exit it contains Q C
/// @pre @p mat_c is distributed according to @p grid
/// @pre @p mat_c has blocksize (NB x NB)
/// @pre @p mat_c has tilesize (NB x NB)
///
/// @param mat_v is (m x m) matrix with blocksize (mb x mb), which contains the Householder reflectors.
/// The j-th HH reflector is v_j = (1, V(mb + j : n, j)).
/// @pre @p mat_v is distributed according to @p grid
/// @pre @p mat_v has blocksize (NB x NB)
/// @pre @p mat_v has tilesize (NB x NB)
///
/// @param mat_taus is the tau vector as returned by reductionToBand. The j-th element is the scaling
/// factor for the j-th HH tranformation.
/// @pre mat_c is distributed,
/// @pre mat_v is distributed according to grid,
/// @pre mat_c has equal tile and block sizes,
/// @pre mat_v has equal tile and block sizes.
template <Backend backend, Device device, class T>
void bt_reduction_to_band(comm::CommunicatorGrid grid, const SizeType b, Matrix<T, device>& mat_c,
Matrix<const T, device>& mat_v, Matrix<const T, Device::CPU>& mat_taus) {
Expand Down
68 changes: 56 additions & 12 deletions include/dlaf/eigensolver/eigensolver.h
View file
Original file line number Diff line number Diff line change
Expand Up @@ -32,9 +32,24 @@ namespace dlaf {
/// Implementation on local memory.
///
/// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
/// @param mat contains the Hermitian matrix A
/// @param eigenvalues is a N x 1 matrix which on output contains the eigenvalues
/// @param eigenvectors is a N x N matrix which on output contains the eigenvectors
///
/// @param[in,out] mat contains the Hermitian matrix A
/// @pre @p mat is not distributed
/// @pre @p mat has size (N x N)
/// @pre @p mat has blocksize (NB x NB)
/// @pre @p mat has tilesize (NB x NB)
///
/// @param[out] eigenvalues contains the eigenvalues
/// @pre @p eigenvalues is not distributed
/// @pre @p eigenvalues has size (N x 1)
/// @pre @p eigenvalues has blocksize (NB x 1)
/// @pre @p eigenvalues has tilesize (NB x 1)
///
/// @param[out] eigenvectors contains the eigenvectors
/// @pre @p eigenvectors is not distributed
/// @pre @p eigenvectors has size (N x N)
/// @pre @p eigenvectors has blocksize (NB x NB)
/// @pre @p eigenvectors has tilesize (NB x NB)
template <Backend B, Device D, class T>
void hermitian_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat, Matrix<BaseType<T>, D>& eigenvalues,
Matrix<T, D>& eigenvectors) {
Expand Down Expand Up @@ -66,9 +81,15 @@ void hermitian_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat, Matrix<BaseType<T
///
/// Implementation on local memory.
///
/// @return struct ReturnEigensolverType with eigenvalues, as a vector<T>, and eigenvectors as a Matrix
/// @return ReturnEigensolverType with eigenvalues and eigenvectors as a Matrix
///
/// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
/// @param mat contains the Hermitian matrix A
///
/// @param[in,out] mat contains the Hermitian matrix A
/// @pre @p mat is not distributed
/// @pre @p mat has size (N x N)
/// @pre @p mat has blocksize (NB x NB)
/// @pre @p mat has tilesize (NB x NB)
template <Backend B, Device D, class T>
EigensolverResult<T, D> hermitian_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat) {
const SizeType size = mat.size().rows();
Expand All @@ -90,11 +111,27 @@ EigensolverResult<T, D> hermitian_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat
///
/// Implementation on distributed memory.
///
/// @param grid is the communicator grid on which the matrix @p mat has been distributed,
/// @param grid is the communicator grid on which the matrix @p mat has been distributed
///
/// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
/// @param mat contains the Hermitian matrix A
/// @param eigenvalues is a N x 1 matrix which on output contains the eigenvalues
/// @param eigenvectors is a N x N matrix which on output contains the eigenvectors
///
/// @param[in,out] mat contains the Hermitian matrix A
/// @pre @p mat is distributed according to @p grid
/// @pre @p mat has size (N x N)
/// @pre @p mat has blocksize (NB x NB)
/// @pre @p mat has tilesize (NB x NB)
///
/// @param[out] eigenvalues contains the eigenvalues
/// @pre @p eigenvalues is stored on all ranks
/// @pre @p eigenvalues has size (N x 1)
/// @pre @p eigenvalues has blocksize (NB x 1)
/// @pre @p eigenvalues has tilesize (NB x 1)
///
/// @param[out] eigenvectors contains the eigenvectors
/// @pre @p eigenvectors is distributed according to @p grid
/// @pre @p eigenvectors has size (N x N)
/// @pre @p eigenvectors has blocksize (NB x NB)
/// @pre @p eigenvectors has tilesize (NB x NB)
template <Backend B, Device D, class T>
void hermitian_eigensolver(comm::CommunicatorGrid grid, blas::Uplo uplo, Matrix<T, D>& mat,
Matrix<BaseType<T>, D>& eigenvalues, Matrix<T, D>& eigenvectors) {
Expand Down Expand Up @@ -126,10 +163,17 @@ void hermitian_eigensolver(comm::CommunicatorGrid grid, blas::Uplo uplo, Matrix<
///
/// Implementation on distributed memory.
///
/// @return struct ReturnEigensolverType with eigenvalues, as a vector<T>, and eigenvectors as a Matrix
/// @param grid is the communicator grid on which the matrix @p mat has been distributed,
/// @return struct ReturnEigensolverType with eigenvalues and eigenvectors as a Matrix
///
/// @param grid is the communicator grid on which the matrix @p mat has been distributed
///
/// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
/// @param mat contains the Hermitian matrix A
///
/// @param[in,out] mat contains the Hermitian matrix A
/// @pre @p mat is distributed according to @p grid
/// @pre @p mat has size (N x N)
/// @pre @p mat has blocksize (NB x NB)
/// @pre @p mat has tilesize (NB x NB)
template <Backend B, Device D, class T>
EigensolverResult<T, D> hermitian_eigensolver(comm::CommunicatorGrid grid, blas::Uplo uplo,
Matrix<T, D>& mat) {
Expand Down
Loading

0 comments on commit e1694e8

Please sign in to comment.