grid: Add Doxygen boxes and some touch ups

src/grid/grid_collocate_cpu.c

@@ -16,7 +16,12 @@
 #include "grid_common.h"
 
 
-// *****************************************************************************
+//******************************************************************************
+// \brief Computes the polynomial expansion coefficients:
+//        (x-a)**lxa (x-b)**lxb -> sum_{ls} alpha(ls,lxa,lxb,1)*(x-p)**ls
+//        Results are passed to grid_prepare_coef.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_prepare_alpha(const double ra[3],
                                const double rb[3],
                                const double rp[3],
@@ -35,10 +40,6 @@ static void grid_prepare_alpha(const double ra[3],
     }
     }
 
-    //
-    //   compute polynomial expansion coefs -> (x-a)**lxa (x-b)**lxb -> sum_{ls} alpha(ls,lxa,lxb,1)*(x-p)**ls
-    //
-
     for (int iaxis=0; iaxis<3; iaxis++) {
        const double drpa = rp[iaxis] - ra[iaxis];
        const double drpb = rp[iaxis] - rb[iaxis];
@@ -62,7 +63,12 @@ static void grid_prepare_alpha(const double ra[3],
     }
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Compute coefficients for all combinations of angular momentum.
+//        Results are passed to grid_collocate_ortho and grid_collocate_general.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_prepare_coef(const int la_max,
                       const int la_min,
                       const int lb_max,
@@ -119,7 +125,12 @@ static void grid_prepare_coef(const int la_max,
     }
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Computes mapping from cube to grid indices.
+//        Used only in the orthorhombic case.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_fill_map(const int lb_cube,
                           const int ub_cube,
                           const int cubecenter,
@@ -138,22 +149,24 @@ static void grid_fill_map(const int lb_cube,
 }
 
 
-// *****************************************************************************
+//******************************************************************************
+// \brief Computes (x-xp)**lp*exp(..) for all cube points in one dimension.
+//        Used only in the orthorhombic case.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_fill_pol(const double dr,
                           const double roffset,
                           const int lb_cube,
                           const int lp,
                           const int cmax,
                           const double zetp,
                           double pol[lp+1][2*cmax+1]) {
-//
-//   compute the values of all (x-xp)**lp*exp(..)
-//
+
 //  still requires the old trick:
 //  new trick to avoid to many exps (reuse the result from the previous gridpoint):
 //  exp( -a*(x+d)**2)=exp(-a*x**2)*exp(-2*a*x*d)*exp(-a*d**2)
 //  exp(-2*a*(x+d)*d)=exp(-2*a*x*d)*exp(-2*a*d**2)
-//
+
       const double t_exp_1 = exp(-zetp * pow(dr, 2));
       const double t_exp_2 = pow(t_exp_1, 2);
 
@@ -186,7 +199,11 @@ static void grid_fill_pol(const double dr,
       }
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief  A much simpler but also slower implementation of grid_collocate_core.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_collocate_core_simple(const int lp,
                                        const int cmax,
                                        const double coef_xyz[lp+1][lp+1][lp+1],
@@ -268,7 +285,13 @@ static void grid_collocate_core_simple(const int lp,
     free(cube);
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Fills the 3D cube by taking the outer product of the 1D pol arrays.
+//        The majority of cpu cycles are spend in this routine.
+//        Used only in the orthorhombic case.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_collocate_core(const int lp,
                                 const int cmax,
                                 const double coef_xyz[lp+1][lp+1][lp+1],
@@ -378,7 +401,11 @@ static void grid_collocate_core(const int lp,
     }
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Collocate kernel for the orthorhombic case.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_collocate_ortho(const int lp,
                                  const double zetp,
                                  const double coef_xyz[lp+1][lp+1][lp+1],
@@ -484,7 +511,10 @@ static void grid_collocate_ortho(const int lp,
 }
 
 
-// *****************************************************************************
+//******************************************************************************
+// \brief Collocate kernel for the general case, ie. non-ortho or with subpatches.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_collocate_general(const bool use_subpatch,
                                    const int subpatch,
                                    const int border,
@@ -747,7 +777,12 @@ static void grid_collocate_general(const bool use_subpatch,
     }
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Internal entry point. Runs common preparations before branching into
+//        the orthorhombic or general kernel.
+// \author Ole Schuett
+//******************************************************************************
 static void grid_collocate_internal(const bool orthorhombic,
                                     const bool use_subpatch,
                                     const int subpatch,
@@ -883,7 +918,11 @@ static void grid_collocate_internal(const bool orthorhombic,
 }
 
 
-// *****************************************************************************
+//******************************************************************************
+// \brief Public entry point. A thin wrapper with the only purpose of calling
+//        grid_collocate_record when DUMP_TASKS = true.
+// \author Ole Schuett
+//******************************************************************************
 void grid_collocate_pgf_product_cpu(const bool orthorhombic,
                                     const bool use_subpatch,
                                     const int subpatch,

src/grid/grid_collocate_miniapp.c

@@ -9,6 +9,10 @@
 
 #include "grid_collocate_replay.h"
 
+//******************************************************************************
+// \brief Stand-alone miniapp for running .task files.
+// \author Ole Schuett
+//******************************************************************************
 int main(int argc, char *argv[]){
     // Parsing of optional args.
     int iarg = 1;

src/grid/grid_collocate_replay.c

@@ -21,7 +21,12 @@
 #include "grid_task_list.h"
 #include "grid_common.h"
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Writes the given arguments into a .task file.
+//        See grid_collocate_replay.h for details.
+// \author Ole Schuett
+//******************************************************************************
 void grid_collocate_record(const bool orthorhombic,
                            const bool use_subpatch,
                            const int subpatch,
@@ -49,10 +54,14 @@ void grid_collocate_record(const bool orthorhombic,
                            const double pab[n2][n1],
                            const double* grid){
 
-    static int counter = 0;
-    counter++;
+    static int counter = 1;
+    int my_number;
+
+    #pragma omp critical
+    my_number = counter++;
+
     char filename[100];
-    snprintf(filename, sizeof(filename), "grid_collocate_%05i.task", counter);
+    snprintf(filename, sizeof(filename), "grid_collocate_%05i.task", my_number);
 
     const int D = DECIMAL_DIG;  // In C11 we could use DBL_DECIMAL_DIG.
     FILE *fp = fopen(filename, "w+");
@@ -116,15 +125,23 @@ void grid_collocate_record(const bool orthorhombic,
 
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Reads next line from given filehandle and handles errors.
+// \author Ole Schuett
+//******************************************************************************
 static void read_next_line(char line[], int length, FILE *fp) {
     if (fgets(line, length, fp) == NULL) {
         fprintf(stderr, "Error: Could not read line.\n");
         abort();
     }
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Parses next line from file, expecting it to match "${key} ${format}".
+// \author Ole Schuett
+//******************************************************************************
 static void parse_next_line(const char key[], FILE *fp, const char format[],
                             const int nargs, ...) {
     char line[100];
@@ -146,30 +163,50 @@ static void parse_next_line(const char key[], FILE *fp, const char format[],
     va_end(varargs);
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Shorthand for parsing a single integer value.
+// \author Ole Schuett
+//******************************************************************************
 static int parse_int(const char key[], FILE *fp) {
     int value;
     parse_next_line(key, fp, "%i", 1, &value);
     return value;
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Shorthand for parsing a vector of three integer values.
+// \author Ole Schuett
+//******************************************************************************
 static void parse_int3(const char key[], FILE *fp, int vec[3]) {
     parse_next_line(key, fp, "%i %i %i", 3, &vec[0], &vec[1], &vec[2]);
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Shorthand for parsing a single double value.
+// \author Ole Schuett
+//******************************************************************************
 static double parse_double(const char key[], FILE *fp) {
     double value;
     parse_next_line(key, fp, "%le", 1, &value);
     return value;
 }
 
+
+//******************************************************************************
+// \brief Shorthand for parsing a vector of three double values.
+// \author Ole Schuett
 // *****************************************************************************
 static void parse_double3(const char key[], FILE *fp, double vec[3]) {
     parse_next_line(key, fp, "%le %le %le", 3, &vec[0], &vec[1], &vec[2]);
 }
 
+
+//******************************************************************************
+// \brief Shorthand for parsing a 3x3 matrix of doubles.
+// \author Ole Schuett
 // *****************************************************************************
 static void parse_double3x3(const char key[], FILE *fp, double mat[3][3]) {
     char format[100];
@@ -179,6 +216,10 @@ static void parse_double3x3(const char key[], FILE *fp, double mat[3][3]) {
     }
 }
 
+
+//******************************************************************************
+// \brief Creates mock basis set using the identity as decontraction matrix.
+// \author Ole Schuett
 // *****************************************************************************
 static void create_dummy_basis_set(const int size,
                                    const int lmin,
@@ -217,6 +258,10 @@ static void create_dummy_basis_set(const int size,
                           basis_set);
 }
 
+
+//******************************************************************************
+// \brief Creates mock task list with one task per cycle.
+// \author Ole Schuett
 // *****************************************************************************
 static void create_dummy_task_list(const bool use_subpatch,
                                    const int subpatch,
@@ -291,7 +336,12 @@ static void create_dummy_task_list(const bool use_subpatch,
     }
 }
 
-// *****************************************************************************
+
+//******************************************************************************
+// \brief Reads a .task file, collocates it, and compares results to reference.
+//        See grid_collocate_replay.h for details.
+// \author Ole Schuett
+//******************************************************************************
 double grid_collocate_replay(const char* filename, const int cycles, const bool batch){
     FILE *fp = fopen(filename, "r");
     if (fp == NULL) {

src/grid/grid_collocate_replay.h

@@ -8,6 +8,11 @@
 
 #include <stdbool.h>
 
+
+//******************************************************************************
+// \brief Writes the given arguments into a .task file.
+// \author Ole Schuett
+//******************************************************************************
 void grid_collocate_record(const bool orthorhombic,
                            const bool use_subpatch,
                            const int subpatch,
@@ -35,6 +40,18 @@ void grid_collocate_record(const bool orthorhombic,
                            const double pab[n2][n1],
                            const double* grid);
 
+
+//******************************************************************************
+// \brief Reads a .task file, collocates it, and compares results to reference.
+//
+// \param filename      Name of the task file.
+// \param cycles        Number of times the task should be collocated.
+// \param batch         When false grid_collocate_pgf_product_cpu is called.
+//                      When true grid_collocate_task_list is called.
+// \returns             The maximum difference for an individual grid point.
+//
+// \author Ole Schuett
+//******************************************************************************
 double grid_collocate_replay(const char* filename, int cycles, bool batch);
 
 #endif

src/grid/grid_collocate_unittest.c

@@ -9,6 +9,11 @@
 
 #include "grid_collocate_replay.h"
 
+
+//******************************************************************************
+// \brief Unit test for the grid collocate code.
+// \author Ole Schuett
+//******************************************************************************
 static int run_test(const char cp2k_root_dir[], const char task_file[]) {
     if (strlen(cp2k_root_dir) > 512) {
         fprintf(stderr, "Error: cp2k_root_dir too long.\n");