add documentation

experiment/power_iteration.cpp

@@ -12,9 +12,10 @@ class Vector {
      * The function `Vector` initializes a vector with the values provided in the `initializer_list`
      * `list`.
      *
-     * @param[in] list The `list` parameter in the code snippet `Vector(std::initializer_list<double>
-     * list) : data(list) {}` is of type `std::initializer_list<double>`. This parameter allows you
-     * to initialize the `Vector` object with a list of `double` values.
+     * @param[in] list The `list` parameter in the code snippet
+     * `Vector(std::initializer_list<double> list) : data(list) {}` is of type
+     * `std::initializer_list<double>`. This parameter allows you to initialize the `Vector` object
+     * with a list of `double` values.
      */
     Vector(std::initializer_list<double> list) : data(list) {}
 
@@ -71,10 +72,10 @@ class Vector {
     /**
      * The `dot` function calculates the dot product of two vectors.
      *
-     * @param[in] other The `other` parameter in the `dot` function is of type `Vector&`, which means it
-     * is a reference to another `Vector` object. This parameter is used to calculate the dot
-     * product of the current `Vector` object with another `Vector` object passed as an argument to
-     * the function
+     * @param[in] other The `other` parameter in the `dot` function is of type `Vector&`, which
+     * means it is a reference to another `Vector` object. This parameter is used to calculate the
+     * dot product of the current `Vector` object with another `Vector` object passed as an argument
+     * to the function
      *
      * @return The `dot` product of the current `Vector` object and the `other` `Vector` object is
      * being returned.
@@ -133,8 +134,8 @@ class Vector {
  * element-wise subtraction of the corresponding elements.
  *
  * @param[in] a The parameter `a` is a constant reference to a `Vector` object.
- * @param[in] b The parameter `b` in the `operator-` function represents a `Vector` object that is being
- * subtracted from another `Vector` object `a`.
+ * @param[in] b The parameter `b` in the `operator-` function represents a `Vector` object that is
+ * being subtracted from another `Vector` object `a`.
  *
  * @return a new `Vector` object that contains the result of subtracting each element of vector `b`
  * from the corresponding element of vector `a`.
@@ -152,8 +153,8 @@ Vector operator-(const Vector& a, const Vector& b) {
  * @param[in] a The parameters `a` and `b` are both of type `Vector`, which is a custom class
  * representing a mathematical vector. The `operator+` function overloads the `+` operator for
  * adding two vectors element-wise.
- * @param[in] b The parameter `b` in the `operator+` function represents a `Vector` object that is being
- * added to another `Vector` object `a`.
+ * @param[in] b The parameter `b` in the `operator+` function represents a `Vector` object that is
+ * being added to another `Vector` object `a`.
  *
  * @return The function `operator+` is returning a new `Vector` object that contains the
  * element-wise sum of the elements of two input `Vector` objects `a` and `b`.
@@ -171,17 +172,18 @@ class Matrix {
     /**
      * The Matrix constructor initializes the data using a list of lists of doubles.
      *
-     * @param[in] list A list of lists of double values that is used to initialize the Matrix object.
+     * @param[in] list A list of lists of double values that is used to initialize the Matrix
+     * object.
      */
     Matrix(std::initializer_list<std::initializer_list<double>> list)
         : data(list.begin(), list.end()) {}
 
     /**
      * The function overloads the * operator to perform matrix-vector multiplication.
      *
-     * @param[in] v The `operator*` function you provided is for multiplying a matrix (represented as a
-     * vector of vectors) by a vector. The `v` parameter in this context represents the vector that
-     * you want to multiply the matrix with.
+     * @param[in] v The `operator*` function you provided is for multiplying a matrix (represented
+     * as a vector of vectors) by a vector. The `v` parameter in this context represents the vector
+     * that you want to multiply the matrix with.
      *
      * @return The `operator*` function is returning a new `Vector` object that is the result of
      * multiplying the current `Vector` object (`this`) with another `Vector` object `v`.
@@ -273,8 +275,9 @@ std::pair<double, int> power_iteration4(const Matrix& A, Vector& x, const Option
  * The function `power_iteration2` implements the power iteration method to find the dominant
  * eigenvalue and eigenvector of a matrix.
  *
- * @param[in] A The parameter `A` in the `power_iteration2` function represents a matrix. It is used for
- * matrix-vector multiplication and eigenvalue calculations within the power iteration algorithm.
+ * @param[in] A The parameter `A` in the `power_iteration2` function represents a matrix. It is used
+ * for matrix-vector multiplication and eigenvalue calculations within the power iteration
+ * algorithm.
  * @param[in,out] x The parameter `x` is a vector that represents the initial guess for the dominant
  * eigenvector of the matrix `A`. It is normalized at the beginning of the `power_iteration2`
  * function to ensure that the calculations are stable and converge properly.
@@ -306,14 +309,14 @@ std::pair<double, int> power_iteration2(const Matrix& A, Vector& x, const Option
  * The function `power_iteration3` implements the power iteration method to find the dominant
  * eigenvalue and eigenvector of a matrix.
  *
- * @param[in] A The parameter `A` in the `power_iteration3` function represents a matrix. It is used in
- * the power iteration algorithm to find the dominant eigenvalue and eigenvector of the matrix.
+ * @param[in] A The parameter `A` in the `power_iteration3` function represents a matrix. It is used
+ * in the power iteration algorithm to find the dominant eigenvalue and eigenvector of the matrix.
  * @param[in,out] x The `x` parameter in the `power_iteration3` function represents the initial
  * vector used in the power iteration algorithm. It is the starting vector that is iteratively
  * transformed and normalized to find the dominant eigenvalue and eigenvector of the given matrix
  * `A`.
- * @param[in] options The `Options` struct likely contains parameters for controlling the behavior of
- * the power iteration algorithm. These parameters could include:
+ * @param[in] options The `Options` struct likely contains parameters for controlling the behavior
+ * of the power iteration algorithm. These parameters could include:
  *
  * @return A std::pair<double, int> is being returned, where the first element of the pair is the
  * dominant eigenvalue (ld) and the second element is the number of iterations (niter) performed.

include/ellalgo/conjugate_gradient.hpp

@@ -80,6 +80,20 @@ class Matrix0 {
     std::vector<std::vector<double>> data;
 };
 
+/**
+ * Solves the linear system Ax = b using the conjugate gradient method.
+ *
+ * @tparam Matrix0 The matrix type, which must support matrix-vector multiplication.
+ * @tparam Vector0 The vector type, which must support vector operations.
+ * @param A The matrix A in the linear system Ax = b.
+ * @param b The right-hand side vector b in the linear system Ax = b.
+ * @param x0 An optional initial guess for the solution vector x.
+ * @param tol The tolerance for the residual norm, used as the stopping criterion.
+ * @param max_iter The maximum number of iterations to perform.
+ * @return The solution vector x.
+ * @throws std::runtime_error if the conjugate gradient method does not converge after the maximum
+ * number of iterations.
+ */
 template <typename Matrix0, typename Vector0>
 inline Vector0 conjugate_gradient(const Matrix0& A, const Vector0& b, const Vector0* x0 = nullptr,
                                   double tol = 1e-5, int max_iter = 1000) {

include/ellalgo/conjugate_gradient2.hpp

@@ -7,8 +7,21 @@
 #include <stdexcept>
 #include <string>
 
-/** The provided code snippet defines a templated function `conjugate_gradient2` that implements the
-Conjugate Gradient method for solving a system of linear equations of the form Ax = b. */
+/**
+ * Solves a system of linear equations Ax = b using the Conjugate Gradient method.
+ *
+ * @tparam Matrix The type of the matrix A.
+ * @tparam Vector The type of the vectors b and x.
+ * @param A The matrix A in the system of linear equations Ax = b.
+ * @param b The right-hand side vector b in the system of linear equations Ax = b.
+ * @param x_vector The initial guess for the solution vector x. This vector will be updated
+ * in-place.
+ * @param tol The tolerance for the residual norm, used as the stopping criterion.
+ * @param max_iter The maximum number of iterations to perform.
+ * @return The solution vector x.
+ * @throws std::runtime_error if the Conjugate Gradient method does not converge after the maximum
+ * number of iterations.
+ */
 template <typename Matrix, typename Vector>
 Vector conjugate_gradient2(const Matrix& A, const Vector& b, Vector& x_vector, double tol = 1e-5,
                            int max_iter = 1000) {

include/ellalgo/linear_algebra.hpp

@@ -10,63 +10,199 @@ template <typename T> class Vector2 {
   public:
     using value_type = T;
 
+    /**
+     * Constructs a Vector2 with the given size, initializing all elements to the default value of
+     * T.
+     *
+     * @param size The size of the Vector2.
+     */
     Vector2(size_t size) : data(size, T{}) {}
+
+    /**
+     * Constructs a Vector2 from a std::vector.
+     *
+     * @param v The std::vector to initialize the Vector2 with.
+     */
     Vector2(const std::vector<T>& v) : data(v) {}
+
+    /**
+     * Destroys the Vector2 object.
+     *
+     * @return None
+     */
     ~Vector2() = default;
+
+    /**
+     * Provides access to the elements of the Vector2 object.
+     *
+     * @param i The index of the element to access.
+     * @return A reference to the element at the specified index.
+     */
     T& operator[](size_t i) { return data[i]; }
+
+    /**
+     * Provides constant access to the elements of the Vector2 object.
+     *
+     * @param i The index of the element to access.
+     * @return A constant reference to the element at the specified index.
+     */
     const T& operator[](size_t i) const { return data[i]; }
+
+    /**
+     * Returns the size of the Vector2 object.
+     *
+     * @return The size of the Vector2 object.
+     */
     size_t size() const { return data.size(); }
 
+    /**
+     * Adds the elements of the given Vector2 to the corresponding elements of this Vector2.
+     *
+     * @param rhs The Vector2 to add to this Vector2.
+     * @return A reference to this Vector2 after the addition.
+     */
     Vector2& operator+=(const Vector2& rhs) {
         for (size_t i = 0; i < size(); ++i) data[i] += rhs[i];
         return *this;
     }
+
+    /**
+     * Subtracts the elements of the given Vector2 from the corresponding elements of this Vector2.
+     *
+     * @param rhs The Vector2 to subtract from this Vector2.
+     * @return A reference to this Vector2 after the subtraction.
+     */
     Vector2& operator-=(const Vector2& rhs) {
         for (size_t i = 0; i < size(); ++i) data[i] -= rhs[i];
         return *this;
     }
+
+    /**
+     * Multiplies each element of the Vector2 by the given scalar value.
+     *
+     * @param scalar The scalar value to multiply the Vector2 elements by.
+     * @return A reference to this Vector2 after the multiplication.
+     */
     Vector2& operator*=(T scalar) {
         for (auto& val : data) val *= scalar;
         return *this;
     }
 
+    /**
+     * Computes the dot product of this Vector2 with the given Vector2.
+     *
+     * @param other The other Vector2 to compute the dot product with.
+     * @return The dot product of this Vector2 and the given Vector2.
+     */
     T dot(const Vector2& other) const {
         T sum = T{};
         for (size_t i = 0; i < size(); ++i) sum += data[i] * other[i];
         return sum;
     }
 
+    /**
+     * Computes the L2 norm (Euclidean length) of the Vector2.
+     *
+     * @return The L2 norm of the Vector2.
+     */
     T norm() const { return std::sqrt(dot(*this)); }
 
   private:
     std::vector<T> data;
 };
 
+/**
+ * Adds the elements of the given Vector2 to the corresponding elements of this Vector2.
+ *
+ * @param lhs The Vector2 to add the elements of the given Vector2 to.
+ * @param rhs The Vector2 to add to the elements of the given Vector2.
+ * @return The resulting Vector2 after the addition.
+ */
 template <typename T> inline Vector2<T> operator+(Vector2<T> lhs, const Vector2<T>& rhs) {
     lhs += rhs;
     return lhs;
 }
 
+/**
+ * Subtracts the elements of the given Vector2 from the corresponding elements of this Vector2.
+ *
+ * @param lhs The Vector2 to subtract the elements of the given Vector2 from.
+ * @param rhs The Vector2 to subtract from the elements of the given Vector2.
+ * @return The resulting Vector2 after the subtraction.
+ */
 template <typename T> inline Vector2<T> operator-(Vector2<T> lhs, const Vector2<T>& rhs) {
     lhs -= rhs;
     return lhs;
 }
 
+/**
+ * Multiplies the elements of the given Vector2 by the given scalar value.
+ *
+ * @param v The Vector2 to multiply by the scalar.
+ * @param scalar The scalar value to multiply the Vector2 by.
+ * @return The resulting Vector2 after the multiplication.
+ */
 template <typename T> inline Vector2<T> operator*(Vector2<T> v, T scalar) {
     v *= scalar;
     return v;
 }
 
+/**
+ * Multiplies the given scalar value by the elements of the given Vector2.
+ *
+ * @param scalar The scalar value to multiply the Vector2 by.
+ * @param v The Vector2 to multiply by the scalar.
+ * @return The resulting Vector2 after the multiplication.
+ */
 template <typename T> inline Vector2<T> operator*(T scalar, Vector2<T> v) { return v * scalar; }
 
 template <typename T> class Matrix2 {
   public:
+    /**
+     * Constructs a new Matrix2 with the specified number of rows and columns, initializing all
+     * elements to the default value of type T.
+     *
+     * @param rows The number of rows in the Matrix2.
+     * @param cols The number of columns in the Matrix2.
+     */
     Matrix2(size_t rows, size_t cols) : data(rows, std::vector<T>(cols, T{})) {}
+
+    /**
+     * Returns a reference to the vector of elements at the specified row index.
+     *
+     * @param i The row index to access.
+     * @return A reference to the vector of elements at the specified row index.
+     */
     std::vector<T>& operator[](size_t i) { return data[i]; }
+
+    /**
+     * Returns a constant reference to the vector of elements at the specified row index.
+     *
+     * @param i The row index to access.
+     * @return A constant reference to the vector of elements at the specified row index.
+     */
     const std::vector<T>& operator[](size_t i) const { return data[i]; }
+
+    /**
+     * Returns the number of rows in the Matrix2.
+     *
+     * @return The number of rows in the Matrix2.
+     */
     size_t rows() const { return data.size(); }
+
+    /**
+     * Returns the number of columns in the Matrix2.
+     *
+     * @return The number of columns in the Matrix2.
+     */
     size_t cols() const { return data[0].size(); }
 
+    /**
+     * Multiplies the given Vector2 by the elements of this Matrix2.
+     *
+     * @param v The Vector2 to multiply by the elements of this Matrix2.
+     * @return The resulting Vector2 after the multiplication.
+     */
     Vector2<T> operator*(const Vector2<T>& v) const {
         Vector2<T> result(rows());
         for (size_t i = 0; i < rows(); ++i) {