Linear algebra documentation partons/core/partons#4.

include/NumA/linear_algebra/eigen/EigenUtils.h

@@ -18,12 +18,30 @@ namespace NumA {
 /**
  * @class EigenUtils
  * @brief Tools for the Eigen wrapper.
+ *
+ * Workaround to not have PARTONS depend on Eigen.
+ * The methods defined here are only used in the cpp files of NumA++. Do not include this file in PARTONS.
  */
 
 class EigenUtils {
 public:
+    /**
+     * Convert a matrix from NumA type to Eigen type.
+     * @param A NumA matrix.
+     * @return Eigen matrix.
+     */
     static Eigen::MatrixXd convertToEigen(const MatrixD & A);
+    /**
+     * Convert a vector from NumA type to Eigen type.
+     * @param V NumA vector.
+     * @return Eigen vector.
+     */
     static Eigen::VectorXd convertToEigen(const VectorD & V);
+    /**
+     * Convert a vector from Eigen type to NumA type.
+     * @param V Eigen vector.
+     * @return NumA vector.
+     */
     static VectorD convertToVectorD(const Eigen::VectorXd & V);
 };
 

include/NumA/linear_algebra/least_squares/LSMRSolver.h

@@ -26,61 +26,84 @@ namespace NumA {
  * @brief LSMR solves Ax = b or min ||Ax - b|| with or without damping,
  * using the iterative algorithm of David Fong and Michael Saunders:
  *     http://www.stanford.edu/group/SOL/software/lsmr.html
+ *
+ * Adapted for C++ from the scipy implementation:
+ * https://github.com/scipy/scipy/blob/v0.18.1/scipy/sparse/linalg/isolve/lsmr.py
  */
 
 class LSMRSolver {
 public:
+    /**
+     * Constructor.
+     * @param damp Damping factor for regularized least-squares.
+     * @param atol Stopping tolerance.
+     * @param btol Stopping tolerance.
+     * @param conlim LSMR terminates if an estimate of `cond(A)` exceeds conlim.
+     * @param maxiter LSMR terminates if the number of iterations reaches maxiter.
+     * @param output Pointer to the stream where to write the output.
+     */
     LSMRSolver(double damp = 0., double atol = 1.e-6, double btol = 1.e-6,
             double conlim = 1.e8, size_t maxiter = 0,
             ElemUtils::Formatter* output = 0);
+    /**
+     * Default destructor.
+     */
     virtual ~LSMRSolver();
 
     /**
      * @brief Solves the linear system \f$ A X = B \f$ and returns \f$ X \f$ in the least-squares sense.
      * Iterative method for large sparse matrices.
-     * @param A MatrixD
-     * @param B VectorD
+     * @param A MatrixD.
+     * @param B VectorD.
      * @return VectorD Solution X.
      */
     VectorD solve(const MatrixD & A, const VectorD & B);
 
     // ##### GETTERS & SETTERS #####
 
-    double getToleranceA() const;
-    void setToleranceA(double atol);
-    double getToleranceB() const;
-    void setToleranceB(double btol);
-    double getConditionNumberLimit() const;
-    void setConditionNumberLimit(double conlim);
-    double getDamping() const;
-    void setDamping(double damp);
-    size_t getMaximumIerations() const;
-    void setMaximumIerations(size_t maxiter);
+    double getToleranceA() const; ///< Stopping tolerance. LSMR continues iterations until a certain backward error estimate is smaller than some quantity depending on atol and btol.
+    void setToleranceA(double atol); ///< Stopping tolerance. LSMR continues iterations until a certain backward error estimate is smaller than some quantity depending on atol and btol.
+    double getToleranceB() const; ///< Stopping tolerance. LSMR continues iterations until a certain backward error estimate is smaller than some quantity depending on atol and btol.
+    void setToleranceB(double btol); ///< Stopping tolerance. LSMR continues iterations until a certain backward error estimate is smaller than some quantity depending on atol and btol.
+    double getConditionNumberLimit() const; ///< LSMR terminates if an estimate of `cond(A)` exceeds conlim.
+    void setConditionNumberLimit(double conlim); ///< LSMR terminates if an estimate of `cond(A)` exceeds conlim.
+    double getDamping() const; ///< Damping factor for regularized least-squares.
+    void setDamping(double damp); ///< Damping factor for regularized least-squares.
+    size_t getMaximumIerations() const; ///< LSMR terminates if the number of iterations reaches maxiter.
+    void setMaximumIerations(size_t maxiter); ///< LSMR terminates if the number of iterations reaches maxiter.
+     /**
+      *
+      * @return Reference to the stream where the output is written.
+      */
     ElemUtils::Formatter& getOutput() const;
+    /**
+     *
+     * @param output Reference to the stream where the output is written.
+     */
     void setOutput(ElemUtils::Formatter& output);
     double getConditionNumber() const;
-    unsigned int getStoppingCase() const;
-    size_t getNumberIterations() const;
+    unsigned int getStoppingCase() const; ///< Reason for stopping the iterations.
+    size_t getNumberIterations() const;  ///< Number of iterations.
     double getNormA() const;
     double getNormAr() const;
     double getNormr() const;
     double getNormX() const;
-    const std::string& getStoppingMessage() const;
+    const std::string& getStoppingMessage() const; ///< Reason for stopping the iterations.
 
 private:
     // ##### Parameters of the solver #####
-    double m_damp;
-    double m_atol;
-    double m_btol;
-    double m_conlim;
-    size_t m_maxiter;
-    ElemUtils::Formatter* m_output;
+    double m_damp; ///< Damping factor for regularized least-squares.
+    double m_atol; ///< Stopping tolerance. LSMR continues iterations until a certain backward error estimate is smaller than some quantity depending on atol and btol.
+    double m_btol; ///< Stopping tolerance. LSMR continues iterations until a certain backward error estimate is smaller than some quantity depending on atol and btol.
+    double m_conlim; ///< LSMR terminates if an estimate of `cond(A)` exceeds conlim.
+    size_t m_maxiter; ///< LSMR terminates if the number of iterations reaches maxiter.
+    ElemUtils::Formatter* m_output; ///< Pointer to the stream where to write the output.
 
     // ##### Results of the solver #####
-    unsigned int m_istop;
-    size_t m_itn;
+    unsigned int m_istop; ///< Reason for stopping the iterations.
+    size_t m_itn; ///< Number of iterations.
     double m_normr, m_normar, m_normA, m_condA, m_normx;
-    std::string m_stopMessage;
+    std::string m_stopMessage; ///< Reason for stopping the iterations.
 
     // Miscellaneous
     std::vector<std::string> m_msg;

include/NumA/linear_algebra/matrix/MatrixD.h

@@ -22,6 +22,28 @@ class VectorD;
  * @class MatrixD
  *
  * @brief Represents a two-dimensional array of double.
+ *
+ * The indices start at 0 up to `size`-1.
+ *
+ * Examples:
+ * ```cpp
+ * NumA::MatrixD A(5,5); // 5x5 matrix with coefficients equal to 0.
+ * A.at(1,3) = 10.; // Defines one coefficient (second row, fourth column).
+ * NumA::MatrixD B = NumA::MatrixD::Id(5); // Identity matrix.
+ * B.at(4,4) = 5.; // Last row, last column.
+ * // Matrix operations:
+ * NumA::MatrixD C;
+ * C = A*B + B/2.;
+ * C.toString();
+ * ```
+ * This returns:
+ * ```
+ * 0.5 0 0 0 0
+ * 0 0.5 0 10 0
+ * 0 0 0.5 0 0
+ * 0 0 0 0.5 0
+ * 0 0 0 0 2.5
+ * ```
  */
 
 class MatrixD {
@@ -33,7 +55,7 @@ public:
     MatrixD();
 
     /**
-     * Create matrix with specific dimension and fill it with given values separate by comma.
+     * Creates a matrix with specific dimensions and fills it with given values separated by comma.
      *
      * TODO: Write something better?
      *
@@ -48,7 +70,7 @@ public:
             double first_value, ...);
 
     /**
-     * Create matrix with specific dimension and fill it with 0.
+     * Creates matrix with specific dimensions and fills it with 0.
      *
      * @param _rowsNumber : number of rows
      * @param _columnsNumber : number of columns
@@ -58,14 +80,14 @@ public:
     /**
      * Copy constructor.
      *
-     * @param rhs
+     * @param rhs Matrix to be copied.
      */
     MatrixD(const MatrixD& rhs);
 
     /**
      * VectorD constructor (creates a one-column matrix).
      *
-     * @param rhs VectorD
+     * @param rhs Vector to be converted to a matrix.
      */
     MatrixD(const VectorD& rhs);
 
@@ -75,62 +97,129 @@ public:
     virtual ~MatrixD();
 
     /**
-     * Assign a new matrix with all coefficients set to value.
-     * @param _rowsNumber
-     * @param _columnsNumber
-     * @param value
+     * Assigns a new matrix with all coefficients set to `value`.
+     * @param _rowsNumber Number of rows.
+     * @param _columnsNumber Number of columns.
+     * @param value Default value for all the coefficients.
      */
     void assign(const size_t _rowsNumber, const size_t _columnsNumber,
             double value = 0.);
 
+    /**
+     * Sets an existing line of the matrix to new values given by a vector.
+     * @param i Index of the line to be modified.
+     * @param line Vector to copy in the matrix.
+     */
     void setLine(size_t i, const NumA::VectorD& line);
+    /**
+     * Adds a new line in the matrix (its dimension is therefore incremented) with the values given by a vector.
+     * @param i Index the row where the line will be inserted.
+     * @param line Vector to copy in the matrix.
+     */
     void addLine(size_t i, const NumA::VectorD& line);
+    /**
+     * Adds a new line at the end of the matrix (its dimension is therefore incremented) with the values given by a vector.
+     * @param line Vector to copy in the matrix.
+     */
     void appendLine(const NumA::VectorD& line);
+    /**
+     * Extracts a single line from the matrix.
+     * @param lineIndex Index of the row to be extracted.
+     * @return Vector corresponding to the row.
+     */
     NumA::VectorD getLine(const size_t lineIndex) const;
 
     // Matrix/vector operations
     /**
      * Matrix vector multiplication.
-     * @param rhs
-     * @return Matrix . rhs
+     * @param rhs Vector.
+     * @return Vector \f$ M \cdot V \f$.
      */
     NumA::VectorD operator*(const NumA::VectorD& rhs) const;
     //std::vector<double> operator*=(const std::vector<double>& rhs);
 
     // Matrix/matrix operations
+    /**
+     * Matrix-matrix multiplication.
+     * @param rhs Matrix.
+     * @return Product of matrices.
+     */
     NumA::MatrixD operator*(const NumA::MatrixD& rhs) const;
+    /**
+     * Matrix addition.
+     * @param rhs Matrix.
+     * @return Sum of matrices.
+     */
     NumA::MatrixD operator+(const NumA::MatrixD& rhs) const;
+    /**
+     * Matrix subtraction.
+     * @param rhs Matrix.
+     * @return Difference of matrices.
+     */
     NumA::MatrixD operator-(const NumA::MatrixD& rhs) const;
 
     // Matrix/double operations
+    /**
+     * Multiplication of all the coefficients by a scalar.
+     * @param rhs Scalar.
+     * @return Matrix.
+     */
     NumA::MatrixD operator*(double rhs) const;
+    /**
+     * Addition coefficient by coefficient with a scalar.
+     * @param rhs Scalar.
+     * @return Matrix.
+     */
     NumA::MatrixD operator+(double rhs) const;
+    /**
+     * Subtraction coefficient by coefficient with a scalar.
+     * @param rhs Scalar.
+     * @return Matrix.
+     */
     NumA::MatrixD operator-(double rhs) const;
+    /**
+     * Division of all the coefficients by a scalar.
+     * @param rhs Scalar.
+     * @return Matrix.
+     */
     NumA::MatrixD operator/(double rhs) const;
 
     /**
      * Matrix transpose.
-     * @return MatrixD transposed
+     * @return Matrix transposed.
      */
     NumA::MatrixD transpose() const;
 
     /**
      * Matrix identity.
      * @param n Dimension.
-     * @return MatrixD id
+     * @return Matrix identity.
      */
     static NumA::MatrixD Id(unsigned int n);
 
     /**
-     * Update the value at the given coordinates.
+     * Update the value at the given indices.
      *
-     * @param i : row coordinate
-     * @param j : column coordinate
-     * @param value
+     * @param i Row index.
+     * @param j Column index.
+     * @param value New value for the coefficient.
      */
     void update(const size_t i, const size_t j, const double value);
 
+    /**
+     * Element access.
+     * Can be used to set the value of a coefficient.
+     * @param i Row index.
+     * @param j Column index.
+     * @return Reference to a certain coefficient of the matrix.
+     */
     double & at(const size_t i, const size_t j);
+    /**
+     * Element access.
+     * @param i Row index.
+     * @param j Column index.
+     * @return Constant reference to a certain coefficient of the matrix.
+     */
     const double & at(const size_t i, const size_t j) const;
 
     /**
@@ -143,19 +232,19 @@ public:
     // ##### GETTERS & SETTERS #####
     /**
      *
-     * @return Number of columns
+     * @return Number of columns.
      */
     size_t cols() const;
     /**
      *
-     * @return Number of rows
+     * @return Number of rows.
      */
     size_t rows() const;
 
 private:
-    std::vector<double> m_matrix; ///< a flat std::vector to represent the matrix
-    size_t m_rowsNumber;    ///< number of rows
-    size_t m_columnsNumber;    ///< number of columns
+    std::vector<double> m_matrix; ///< A flat std::vector to represent the matrix.
+    size_t m_rowsNumber;    ///< Number of rows.
+    size_t m_columnsNumber;    ///< Number of columns.
 };
 
 } /* namespace NumA */

include/NumA/linear_algebra/vector/Vector2D.h

@@ -14,29 +14,76 @@ namespace NumA {
 
 /**
  * @class Vector2D
+ *
+ * Object representing a two-dimensional vector.
  */
 class Vector2D {
 public:
+    /**
+     * Default constructor.
+     */
     Vector2D();
+    /**
+     * Constructor.
+     * @param x x-coordinate.
+     * @param y y-coordinate.
+     */
     Vector2D(double x, double y);
+    /**
+     * Default destructor.
+     */
     ~Vector2D();
 
     // ##### GETTERS & SETTERS #####
 
+    /**
+     *
+     * @return x-coordinate.
+     */
     double getX() const;
+    /**
+     *
+     * @param x x-coordinate.
+     */
     void setX(double x);
+    /**
+     *
+     * @return y-coordinate.
+     */
     double getY() const;
+    /**
+     *
+     * @param y y-coordinate.
+     */
     void setY(double y);
 
+    /**
+     * Addition of two vectors.
+     * @param rhs Vector2D.
+     * @return Sum of two Vector2D.
+     */
     Vector2D operator+(Vector2D const &rhs);
+    /**
+     * Addition with a scalar.
+     * @param rhs Scalar.
+     */
     void operator+=(Vector2D const &rhs);
 
+    /**
+     * Subtraction of two vectors
+     * @param rhs Vector2D.
+     * @return Subtraction of two Vector2D.
+     */
     Vector2D operator-(Vector2D const &rhs);
+    /**
+     * Subtraction with a scalar.
+     * @param rhs Scalar.
+     */
     void operator-=(Vector2D const &rhs);
 
 private:
-    double m_x;
-    double m_y;
+    double m_x; ///< x-coordinate.
+    double m_y; ///< y-coordinate.
 };
 
 } /* namespace NumA */

include/NumA/linear_algebra/vector/Vector3D.h

@@ -18,25 +18,57 @@ namespace NumA {
 
 /**
  * @class Vector3D
+ *
+ * Object representing a three-dimensional vector.
  */
 class Vector3D: public Vector2D {
 public:
+    /**
+     * Default constructor.
+     */
     Vector3D();
+    /**
+     * Constructor.
+     * @param x x-coordinate.
+     * @param y y-coordinate.
+     * @param z z-coordinate.
+     */
     Vector3D(double x, double y, double z);
+    /**
+     * Default destructor.
+     */
     ~Vector3D();
 
     // Scalar operation
+    /**
+     * Scalar product.
+     * @param rhs Vector3D.
+     * @return double
+     */
     double operator*(const Vector3D &rhs) const;
 
     // ##### GETTERS & SETTERS #####
 
+    /**
+     *
+     * @return z-coordinate.
+     */
     double getZ() const;
+    /**
+     *
+     * @param z z-coordinate.
+     */
     void setZ(double z);
 
+    /**
+     * Return a formatted characters string to display vector's values.
+     *
+     * @return std::string
+     */
     std::string toString();
 
 private:
-    double m_z;
+    double m_z; ///< z-coordinate.
 };
 
 } /* namespace NumA */

include/NumA/linear_algebra/vector/Vector4D.h

@@ -14,23 +14,37 @@
 
 namespace NumA {
 
-
 /**
  * @class Vector4D
+ *
+ * Object representing a four-vector.
  */
 class Vector4D: public Vector3D {
 public:
+    /**
+     * Default constructor.
+     */
     Vector4D();
+    /**
+     * Constructor.
+     * @param x x-coordinate.
+     * @param y y-coordinate.
+     * @param z z-coordinate.
+     * @param e Energy/Time component.
+     */
     Vector4D(double x, double y, double z, double e);
+    /**
+     * Default destructor.
+     */
     ~Vector4D();
 
     // ##### GETTERS & SETTERS #####
 
-    double getE() const;
-    void setE(double e);
+    double getE() const; ///< Energy/Time component.
+    void setE(double e); ///< Energy/Time component.
 
 private:
-    double m_e;
+    double m_e; ///< Energy/Time component.
 };
 
 } /* namespace NumA */

include/NumA/linear_algebra/vector/VectorD.h

@@ -38,15 +38,15 @@ public:
     VectorD();
 
     /**
-     * Construct a vector of size size initialized at 0.
-     * @param size : the length of the vector
+     * Construct a vector of given size initialized at 0.
+     * @param size Size of the vector.
      */
     VectorD(size_t size);
 
     /**
-     * Construct a vector of size size initialized at initValue.
-     * @param size : the length of the vector
-     * @param initValue : value used to initialize the vector
+     * Construct a vector of given size initialized at initValue.
+     * @param size Size of the vector.
+     * @param initValue Default value for the coefficients.
      */
     VectorD(size_t size, double initValue);
 
@@ -81,21 +81,21 @@ public:
     VectorD(const Vector4D &vector);
 
     /**
-     * Default destructor
+     * Default destructor.
      */
     virtual ~VectorD();
 
-    void push_back(double value);
-    void resize(size_t n, double value = 0.);
-    void assign(size_t n, double value = 0.);
+    void push_back(double value); ///< Same as std::vector.
+    void resize(size_t n, double value = 0.); ///< Same as std::vector.
+    void assign(size_t n, double value = 0.); ///< Same as std::vector.
 
     /**
-     * @return size_t : the length of the current vector.
+     * @return size_t Size of the vector.
      */
     size_t size() const;
 
     /**
-     * Return a subset of the vector. [startPos:endPos[
+     * Returns a subset of the vector: [startPos:endPos[
      * @param startPos
      * @param endPos
      * @return VectorD
@@ -103,29 +103,49 @@ public:
     VectorD sub(size_t startPos, size_t endPos) const;
 
     /**
-     * Scalar product
-     * @param rhs VectorD of same size
+     * Scalar product.
+     * @param rhs VectorD of same size.
      * @return double
      */
     double operator *(const VectorD &rhs) const;
 
     /**
      * Subtraction.
-     * @param rhs VectorD of same size
-     * @return VectorD of same size
+     * @param rhs VectorD of same size.
+     * @return VectorD of same size.
      */
     VectorD operator -(const VectorD &rhs) const;