Update docstrings

eth-cscs · Sep 8, 2023 · 828552e · 828552e
1 parent ba566e3
commit 828552e
Show file tree

Hide file tree

Showing 15 changed files with 357 additions and 234 deletions.
diff --git a/include/dlaf/auxiliary/norm.h b/include/dlaf/auxiliary/norm.h
@@ -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,

diff --git a/include/dlaf/eigensolver/band_to_tridiag.h b/include/dlaf/eigensolver/band_to_tridiag.h
@@ -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) {
@@ -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) {

diff --git a/include/dlaf/eigensolver/bt_band_to_tridiag.h b/include/dlaf/eigensolver/bt_band_to_tridiag.h
@@ -42,17 +42,19 @@ namespace dlaf::eigensolver::internal {
 /// 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 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
+/// @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) {
@@ -97,17 +99,19 @@ void bt_band_to_tridiagonal(const SizeType band_size, matrix::Matrix<T, D>& mat_
 /// 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 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 distributed according to grid
-/// @pre mat_hh is distributed according to grid
-/// @pre mat_e has equal tile and block sizes
-/// @pre mat_hh has equal tile and block sizes
+/// @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) {

diff --git a/include/dlaf/eigensolver/bt_reduction_to_band.h b/include/dlaf/eigensolver/bt_reduction_to_band.h
@@ -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) {
@@ -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) {

diff --git a/include/dlaf/eigensolver/eigensolver.h b/include/dlaf/eigensolver/eigensolver.h
@@ -34,22 +34,22 @@ namespace dlaf {
 /// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
 ///
 /// @param[in,out] mat contains the Hermitian matrix A
-/// @pre mat is not distributed
-/// @pre mat has size (N x N)
-/// @pre mat has blocksize (NB x NB)
-/// @pre mat has tilesize (NB x NB)
+/// @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 eigenvalues is not distributed
-/// @pre eigenvalues has size (N x 1)
-/// @pre eigenvalues has blocksize (NB x 1)
-/// @pre eigenvalues has tilesize (NB x 1)
+/// @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 eigenvectors is not distributed
-/// @pre eigenvectors has size (N x N)
-/// @pre eigenvectors has blocksize (NB x NB)
-/// @pre eigenvectors has tilesize (NB x NB)
+/// @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) {
@@ -86,10 +86,10 @@ void hermitian_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat, Matrix<BaseType<T
 /// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
 ///
 /// @param[in,out] mat contains the Hermitian matrix A
-/// @pre mat is not distributed
-/// @pre mat has size (N x N)
-/// @pre mat has blocksize (NB x NB)
-/// @pre mat has tilesize (NB x NB)
+/// @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();
@@ -117,22 +117,22 @@ EigensolverResult<T, D> hermitian_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat
 /// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
 ///
 /// @param[in,out] mat contains the Hermitian matrix A
-/// @pre mat is distributed according to @p grid
-/// @pre mat has size (N x N)
-/// @pre mat has blocksize (NB x NB)
-/// @pre mat has tilesize (NB x NB)
+/// @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 eigenvalues is stored on all ranks
-/// @pre eigenvalues has size (N x 1)
-/// @pre eigenvalues has blocksize (NB x 1)
-/// @pre eigenvalues has tilesize (NB x 1)
+/// @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 eigenvectors is distributed according to @p grid
-/// @pre eigenvectors has size (N x N)
-/// @pre eigenvectors has blocksize (NB x NB)
-/// @pre eigenvectors has tilesize (NB x NB)
+/// @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) {
@@ -171,10 +171,10 @@ void hermitian_eigensolver(comm::CommunicatorGrid grid, blas::Uplo uplo, Matrix<
 /// @param uplo specifies if upper or lower triangular part of @p mat will be referenced
 ///
 /// @param[in,out] mat contains the Hermitian matrix A
-/// @pre mat is distributed according to @p grid
-/// @pre mat has size (N x N)
-/// @pre mat has blocksize (NB x NB)
-/// @pre mat has tilesize (NB x NB)
+/// @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) {

diff --git a/include/dlaf/eigensolver/gen_eigensolver.h b/include/dlaf/eigensolver/gen_eigensolver.h
@@ -34,23 +34,30 @@ namespace dlaf {
 /// Implementation on local memory.
 ///
 /// @param uplo specifies if upper or lower triangular part of @p mat_a and @p mat_b will be referenced
+///
 /// @param mat_a contains the Hermitian matrix A
+/// @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)
+///
 /// @param mat_b contains the Hermitian positive definite matrix B
-/// @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
-/// @pre mat_a is not distributed
-/// @pre mat_a has a square size
-/// @pre mat_a has a square blocksize
-/// @pre mat_a has equal tile and block sizes
-/// @pre mat_b is not distributed
-/// @pre mat_b has a square size
-/// @pre mat_b has a square blocksize
-/// @pre mat_b has equal tile and block sizes
-/// @pre eigenvalues is not distributed
-/// @pre eigenvalues has equal tile and block sizes
-/// @pre eigenvectors is not distributed
-/// @pre eigenvectors has a square blocksize
-/// @pre eigenvectors has equal tile and block sizes
+/// @pre @p mat_b is not distributed
+/// @pre @p mat_b has size (N x N)
+/// @pre @p mat_b has blocksize (NB x NB)
+/// @pre @p mat_b 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 NB)
+/// @pre @p eigenvalues has tilesize (NB x NB)
+///
+/// @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_generalized_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat_a, Matrix<T, D>& mat_b,
                                        Matrix<BaseType<T>, D>& eigenvalues, Matrix<T, D>& eigenvectors) {
@@ -92,16 +99,18 @@ void hermitian_generalized_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat_a, Mat
 ///
 /// @return struct ReturnEigensolverType with eigenvalues, as a vector<T>, and eigenvectors as a Matrix
 /// @param uplo specifies if upper or lower triangular part of @p mat_a and @p mat_b will be referenced
+///
 /// @param mat_a contains the Hermitian matrix A
+/// @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)
+///
 /// @param mat_b contains the Hermitian positive definite matrix B
-/// @pre mat_a is not distributed
-/// @pre mat_a has a square size
-/// @pre mat_a has a square blocksize
-/// @pre mat_a has equal tile and block sizes
-/// @pre mat_b is not distributed
-/// @pre mat_b has a square size
-/// @pre mat_b has a square blocksize
-/// @pre mat_b has equal tile and block sizes
+/// @pre @p mat_b is not distributed
+/// @pre @p mat_b has size (N x N)
+/// @pre @p mat_b has blocksize (NB x NB)
+/// @pre @p mat_b has tilesize (NB x NB)
 template <Backend B, Device D, class T>
 EigensolverResult<T, D> hermitian_generalized_eigensolver(blas::Uplo uplo, Matrix<T, D>& mat_a,
                                                           Matrix<T, D>& mat_b) {
@@ -140,23 +149,30 @@ EigensolverResult<T, D> hermitian_generalized_eigensolver(blas::Uplo uplo, Matri
 ///
 /// @param grid is the communicator grid on which the matrices @p mat_a and @p mat_b have been distributed,
 /// @param uplo specifies if upper or lower triangular part of @p mat_a and @p mat_b will be referenced
+///
 /// @param mat_a contains the Hermitian matrix A
+/// @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)
+///
 /// @param mat_b contains the Hermitian positive definite matrix B
+/// @pre @p mat_b is distributed according to @p grid
+/// @pre @p mat_b has size (N x N)
+/// @pre @p mat_b has blocksize (NB x NB)
+/// @pre @p mat_b has tilesize (NB x NB)
+///
 /// @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
-/// @pre mat_a is distributed according to grid
-/// @pre mat_a has a square size
-/// @pre mat_a has a square blocksize
-/// @pre mat_a has equal tile and block sizes
-/// @pre mat_b is distributed according to grid
-/// @pre mat_b has a square size
-/// @pre mat_b has a square blocksize
-/// @pre mat_b has equal tile and block sizes
-/// @pre eigenvalues is not distributed
-/// @pre eigenvalues has equal tile and block sizes
-/// @pre eigenvectors is distributed according to grid
-/// @pre eigenvectors has a square blocksize
-/// @pre eigenvectors has equal tile and block sizes
+/// @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 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_generalized_eigensolver(comm::CommunicatorGrid grid, blas::Uplo uplo, Matrix<T, D>& mat_a,
                                        Matrix<T, D>& mat_b, Matrix<BaseType<T>, D>& eigenvalues,
@@ -201,16 +217,18 @@ void hermitian_generalized_eigensolver(comm::CommunicatorGrid grid, blas::Uplo u
 /// @return struct ReturnEigensolverType with eigenvalues, as a vector<T>, and eigenvectors as a Matrix
 /// @param grid is the communicator grid on which the matrices @p mat_a and @p mat_b have been distributed,
 /// @param uplo specifies if upper or lower triangular part of @p mat_a and @p mat_b will be referenced
+///
 /// @param mat_a contains the Hermitian matrix A
+/// @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)
+///
 /// @param mat_b contains the Hermitian positive definite matrix B
-/// @pre mat_a is distributed according to grid
-/// @pre mat_a has a square size
-/// @pre mat_a has a square blocksize
-/// @pre mat_a has equal tile and block sizes
-/// @pre mat_b is distributed according to grid
-/// @pre mat_b has a square size
-/// @pre mat_b has a square blocksize
-/// @pre mat_b has equal tile and block sizes
+/// @pre @p mat_b is distributed according to @p grid
+/// @pre @p mat_b has size (N x N)
+/// @pre @p mat_b has blocksize (NB x NB)
+/// @pre @p mat_b has tilesize (NB x NB)
 template <Backend B, Device D, class T>
 EigensolverResult<T, D> hermitian_generalized_eigensolver(comm::CommunicatorGrid grid, blas::Uplo uplo,
                                                           Matrix<T, D>& mat_a, Matrix<T, D>& mat_b) {