diff --git a/doc/Doxyfile b/doc/Doxyfile index 0221bb93..48f244ce 100644 --- a/doc/Doxyfile +++ b/doc/Doxyfile @@ -875,31 +875,7 @@ INPUT = \ ../include/SPTK/conversion/waveform_to_autocorrelation.h \ ../include/SPTK/filter \ ../include/SPTK/generation \ - ../include/SPTK/math/discrete_cosine_transform.h \ - ../include/SPTK/math/distance_calculation.h \ - ../include/SPTK/math/entropy_calculation.h \ - ../include/SPTK/math/durand_kerner_method.h \ - ../include/SPTK/math/dynamic_time_warping.h \ - ../include/SPTK/math/fast_fourier_transform.h \ - ../include/SPTK/math/frequency_transform.h \ - ../include/SPTK/math/gaussian_mixture_modeling.h \ - ../include/SPTK/math/gaussian_mixture_model_based_conversion.h \ - ../include/SPTK/math/histogram_calculation.h \ - ../include/SPTK/math/inverse_discrete_cosine_transform.h \ - ../include/SPTK/math/inverse_fast_fourier_transform.h \ - ../include/SPTK/math/levinson_durbin_recursion.h \ - ../include/SPTK/math/minmax_accumulation.h \ - ../include/SPTK/math/principal_component_analysis.h \ - ../include/SPTK/math/real_valued_fast_fourier_transform.h \ - ../include/SPTK/math/real_valued_inverse_fast_fourier_transform.h \ - ../include/SPTK/math/reverse_levinson_durbin_recursion.h \ - ../include/SPTK/math/scalar_operation.h \ - ../include/SPTK/math/statistics_accumulation.h \ - ../include/SPTK/math/toeplitz_plus_hankel_system_solver.h \ - ../include/SPTK/math/two_dimensional_fast_fourier_transform.h \ - ../include/SPTK/math/two_dimensional_inverse_fast_fourier_transform.h \ - ../include/SPTK/math/two_dimensional_real_valued_fast_fourier_transform.h \ - ../include/SPTK/math/vandermonde_system_solver.h \ + ../include/SPTK/math \ ../include/SPTK/utils/data_symmetrizing.h \ ../include/SPTK/utils/misc_utils.h \ ../include/SPTK/window/data_windowing.h \ diff --git a/doc/utils/math.rst b/doc/utils/math.rst index 5f8b5cff..c97fcd82 100644 --- a/doc/utils/math.rst +++ b/doc/utils/math.rst @@ -1,6 +1,18 @@ math ==== +.. doxygenclass:: sptk::Matrix + :members: + +.. doxygenclass:: sptk::Matrix2D + :members: + +.. doxygenclass:: sptk::SymmetricMatrix + :members: + +.. doxygenclass:: sptk::SymmetricSystemSolver + :members: + .. doxygenclass:: sptk::ToeplitzPlusHankelSystemSolver :members: diff --git a/include/SPTK/math/distance_calculation.h b/include/SPTK/math/distance_calculation.h index 16010589..67d5f07c 100644 --- a/include/SPTK/math/distance_calculation.h +++ b/include/SPTK/math/distance_calculation.h @@ -101,6 +101,7 @@ class DistanceCalculation { * @param[in] vector1 @f$M@f$-th order vector. * @param[in] vector2 @f$M@f$-th order vector. * @param[out] distance Distance between the two vectors. + * @return True on success, false on failure. */ bool Run(const std::vector& vector1, const std::vector& vector2, double* distance) const; diff --git a/include/SPTK/math/fourier_transform.h b/include/SPTK/math/fourier_transform.h index 3a59c116..c2cd6d62 100644 --- a/include/SPTK/math/fourier_transform.h +++ b/include/SPTK/math/fourier_transform.h @@ -51,40 +51,80 @@ namespace sptk { +/** + * Fourier transform wrapper. + */ class FourierTransform { public: + /** + * Inteface of Fourier transform. + */ class FourierTransformInterface { public: virtual ~FourierTransformInterface() { } + /** + * @return DFT length. + */ virtual int GetLength() const = 0; + /** + * @return True if this object is valid. + */ virtual bool IsValid() const = 0; + /** + * @param[in] real_part_input @f$L@f$-length real part of input. + * @param[in] imag_part_input @f$L@f$-length imaginary part of input. + * @param[out] real_part_output @f$L@f$-length real part of output. + * @param[out] imag_part_output @f$L@f$-length imaginary part of output. + * @return True on success, false on failure. + */ virtual bool Run(const std::vector& real_part_input, const std::vector& imag_part_input, std::vector* real_part_output, std::vector* imag_part_output) const = 0; - virtual bool Run(std::vector* real_part_output, - std::vector* imag_part_output) const = 0; + /** + * @param[in,out] real_part Real part. + * @param[in,out] imag_part Imaginary part. + * @return True on success, false on failure. + */ + virtual bool Run(std::vector* real_part, + std::vector* imag_part) const = 0; }; + /** + * @param[in] length DFT length, @f$L@f$. + */ explicit FourierTransform(int length); ~FourierTransform() { delete fourier_transform_; } + /** + * @return DFT length. + */ int GetLength() const { return fourier_transform_->GetLength(); } + /** + * @return True if this object is valid. + */ bool IsValid() const { return fourier_transform_->IsValid(); } + /** + * @param[in] real_part_input @f$L@f$-length real part of input. + * @param[in] imag_part_input @f$L@f$-length imaginary part of input. + * @param[out] real_part_output @f$L@f$-length real part of output. + * @param[out] imag_part_output @f$L@f$-length imaginary part of output. + * @return True on success, false on failure. + */ bool Run(const std::vector& real_part_input, const std::vector& imag_part_input, std::vector* real_part_output, @@ -93,6 +133,11 @@ class FourierTransform { real_part_output, imag_part_output); } + /** + * @param[in,out] real_part Real part. + * @param[in,out] imag_part Imaginary part. + * @return True on success, false on failure. + */ bool Run(std::vector* real_part, std::vector* imag_part) const { return fourier_transform_->Run(real_part, imag_part); diff --git a/include/SPTK/math/matrix.h b/include/SPTK/math/matrix.h index c7b18008..8d101367 100644 --- a/include/SPTK/math/matrix.h +++ b/include/SPTK/math/matrix.h @@ -8,7 +8,7 @@ // Interdisciplinary Graduate School of // // Science and Engineering // // // -// 1996-2019 Nagoya Institute of Technology // +// 1996-2020 Nagoya Institute of Technology // // Department of Computer Science // // // // All rights reserved. // @@ -49,104 +49,187 @@ namespace sptk { +/** + * Matrix. + */ class Matrix { public: - // + /** + * @param[in] num_row Number of rows. + * @param[in] num_column Number of columns. + */ explicit Matrix(int num_row = 0, int num_column = 0); - // + /** + * @param[in] num_row Number of rows. + * @param[in] num_column Number of columns. + * @param[in] vector Diagonal elements. + */ Matrix(int num_row, int num_column, const std::vector& vector); - // + /** + * @param[in] matrix Matrix. + */ Matrix(const Matrix& matrix); - // + /** + * @param[in] matrix Matrix. + */ Matrix& operator=(const Matrix& matrix); - // virtual ~Matrix() { } - // + /** + * @return Number of rows. + */ int GetNumRow() const { return num_row_; } - // + /** + * @return Number of columns. + */ int GetNumColumn() const { return num_column_; } - // + /** + * Resize matrix. + * + * @param[in] num_row Number of rows. + * @param[in] num_column Number of columns. + */ void Resize(int num_row, int num_column); - // + /** + * @param[in] row Row. + */ double* operator[](int row) { return index_[row]; } - // + /** + * @param[in] row Row. + */ const double* operator[](int row) const { return index_[row]; } - // + /** + * Get element. + * + * @param[in] row i. + * @param[in] column j. + * @return (i, j)-th element. + */ double& At(int row, int column); - // + /** + * Get element. + * + * @param[in] row i. + * @param[in] column j. + * @return (i, j)-th element. + */ const double& At(int row, int column) const; - // + /** + * @param[in] matrix Addend. + * @return Sum. + */ Matrix& operator+=(const Matrix& matrix); - // + /** + * @param[in] matrix Subtrahend. + * @return Difference. + */ Matrix& operator-=(const Matrix& matrix); - // + /** + * @param[in] matrix Multiplicand. + * @return Product. + */ Matrix& operator*=(const Matrix& matrix); - // + /** + * @param[in] matrix Addend. + * @return Sum. + */ Matrix operator+(const Matrix& matrix) const; - // + /** + * @param[in] matrix Subtrahend. + * @return Difference. + */ Matrix operator-(const Matrix& matrix) const; - // + /** + * @param[in] matrix Multiplicand. + * @return Product. + */ Matrix operator*(const Matrix& matrix) const; - // + /** + * Negate. + * + * @return Negated matrix. + */ Matrix operator-() const; - // + /** + * Overwrite all elements with a value. + * + * @param[in] value Value. + */ void Fill(double value); - // + /** + * Overwrite diagonal elements with a value. + * + * @param[in] value Diagonal value. + */ void FillDiagonal(double value); - // + /** + * Negate all elements of matrix. + */ void Negate(); - // + /** + * Transpose matrix. + * + * @param[out] transposed_matrix Transposed matrix. + * @return True on success, false on failure. + */ bool Transpose(Matrix* transposed_matrix) const; - // + /** + * Get submatrix. + * + * @param[in] row_offset Offset of row. + * @param[in] num_row_of_submatrix Number of rows of submatrix. + * @param[in] column_offset Offset of column. + * @param[in] num_column_of_submatrix Number of columns of submatrix. + * @param[out] submatrix Submatrix. + * @return True on success, false on failure. + */ bool GetSubmatrix(int row_offset, int num_row_of_submatrix, int column_offset, int num_column_of_submatrix, Matrix* submatrix) const; - // + /** + * Compute determinant. + * + * @param[out] determinant Determinant. + * @return True on success, false on failure. + */ bool GetDeterminant(double* determinant) const; private: - // int num_row_; - - // int num_column_; - // std::vector data_; - - // std::vector index_; }; diff --git a/include/SPTK/math/matrix2d.h b/include/SPTK/math/matrix2d.h index 5bff234a..669d9dd5 100644 --- a/include/SPTK/math/matrix2d.h +++ b/include/SPTK/math/matrix2d.h @@ -8,7 +8,7 @@ // Interdisciplinary Graduate School of // // Science and Engineering // // // -// 1996-2019 Nagoya Institute of Technology // +// 1996-2020 Nagoya Institute of Technology // // Department of Computer Science // // // // All rights reserved. // @@ -49,80 +49,165 @@ namespace sptk { +/** + * 2D matrix. + */ class Matrix2D { public: - // + /** + * Make 2D matrix. + */ Matrix2D(); - // + /** + * @param[in] matrix 2D matrix. + */ Matrix2D(const Matrix2D& matrix); - // + /** + * @param[in] matrix 2D matrix. + */ Matrix2D& operator=(const Matrix2D& matrix); - // virtual ~Matrix2D() { } - // + /** + * @param[in] row Row. + */ double* operator[](int row) { return &data_.x_[row + row]; } - // + /** + * @param[in] row Row. + */ const double* operator[](int row) const { return &data_.x_[row + row]; } - // + /** + * Get element. + * + * @param[in] row i. + * @param[in] column j. + * @return (i, j)-th element. + */ double& At(int row, int column); - // + /** + * Get element. + * + * @param[in] row i. + * @param[in] column j. + * @return (i, j)-th element. + */ const double& At(int row, int column) const; - // + /** + * Compute sum. + * + * @param[in] matrix Addend. + * @param[in,out] output Result. + * @return True on success, false on failure. + */ static bool Add(const Matrix2D& matrix, Matrix2D* output); - // + /** + * Compute sum. + * + * @param[in] first_matrix Augend. + * @param[in] second_matrix Addend. + * @param[out] output Result. + * @return True on success, false on failure. + */ static bool Add(const Matrix2D& first_matrix, const Matrix2D& second_matrix, Matrix2D* output); - // + /** + * Compute difference. + * + * @param[in] matrix Subtrahend. + * @param[in,out] output Result. + * @return True on success, false on failure. + */ static bool Subtract(const Matrix2D& matrix, Matrix2D* output); - // + /** + * Compute difference. + * + * @param[in] first_matrix Minuend. + * @param[in] second_matrix Subtrahend. + * @param[out] output Result. + * @return True on success, false on failure. + */ static bool Subtract(const Matrix2D& first_matrix, const Matrix2D& second_matrix, Matrix2D* output); - // + /** + * Compute Ax. + * + * @param[in] matrix A. + * @param[in] column_vector x. + * @param[out] output Result. + * @return True on success, false on failure. + */ static bool Multiply(const Matrix2D& matrix, const std::vector& column_vector, std::vector* output); - // + /** + * Compute AB. + * + * @param[in] first_matrix A. + * @param[in] second_matrix B. + * @param[out] output Result. + * @return True on success, false on failure. + */ static bool Multiply(const Matrix2D& first_matrix, const Matrix2D& second_matrix, Matrix2D* output); - // + /** + * Overwrite all elements with a value. + * + * @param[in] value Value. + */ void Fill(double value); - // + /** + * Overwrite diagonal elements with a value. + * + * @param[in] value Diagonal value. + */ void FillDiagonal(double value); - // + /** + * Negate all elements of matrix. + */ void Negate(); - // + /** + * Negate all elements of matrix. + */ void Negate(const Matrix2D& matrix); - // + /** + * Compute cross-transpose matrix. + * + * @param[out] transposed_matrix Cross-transposed matrix. + * @return True on success, false on failure. + */ bool CrossTranspose(Matrix2D* transposed_matrix) const; - // + /** + * Compute inverse matrix. + * + * @param[out] inverse_matrix Inverse matrix. + * @return True on success, false on failure. + */ bool Invert(Matrix2D* inverse_matrix) const; private: - // union { double x_[4]; struct { diff --git a/include/SPTK/math/symmetric_matrix.h b/include/SPTK/math/symmetric_matrix.h index 2e9c4141..bc344f47 100644 --- a/include/SPTK/math/symmetric_matrix.h +++ b/include/SPTK/math/symmetric_matrix.h @@ -8,7 +8,7 @@ // Interdisciplinary Graduate School of // // Science and Engineering // // // -// 1996-2019 Nagoya Institute of Technology // +// 1996-2020 Nagoya Institute of Technology // // Department of Computer Science // // // // All rights reserved. // @@ -49,87 +49,156 @@ namespace sptk { +/** + * Symmetric matrix. + */ class SymmetricMatrix { public: + /** + * A row of symmetric matrix.a + */ class Row { public: - Row(const SymmetricMatrix& symmetric_matrix, int row) - : symmetric_matrix_(symmetric_matrix), row_(row) { + /** + * @param[in] matrix Symmetric matrix. + * @param[in] row Row index. + */ + Row(const SymmetricMatrix& matrix, int row) : matrix_(matrix), row_(row) { } + virtual ~Row() { } + + /** + * @param[in] column Column index. + * @return Element. + */ double& operator[](int column); + + /** + * @param[in] column Column index. + * @return Element. + */ const double& operator[](int column) const; private: - const SymmetricMatrix& symmetric_matrix_; + const SymmetricMatrix& matrix_; const int row_; + friend class SymmetricMatrix; Row(const Row&); void operator=(const Row&); }; - // + /** + * @param[in] num_dimension Size of matrix. + */ explicit SymmetricMatrix(int num_dimension = 0); - // - SymmetricMatrix(const SymmetricMatrix& symmetric_matrix); + /** + * @param[in] matrix Symmetric matrix. + */ + SymmetricMatrix(const SymmetricMatrix& matrix); - // - SymmetricMatrix& operator=(const SymmetricMatrix& symmetric_matrix); + /** + * @param[in] matrix Symmetric matrix. + */ + SymmetricMatrix& operator=(const SymmetricMatrix& matrix); - // virtual ~SymmetricMatrix() { } - // + /** + * @return Number of dimensions. + */ int GetNumDimension() const { return num_dimension_; } - // + /** + * Resize matrix. + * + * @param[in] num_dimension Number of dimensions. + */ void Resize(int num_dimension); - // + /** + * @param[in] row Row. + */ Row operator[](int row) { return Row(*this, row); } - // + /** + * @param[in] row Row. + */ const Row operator[](int row) const { return Row(*this, row); } - // + /** + * Get element. + * + * @param[in] row i. + * @param[in] column j. + * @return (i, j)-th element. + */ double& At(int row, int column); - // + /** + * Get element. + * + * @param[in] row i. + * @param[in] column j. + * @return (i, j)-th element. + */ const double& At(int row, int column) const; - // + /** + * Overwrite all elements with a value. + * + * @param[in] value Value. + */ void Fill(double value); - // + /** + * Get diagonal elements. + * + * @param[out] diagonal_elements Diagonal elements. + * @return True on success, false on failure. + */ bool GetDiagonal(std::vector* diagonal_elements) const; - // + /** + * Set diagonal elements. + * + * @param[in] diagonal_elements Diagonal elements. + * @return True on success, false on failure. + */ bool SetDiagonal(const std::vector& diagonal_elements) const; - // + /** + * Perform Cholesky decomposition. + * + * @param[out] lower_triangular_matrix Lower triangular matrix. + * @param[out] diagonal_elements Diagonal elements. + * @return True on success, false on failure. + */ bool CholeskyDecomposition(SymmetricMatrix* lower_triangular_matrix, std::vector* diagonal_elements) const; - // + /** + * Compute inverse matrix. + * + * @param[out] inverse_matrix Inverse matrix. + * @return True on success, false on failure. + */ bool Invert(SymmetricMatrix* inverse_matrix) const; private: - // int num_dimension_; - // std::vector data_; - - // std::vector index_; }; diff --git a/include/SPTK/math/symmetric_system_solver.h b/include/SPTK/math/symmetric_system_solver.h index 80564fda..42b46476 100644 --- a/include/SPTK/math/symmetric_system_solver.h +++ b/include/SPTK/math/symmetric_system_solver.h @@ -8,7 +8,7 @@ // Interdisciplinary Graduate School of // // Science and Engineering // // // -// 1996-2019 Nagoya Institute of Technology // +// 1996-2020 Nagoya Institute of Technology // // Department of Computer Science // // // // All rights reserved. // @@ -52,52 +52,85 @@ namespace sptk { +/** + * Solve the following symmetric system: + * @f[ + * \boldsymbol{A} \boldsymbol{x} = \boldsymbol{b}, + * @f] + * where @f$\boldsymbol{A}@f$ is a symmetric matrix. + * + * The inputs are @f$\boldsymbol{A}@f$ and @f$M@f$-th order constant vector: + * @f[ + * \begin{array}{cccc} + * b(0), & b(1), & \ldots, & b(M). + * \end{array} + * @f] + * The outputs are the unknown coefficients + * @f[ + * \begin{array}{cccc} + * x(0), & x(1), & \ldots, & x(M). + * \end{array} + * @f] + */ class SymmetricSystemSolver { public: + /** + * Buffer for SymmetricSystemSolver class. + */ class Buffer { public: Buffer() { } + virtual ~Buffer() { } private: SymmetricMatrix inverse_matrix_; + friend class SymmetricSystemSolver; DISALLOW_COPY_AND_ASSIGN(Buffer); }; - // + /** + * @param[in] num_order Order of vector, @f$M@f$. + */ explicit SymmetricSystemSolver(int num_order); - // virtual ~SymmetricSystemSolver() { } - // + /** + * @return Order of vector. + */ int GetNumOrder() const { return num_order_; } - // + /** + * @return True if this object is valid. + */ bool IsValid() const { return is_valid_; } - // + /** + * @param[in] coefficient_matrix @f$(M+1, M+1)@f$ matrix @f$\boldsymbol{A}@f$. + * @param[in] constant_vector @f$M@f$-th order vector @f$\boldsymbol{b}@f$. + * @param[out] solution_vector @f$M@f$-th order vector @f$\boldsymbol{x}@f$. + * @param[out] buffer Buffer. + * @return True on success, false on failure. + */ bool Run(const SymmetricMatrix& coefficient_matrix, const std::vector& constant_vector, std::vector* solution_vector, SymmetricSystemSolver::Buffer* buffer) const; private: - // const int num_order_; - // bool is_valid_; - // DISALLOW_COPY_AND_ASSIGN(SymmetricSystemSolver); }; diff --git a/src/math/matrix.cc b/src/math/matrix.cc index 78472e40..dbe49ea9 100644 --- a/src/math/matrix.cc +++ b/src/math/matrix.cc @@ -8,7 +8,7 @@ // Interdisciplinary Graduate School of // // Science and Engineering // // // -// 1996-2019 Nagoya Institute of Technology // +// 1996-2020 Nagoya Institute of Technology // // Department of Computer Science // // // // All rights reserved. // diff --git a/src/math/matrix2d.cc b/src/math/matrix2d.cc index a3c3ea49..af5aecde 100644 --- a/src/math/matrix2d.cc +++ b/src/math/matrix2d.cc @@ -8,7 +8,7 @@ // Interdisciplinary Graduate School of // // Science and Engineering // // // -// 1996-2019 Nagoya Institute of Technology // +// 1996-2020 Nagoya Institute of Technology // // Department of Computer Science // // // // All rights reserved. // diff --git a/src/math/symmetric_matrix.cc b/src/math/symmetric_matrix.cc index e99acf0f..a2c741b7 100644 --- a/src/math/symmetric_matrix.cc +++ b/src/math/symmetric_matrix.cc @@ -8,7 +8,7 @@ // Interdisciplinary Graduate School of // // Science and Engineering // // // -// 1996-2019 Nagoya Institute of Technology // +// 1996-2020 Nagoya Institute of Technology // // Department of Computer Science // // // // All rights reserved. // @@ -65,7 +65,7 @@ double& SymmetricMatrix::Row::operator[](int column) { if (row < column) { std::swap(row, column); } - return symmetric_matrix_.index_[row][column]; + return matrix_.index_[row][column]; } const double& SymmetricMatrix::Row::operator[](int column) const { @@ -73,7 +73,7 @@ const double& SymmetricMatrix::Row::operator[](int column) const { if (row < column) { std::swap(row, column); } - return symmetric_matrix_.index_[row][column]; + return matrix_.index_[row][column]; } SymmetricMatrix::SymmetricMatrix(int num_dimension) @@ -86,9 +86,9 @@ SymmetricMatrix::SymmetricMatrix(int num_dimension) } } -SymmetricMatrix::SymmetricMatrix(const SymmetricMatrix& symmetric_matrix) - : num_dimension_(symmetric_matrix.num_dimension_) { - data_ = symmetric_matrix.data_; +SymmetricMatrix::SymmetricMatrix(const SymmetricMatrix& matrix) + : num_dimension_(matrix.num_dimension_) { + data_ = matrix.data_; index_.resize(num_dimension_); for (int i(0), j(0); i < num_dimension_; ++i, j += i) { @@ -96,11 +96,10 @@ SymmetricMatrix::SymmetricMatrix(const SymmetricMatrix& symmetric_matrix) } } -SymmetricMatrix& SymmetricMatrix::operator=( - const SymmetricMatrix& symmetric_matrix) { - if (this != &symmetric_matrix) { - num_dimension_ = symmetric_matrix.num_dimension_; - data_ = symmetric_matrix.data_; +SymmetricMatrix& SymmetricMatrix::operator=(const SymmetricMatrix& matrix) { + if (this != &matrix) { + num_dimension_ = matrix.num_dimension_; + data_ = matrix.data_; index_.resize(num_dimension_); for (int i(0), j(0); i < num_dimension_; ++i, j += i) {