From 0455d14a6c0e03ba14e1218f8053e608606dd024 Mon Sep 17 00:00:00 2001 From: Cody Michael Jones <46515483+cm-jones@users.noreply.github.com> Date: Tue, 9 Jul 2024 21:39:54 -0500 Subject: [PATCH] Update docstrings --- include/matrix.hpp | 314 ++++++++++++++++++++++++++++----------------- 1 file changed, 197 insertions(+), 117 deletions(-) diff --git a/include/matrix.hpp b/include/matrix.hpp index f146dc7..1943d55 100644 --- a/include/matrix.hpp +++ b/include/matrix.hpp @@ -4,27 +4,24 @@ #include #include -#include -#include +#include +#include +#include #include namespace cramer { -template -class Vector; - +/** + * @brief Represents a matrix of elements of type T. + * + * @tparam T The type of elements stored in the matrix. + */ template class Matrix { private: - size_t rows; - size_t cols; - std::vector> data; - - /** - * @brief Calculates the maximum norm of the matrix. - * @return The maximum norm value. - */ - T max_norm() const; + size_t rows; /**< The number of rows in the matrix. */ + size_t cols; /**< The number of columns in the matrix. */ + std::vector> data; /**< The underlying container storing the matrix elements. */ public: /** @@ -33,294 +30,377 @@ class Matrix { Matrix(); /** - * @brief Constructor that creates a matrix with specified dimensions. - * @param rows Number of rows. - * @param cols Number of columns. + * @brief Constructor that creates a matrix of a specified size. + * + * @param rows The number of rows in the matrix. + * @param cols The number of columns in the matrix. */ Matrix(size_t rows, size_t cols); /** - * @brief Constructor that creates a matrix with specified dimensions and - * fills it with a value. - * @param rows Number of rows. - * @param cols Number of columns. - * @param value The value to fill the matrix with. + * @brief Constructor that creates a matrix of a specified size and initializes all elements with a given value. + * + * @param rows The number of rows in the matrix. + * @param cols The number of columns in the matrix. + * @param value The value to initialize all elements with. */ Matrix(size_t rows, size_t cols, const T& value); /** - * @brief Constructor that creates a matrix from a 2D vector. - * @param values The 2D vector to create the matrix from. + * @brief Constructor that creates a matrix from a vector of vectors. + * + * @param values The vector of vectors representing the matrix elements. + * @throws std::invalid_argument If the input vector is empty or the rows have different sizes. */ Matrix(const std::vector>& values); /** * @brief Constructor that creates a matrix from an initializer list. - * @param rows Number of rows. - * @param cols Number of columns. - * @param values The initializer list of values to populate the matrix. - * @throws std::invalid_argument if the size of values doesn't match rows * - * cols. + * + * @param rows The number of rows in the matrix. + * @param cols The number of columns in the matrix. + * @param values The initializer list representing the matrix elements. + * @throws std::invalid_argument If the initializer list size does not match the specified dimensions. */ Matrix(size_t rows, size_t cols, std::initializer_list values); /** * @brief Gets the number of rows in the matrix. - * @return The number of rows. + * + * @return The number of rows in the matrix. */ size_t get_rows() const; /** * @brief Gets the number of columns in the matrix. - * @return The number of columns. + * + * @return The number of columns in the matrix. */ size_t get_cols() const; /** - * @brief Creates an identity matrix of specified size. - * @param size The size of the square identity matrix. + * @brief Creates an identity matrix of a specified size. + * + * @param size The size of the identity matrix. * @return The identity matrix. */ - static Matrix identity(size_t size); + static Matrix identity(size_t size); /** - * @brief Creates a zero matrix of specified dimensions. - * @param rows Number of rows. - * @param cols Number of columns. - * @return The zero matrix. + * @brief Creates a matrix of zeros of a specified size. + * + * @param rows The number of rows in the matrix. + * @param cols The number of columns in the matrix. + * @return The matrix of zeros. */ - static Matrix zeros(size_t rows, size_t cols); + static Matrix zeros(size_t rows, size_t cols); /** - * @brief Creates a matrix of ones with specified dimensions. - * @param rows Number of rows. - * @param cols Number of columns. + * @brief Creates a matrix of ones of a specified size. + * + * @param rows The number of rows in the matrix. + * @param cols The number of columns in the matrix. * @return The matrix of ones. */ - static Matrix ones(size_t rows, size_t cols); + static Matrix ones(size_t rows, size_t cols); /** - * @brief Creates a matrix with random values between 0 and 1. - * @param rows Number of rows. - * @param cols Number of columns. + * @brief Creates a random matrix of a specified size. + * + * @param rows The number of rows in the matrix. + * @param cols The number of columns in the matrix. * @return The random matrix. + * @throws std::runtime_error If the random matrix generation is not supported for the given type. */ - static Matrix random(size_t rows, size_t cols); + static Matrix random(size_t rows, size_t cols); /** - * @brief Access operator for matrix elements. - * @param row Row index. - * @param col Column index. - * @return Reference to the element at (row, col). + * @brief Overloads the () operator to access elements of the matrix. + * + * @param row The row index of the element to access. + * @param col The column index of the element to access. + * @return A reference to the element at the specified indices. */ T& operator()(size_t row, size_t col); /** - * @brief Const access operator for matrix elements. - * @param row Row index. - * @param col Column index. - * @return Const reference to the element at (row, col). + * @brief Overloads the () operator to access elements of the matrix (const version). + * + * @param row The row index of the element to access. + * @param col The column index of the element to access. + * @return A const reference to the element at the specified indices. */ const T& operator()(size_t row, size_t col) const; /** - * @brief Equality comparison operator. + * @brief Overloads the == operator to check for matrix equality. + * * @param other The matrix to compare with. - * @return True if matrices are equal, false otherwise. + * @return true if the matrices are equal, false otherwise. */ bool operator==(const Matrix& other) const; /** - * @brief Addition operator. - * @param other The matrix to add. - * @return The sum of the two matrices. + * @brief Overloads the + operator to perform matrix addition. + * + * @param other The matrix to add to the current matrix. + * @return A new matrix that is the result of adding the current matrix and the other matrix. + * @throws std::invalid_argument If the matrices have different dimensions. */ Matrix operator+(const Matrix& other) const; /** - * @brief Addition assignment operator. - * @param other The matrix to add. - * @return Reference to the modified matrix. + * @brief Overloads the += operator to perform matrix addition and assignment. + * + * @param other The matrix to add to the current matrix. + * @return A reference to the updated current matrix. + * @throws std::invalid_argument If the matrices have different dimensions. */ Matrix& operator+=(const Matrix& other); /** - * @brief Subtraction operator. - * @param other The matrix to subtract. - * @return The difference of the two matrices. + * @brief Overloads the - operator to perform matrix subtraction. + * + * @param other The matrix to subtract from the current matrix. + * @return A new matrix that is the result of subtracting the other matrix from the current matrix. + * @throws std::invalid_argument If the matrices have different dimensions. */ Matrix operator-(const Matrix& other) const; /** - * @brief Subtraction assignment operator. - * @param other The matrix to subtract. - * @return Reference to the modified matrix. + * @brief Overloads the -= operator to perform matrix subtraction and assignment. + * + * @param other The matrix to subtract from the current matrix. + * @return A reference to the updated current matrix. + * @throws std::invalid_argument If the matrices have different dimensions. */ Matrix& operator-=(const Matrix& other); /** - * @brief Scalar multiplication operator. - * @param scalar The scalar to multiply by. - * @return The product of the matrix and the scalar. + * @brief Overloads the * operator to perform scalar multiplication. + * + * @param scalar The scalar to multiply the matrix by. + * @return A new matrix that is the result of multiplying the current matrix by the scalar. */ Matrix operator*(const T& scalar) const; /** - * @brief Scalar multiplication assignment operator. - * @param scalar The scalar to multiply by. - * @return Reference to the modified matrix. + * @brief Overloads the *= operator to perform scalar multiplication and assignment. + * + * @param scalar The scalar to multiply the matrix by. + * @return A reference to the updated current matrix. */ Matrix& operator*=(const T& scalar); /** - * @brief Matrix multiplication operator. - * @param other The matrix to multiply with. - * @return The product of the two matrices. + * @brief Overloads the * operator to perform matrix multiplication. + * + * @param other The matrix to multiply the current matrix by. + * @return A new matrix that is the result of multiplying the current matrix by the other matrix. + * @throws std::invalid_argument If the dimensions of the matrices do not match for multiplication. */ Matrix operator*(const Matrix& other) const; /** - * @brief Multiplies the matrix with a vector. - * @param vec The vector to multiply with. - * @return The resulting vector. + * @brief Multiplies the matrix by a vector. + * + * @param vec The vector to multiply the matrix by. + * @return The resulting vector after matrix-vector multiplication. + * @throws std::invalid_argument If the dimensions of the matrix and vector do not match for multiplication. */ Vector multiply_vector(const Vector& vec) const; /** * @brief Checks if the matrix is square. - * @return True if the matrix is square, false otherwise. + * + * @return true if the matrix is square, false otherwise. */ bool is_square() const; /** * @brief Checks if the matrix is diagonal. - * @return True if the matrix is diagonal, false otherwise. + * + * @return true if the matrix is diagonal, false otherwise. */ bool is_diagonal() const; /** * @brief Checks if the matrix is symmetric. - * @return True if the matrix is symmetric, false otherwise. + * + * @return true if the matrix is symmetric, false otherwise. */ bool is_symmetric() const; /** * @brief Checks if the matrix is invertible. - * @return True if the matrix is invertible, false otherwise. + * + * @return true if the matrix is invertible, false otherwise. */ bool is_invertible() const; /** - * @brief Checks if the matrix is Hermitian. - * @return True if the matrix is Hermitian, false otherwise. + * @brief Checks if the matrix is Hermitian (conjugate symmetric). + * + * @return true if the matrix is Hermitian, false otherwise. */ bool is_hermitian() const; /** * @brief Checks if the matrix is orthogonal. - * @return True if the matrix is orthogonal, false otherwise. + * + * @return true if the matrix is orthogonal, false otherwise. */ bool is_orthogonal() const; /** * @brief Calculates the trace of the matrix. + * * @return The trace of the matrix. */ T trace() const; /** * @brief Calculates the determinant of the matrix. + * * @return The determinant of the matrix. + * @throws std::invalid_argument If the matrix is not square. */ T det() const; /** * @brief Calculates the determinant of the matrix using LU decomposition. + * * @return The determinant of the matrix. + * @throws std::invalid_argument If the matrix is not square. */ T det_via_lu() const; + /** + * @brief Calculates the rank of the matrix. + * + * @return The rank of the matrix. + */ + size_t rank() const; + /** * @brief Calculates the transpose of the matrix. - * @return The transposed matrix. + * + * @return The transpose of the matrix. */ Matrix transpose() const; /** * @brief Calculates the inverse of the matrix. - * @return The inverted matrix. + * + * @return The inverse of the matrix. + * @throws std::invalid_argument If the matrix is not square or invertible. */ Matrix inverse() const; /** - * @brief Calculates the adjoint of the matrix. - * @return The adjoint matrix. + * @brief Calculates the adjoint (adjugate) of the matrix. + * + * @return The adjoint of the matrix. + * @throws std::invalid_argument If the matrix is not square. */ Matrix adjoint() const; /** * @brief Calculates the conjugate of the matrix. - * @return The conjugate matrix. + * + * @return The conjugate of the matrix. + * @throws std::runtime_error If the conjugate operation is not supported for the given type. */ Matrix conjugate() const; /** - * @brief Computes the outer product of two vectors. + * @brief Calculates the exponential of the matrix. + * + * @return The exponential of the matrix. + * @throws std::invalid_argument If the matrix is not square. + */ + Matrix exp() const; + + /** + * @brief Calculates the matrix raised to a specified integer power. + * + * @param n The power to raise the matrix to. + * @return The matrix raised to the specified power. + * @throws std::invalid_argument If the matrix is not square. + */ + Matrix pow(int n) const; + + /** + * @brief Calculates the square root of the matrix. + * + * @return The square root of the matrix. + * @throws std::invalid_argument If the matrix is not square. + * @throws std::runtime_error If the square root iteration does not converge. + */ + Matrix sqrt() const; + + /** + * @brief Calculates the natural logarithm of the matrix. * - * - * @param u The first vector. - * @param v The second vector. - * @return Matrix The resulting matrix from the outer product. - * - * @throw std::invalid_argument If the vectors have incompatible sizes. + * @return The natural logarithm of the matrix. + * @throws std::invalid_argument If the matrix is not square. */ - static Matrix outer(const Vector& u, const Vector& v); + Matrix log() const; /** * @brief Performs LU decomposition of the matrix. - * @return A pair of matrices (L, U) where L is lower triangular and U is - * upper triangular. + * + * @return A pair containing the lower and upper triangular matrices (L and U). + * @throws std::invalid_argument If the matrix is not square. */ std::pair, Matrix> lu() const; /** * @brief Performs QR decomposition of the matrix. - * @return A pair of matrices (Q, R) where Q is orthogonal and R is upper - * triangular. + * + * @return A pair containing the orthogonal matrix Q and upper triangular matrix R. */ std::pair, Matrix> qr() const; /** - * @brief Performs Singular Value Decomposition (SVD) of the matrix. - * @return A tuple of matrices (U, S, V) where U and V are orthogonal and S - * is diagonal. + * @brief Performs singular value decomposition (SVD) of the matrix. + * + * @return A tuple containing the left singular vectors (U), singular values (S), and right singular vectors (V). */ std::tuple, Matrix, Matrix> svd() const; /** * @brief Calculates the eigenvalues of the matrix. - * @return A vector of complex eigenvalues. + * + * @return A vector containing the eigenvalues of the matrix. + * @throws std::invalid_argument If the matrix is not square. */ std::vector> eigenvalues() const; /** * @brief Calculates the eigenvectors of the matrix. - * @return A matrix where each column is an eigenvector. + * + * @return A matrix containing the eigenvectors of the matrix. + * @throws std::invalid_argument If the matrix is not square. */ Matrix eigenvectors() const; /** - * @brief Calculates the rank of the matrix. - * @return The rank of the matrix. + * @brief Solves a linear system of equations Ax = b using LU decomposition. + * + * @param b The right-hand side vector b. + * @return The solution vector x. + * @throws std::invalid_argument If the matrix is not square or the dimensions do not match. */ - size_t rank() const; + Vector solve(const Vector& b) const; + private: /** - * @brief Solves the linear system Ax = b. - * @param b The right-hand side vector. - * @return The solution vector x. + * @brief Calculates the maximum norm of the matrix. + * + * @return The maximum norm of the matrix. */ - Vector solve(const Vector& b) const; + T max_norm() const; }; } // namespace cramer