Add documentation for functions

HPCCG.cpp

@@ -39,25 +39,6 @@
 // 
 // ************************************************************************
 //@HEADER
-/////////////////////////////////////////////////////////////////////////
-
-// Routine to compute an approximate solution to Ax = b where:
-
-// A - known matrix stored as an HPC_Sparse_Matrix struct
-
-// b - known right hand side vector
-
-// x - On entry is initial guess, on exit new approximate solution
-
-// max_iter - Maximum number of iterations to perform, even if
-//            tolerance is not met.
-
-// tolerance - Stop and assert convergence if norm of residual is <=
-//             to tolerance.
-
-// niters - On output, the number of iterations actually performed.
-
-/////////////////////////////////////////////////////////////////////////
 
 #include <iostream>
 using std::cout;
@@ -69,6 +50,24 @@ using std::endl;
 
 #define TICK()  t0 = mytimer() // Use TICK and TOCK to time a code section
 #define TOCK(t) t += mytimer() - t0
+
+/**
+ * A method to computer the approximate solution to `Ax = b`
+ *
+ * @param A The input sparse matrix.
+ * @param b The known right hand side vector.
+ * @param x The current approximate solution, which starts as the initial guess.
+ * @param max_iter The maximum number of iterations to perform.
+ * @param tolerance The value the residual needs to be less than for convergence
+ *                  (how "good" of a solution do we need).
+ * @param niters The mutable number of iterations performed before convergence
+ *               or the iteration limit is reached.
+ * @param normr The mutable residual between the current approximate solution
+ *              and the exact solution.
+ * @param times A mutable array which tracks the time spent for each operation
+ *              (ddot/waxpby/sparse_mv/total/[MPI reductions]/[MPI setup]).
+ * @return An exit code of zero on success.
+ */
 int HPCCG(HPC_Sparse_Matrix * A,
 	  const double * const b, double * const x,
 	  const int max_iter, const double tolerance, int &niters, double & normr,

HPC_Sparse_Matrix.cpp

@@ -39,14 +39,18 @@
 // 
 // ************************************************************************
 //@HEADER
+
 #include "HPC_Sparse_Matrix.hpp"
 
 #ifdef USING_MPI
 #include <mpi.h>
 #endif
 
-////////////////////////////////////////////////////////////////////////////////
-////////////////////////////////////////////////////////////////////////////////
+/**
+ * A method to clean up the memory of the sparse matrix.
+ *
+ * @param A A pointer to the sparse matrix to clean up.
+ */
 void destroyMatrix(HPC_Sparse_Matrix * &A)
 {
   if(A->title)
@@ -196,4 +200,3 @@ void destroySharedMemMatrix(HPC_Sparse_Matrix * &A)
 #endif
 #endif
 ////////////////////////////////////////////////////////////////////////////////
-

HPC_Sparse_Matrix.hpp

@@ -50,37 +50,40 @@ const int max_external = 100000;
 const int max_num_messages = 500;
 const int max_num_neighbors = max_num_messages;
 
-
+/**
+ * A structure representing a sparse matrix stored in compressed-sparse column
+ * (CSC) form.
+ */
 struct HPC_Sparse_Matrix_STRUCT {
-  char   *title;
-  int start_row;
-  int stop_row;
-  int total_nrow;
-  long long total_nnz;
-  int local_nrow;
-  int local_ncol;  // Must be defined in make_local_matrix
-  int local_nnz;
-  int  * nnz_in_row;
-  double ** ptr_to_vals_in_row;
-  int ** ptr_to_inds_in_row;
-  double ** ptr_to_diags;
+  char *title;  /**< The title of the sparse matrix. */
+  int start_row;  /**< The start row within the entire matrix (always `0` in serial mode). */
+  int stop_row;  /**< The start row within the entire matrix (always `total_nrow-1` in serial mode). */
+  int total_nrow; /**< The number of rows of the entire matrix. */
+  long long total_nnz;  /**< The number of non-zeroes in the entire matrix. */
+  int local_nrow;  /**< The number of rows in the local slice of the matrix (always `total_nrow` in serial mode). */
+  int local_ncol; /**< Must be defined in make_local_matrix (unused and defaults to `local_nrow` in serial mode). */
+  int local_nnz;  /**< The number of non-zeroes in the local slice of the matrix (always `total_nnz` in serial mode). */
+  int *nnz_in_row;  /**< An array of length `local_nrow` containing the number of non-zeroes in each row. */
+  double **ptr_to_vals_in_row;  /**< An array of pointers to the starts of slices in `list_of_vals` for each row. */
+  int **ptr_to_inds_in_row;  /**< An array of pointers to the starts of slices in `list_of_inds` for each row. */
+  double **ptr_to_diags;    /**< An array of pointers to the starts of slices in `list_of_vals`. */
 
 #ifdef USING_MPI
-  int num_external;
-  int num_send_neighbors;
-  int *external_index;
-  int *external_local_index;
-  int total_to_be_sent;
-  int *elements_to_send;
-  int *neighbors;
-  int *recv_length;
-  int *send_length;
-  double *send_buffer;
+  int num_external;  /**< The number of neighbouring. */
+  int num_send_neighbors;  /**< The number of neighbouring MPI ranks to send data to. */
+  int *external_index;  /**< A list of external local indices. */
+  int *external_local_index;  /**< A list of external local indices. */
+  int total_to_be_sent;  /**< The total data to be sent to other MPI ranks. */
+  int *elements_to_send;  /**< A list of data elements to send to other MPI ranks. */
+  int *neighbors;  /**< A list of adjacent rank numbers. */
+  int *recv_length;   /**< A list of number of elements to receive from each neighbouring rank. */
+  int *send_length;  /**< A list of number of elements to send to each neighbouring rank. */
+  double *send_buffer;  /**< A buffer containing the data to send to other MPI ranks. */
 #endif
 
-  double *list_of_vals;   //needed for cleaning up memory
-  int *list_of_inds;      //needed for cleaning up memory
-
+  // needed for cleaning up memory
+  double *list_of_vals;  /**< An array of non-zero values in the sparse matrix. */
+  int *list_of_inds;  /**< An array of the indices in rows of non-zero values in the sparse matrix.*/
 };
 typedef struct HPC_Sparse_Matrix_STRUCT HPC_Sparse_Matrix;
 
@@ -94,4 +97,3 @@ void destroySharedMemMatrix(HPC_Sparse_Matrix * &A);
 #endif
 
 #endif
-

HPC_sparsemv.cpp

@@ -40,17 +40,6 @@
 // ************************************************************************
 //@HEADER
 
-/////////////////////////////////////////////////////////////////////////
-
-// Routine to compute matrix vector product y = Ax where:
-// First call exchange_externals to get off-processor values of x
-
-// A - known matrix 
-// x - known vector
-// y - On exit contains Ax.
-
-/////////////////////////////////////////////////////////////////////////
-
 #include <iostream>
 using std::cout;
 using std::cerr;
@@ -63,6 +52,30 @@ using std::endl;
 #include <cmath>
 #include "HPC_sparsemv.hpp"
 
+/**
+ * A method to compute the matrix-vector product `y = Ax`.
+ *
+ * @note In MPI, first call exchange_externals to get off-processor values of x.
+ *
+ * The input matrix to the function is stored in compressed-sparse column form.
+ * Hence, `cur_vals` is a pointer to a slice of the `list_of_vals` array, which
+ * then contains an ordered array of the non-zero values in the current row.
+ * `cur_inds` equivalently is an ordered array of the indices of those values in
+ * the current row. `cur_nnz` is the number of non-zeroes in the array (hence
+ * the length of both `cur_vals` and `cur_inds` array slices, as the
+ * `list_of_vals/inds` arrays are non-homogenous in sub-array length, and don't
+ * have termination to split the sub-arrays up).
+ *
+ * Hence, the matrix-vector multiplication is an array containing the products
+ * of those non-zero values with their pairs in the input vector, for each rown
+ * in the input matrix and vector.
+ *
+ * @param A The input sparse matrix.
+ * @param x The input vector.
+ * @param y A pointer to a vector, which is updated to contain the calculated
+ *          product `Ax`.
+ * @return An exit code of zero on success.
+ */
 int HPC_sparsemv( HPC_Sparse_Matrix *A, 
 		 const double * const x, double * const y)
 {

YAML_Doc.cpp

@@ -13,22 +13,32 @@
 #include "YAML_Doc.hpp"
 using namespace std;
 
-//set the microapp_name and version which will become part of the YAML doc.
+/**
+ * Set the mini-app name and version which will become part of the YAML doc.
+ *
+ * @param miniApp_Name The name of the mini-app.
+ * @param miniApp_Version The version of the mini-app.
+ * @param destination_Directory The output directory for the YAML file.
+ * @param destination_FileName The output filename for the YAML file.
+ */
 YAML_Doc::YAML_Doc(const std::string& miniApp_Name, const std::string& miniApp_Version, const std::string& destination_Directory, const std::string& destination_FileName){
   miniAppName = miniApp_Name;
   miniAppVersion = miniApp_Version;
   destinationDirectory = destination_Directory;
   destinationFileName = destination_FileName;
 }
 
-//inherits the destructor from YAML_Element
+/**
+ * Inherits the destructor from YAML_Element.
+ */
 YAML_Doc::~YAML_Doc(void){
 }
 
-/*
-* generates YAML from the elements of the document and saves it
-* to a file
-*/
+/**
+ * Generate YAML from the elements of the document and save it to a file.
+ *
+ * @return A string containing the YAML data written to the file.
+ */
 string YAML_Doc::generateYAML(){
   string yaml;
   yaml =  yaml + "Mini-Application Name: " + miniAppName + "\n";
@@ -70,5 +80,3 @@ string YAML_Doc::generateYAML(){
   myfile.close();
   return yaml;
 }
-
-