documentation improvements

libsharp/libsharp.dox

@@ -7,10 +7,9 @@
 
 /*! \page introduction Introduction to libsharp
 
-  "SHARP" is an acronym for <i>Performant Spherical Harmonic Transforms</i>.
+  "SHARP" is an acronym for <i>Spherical HARmonic Package</i>.
   All user-visible data types and functions in this library start with
-  the prefix "sharp_", or with "sharps_" and "sharpd_" for single- and
+  the prefix "sharp_" to avoid pollution of the global C namespace.
-  double precision variants, respectively.
 
   <i>libsharp</i>'s main functionality is the conversion between <i>maps</i>
   on the sphere and <i>spherical harmonic coefficients</i> (or <i>a_lm</i>).
@@ -57,7 +56,7 @@
   for generating often-used pixelisations like ECP grids, Gaussian grids,
   and Healpix grids.
 
-  Currently, SHARP supports the following kinds of transforms:
+  Currently, libsharp supports the following kinds of transforms:
   <ul>
   <li>scalar a_lm to map</li>
   <li>scalar map to a_lm</li>
@@ -68,10 +67,10 @@
   <li>scalar a_lm to maps of first derivatives</li>
   </ul>
 
-  SHARP supports shared-memory parallelisation via OpenMP; this feature will
+  libsharp supports shared-memory parallelisation via OpenMP; this feature will
   be automatically enabled if the compiler supports it.
 
-  SHARP will also make use of SSE2 and AVX instructions when compiled for a
+  Libsharp will also make use of SSE2 and AVX instructions when compiled for a
   platform known to support them.
 
   Support for MPI-parallel transforms is also available; in this mode,
@@ -84,7 +83,7 @@
   double-precision counterparts, but they will require significantly less
   memory.
 
-  Two example and benchmark programs are distributed with SHARP:
+  Two example and benchmark programs are distributed with libsharp:
   <ul>
   <li>sharp_test.c checks the accuracy of the (iterative) map analysis
       algorithm</li>

libsharp/sharp_geomhelpers.c

@@ -25,7 +25,7 @@
 /*! \file sharp_geomhelpers.c
  *  Spherical transform library
  *
- *  Copyright (C) 2006-2012 Max-Planck-Society
+ *  Copyright (C) 2006-2012 Max-Planck-Society<br>
  *  Copyright (C) 2007-2008 Pavel Holoborodko (for gauss_legendre_tbl)
  *  \author Martin Reinecke \author Pavel Holoborodko
  */

libsharp/sharp_lowlevel.h

@@ -83,20 +83,22 @@ typedef struct
   ptrdiff_t stride;
   } sharp_alm_info;
 
-/*! Creates an Alm data structure information from the following parameters:
+/*! Creates an a_lm data structure from the following parameters:
     \param lmax maximum \a l quantum number (>=0)
     \param mmax maximum \a m quantum number (0<= \a mmax <= \a lmax)
-    \param stride the stride between consecutive a_lm entries
+    \param stride the stride between entries with identical \a m, and \a l
+      differing by 1.
     \param mstart the index of the (hypothetical) coefficient with the
       quantum numbers 0,\a m. Must have \a mmax+1 entries.
     \param alm_info will hold a pointer to the newly created data structure
  */
 void sharp_make_alm_info (int lmax, int mmax, int stride,
   const ptrdiff_t *mstart, sharp_alm_info **alm_info);
-/*! Creates an Alm data structure information from the following parameters:
+/*! Creates an a_lm data structure which from the following parameters:
-    \param lmax maximum \a l quantum number (>=0)
+    \param lmax maximum \a l quantum number (\a >=0)
-    \param nm number of different \a m (<=\a lmax+1)
+    \param nm number of different \a m (\a 0<=nm<=lmax+1)
-    \param stride the stride between consecutive a_lm entries
+    \param stride the stride between entries with identical \a m, and \a l
+      differing by 1.
     \param mval array with \a nm entries containing the individual m values
     \param mvstart array with \a nm entries containing the (hypothetical)
       indices of the coefficients with the quantum numbers 0,\a mval[i]
@@ -105,7 +107,9 @@ void sharp_make_alm_info (int lmax, int mmax, int stride,
 void sharp_make_general_alm_info (int lmax, int nm, int stride, const int *mval,
   const ptrdiff_t *mvstart, sharp_alm_info **alm_info);
 /*! Returns the index of the coefficient with quantum numbers \a l,
-    \a mval[mi]. */
+    \a mval[mi].
+    \note for a \a sharp_alm_info generated by sharp_make_alm_info() this is
+    the index for the coefficient with the quantum numbers \a l, \a mi. */
 ptrdiff_t sharp_alm_index (const sharp_alm_info *self, int l, int mi);
 /*! Deallocates the a_lm info object. */
 void sharp_destroy_alm_info (sharp_alm_info *info);
@@ -148,8 +152,9 @@ typedef enum { SHARP_MAP2ALM,       /*!< analysis */
              } sharp_jobtype;
 
 /*! Job flags */
-typedef enum { SHARP_DP = 1<<4, /*!< map and alm is in double precision */
+typedef enum { SHARP_DP = 1<<4, /*!< map and a_lm are in double precision */
-               SHARP_ADD= 1<<5, /*!< results are added to the output data */
+               SHARP_ADD= 1<<5, /*!< results are added to the output arrays,
+                                     instead of overwriting them */
                SHARP_NVMAX = (1<<4)-1 /* internal use only */
              } sharp_jobflags;
 
@@ -161,12 +166,13 @@ typedef enum { SHARP_DP = 1<<4, /*!< map and alm is in double precision */
     alm[0] points to the a_lm of the first SHT, alm[1] to those of the second
     etc. If \a spin>0, alm[0] and alm[1] point to the a_lm of the first SHT,
     alm[2] and alm[3] to those of the second, etc. The exact data type of \a alm
-    depends on the \a dp parameter.
+    depends on whether the SHARP_DP flag is set.
   \param map contains pointers to the maps. If \a spin==0,
     map[0] points to the map of the first SHT, map[1] to that of the second
-    etc. If \a spin>0, map[0] and map[1] point to the maps of the first SHT,
+    etc. If \a spin>0, or \a type is SHARP_ALM2MAP_DERIV1, map[0] and map[1]
-    map[2] and map[3] to those of the second, etc. The exact data type of \a map
+    point to the maps of the first SHT, map[2] and map[3] to those of the
-    depends on the \a dp parameter.
+    second, etc. The exact data type of \a map depends on whether the SHARP_DP
+    flag is set.
   \param geom_info A \c sharp_geom_info object compatible with the provided
     \a map arrays.
   \param alm_info A \c sharp_alm_info object compatible with the provided
@@ -178,7 +184,7 @@ typedef enum { SHARP_DP = 1<<4, /*!< map and alm is in double precision */
     expected to have the type "double **"; otherwise, the expected
     types are "complex float **" and "float **", respectively.
   \param time If not NULL, the wall clock time required for this SHT
-    (in seconds)will be written here.
+    (in seconds) will be written here.
   \param opcnt If not NULL, a conservative estimate of the total floating point
     operation count for this SHT will be written here. */
 void sharp_execute (sharp_jobtype type, int spin, void *alm, void *map,

libsharp/sharp_mpi.h

@@ -48,12 +48,13 @@ extern "C" {
     alm[0] points to the a_lm of the first SHT, alm[1] to those of the second
     etc. If \a spin>0, alm[0] and alm[1] point to the a_lm of the first SHT,
     alm[2] and alm[3] to those of the second, etc. The exact data type of \a alm
-    depends on the \a dp parameter.
+    depends on whether the SHARP_DP flag is set.
   \param map contains pointers to the maps. If \a spin==0,
     map[0] points to the map of the first SHT, map[1] to that of the second
-    etc. If \a spin>0, map[0] and map[1] point to the maps of the first SHT,
+    etc. If \a spin>0, or \a type is SHARP_ALM2MAP_DERIV1, map[0] and map[1]
-    map[2] and map[3] to those of the second, etc. The exact data type of \a map
+    point to the maps of the first SHT, map[2] and map[3] to those of the
-    depends on the \a dp parameter.
+    second, etc. The exact data type of \a map depends on whether the SHARP_DP
+    flag is set.
   \param geom_info A \c sharp_geom_info object compatible with the provided
     \a map arrays. The total map geometry is the union of all \a geom_info
     objects over the participating MPI tasks.
@@ -67,7 +68,7 @@ extern "C" {
     expected to have the type "double **"; otherwise, the expected
     types are "complex float **" and "float **", respectively.
   \param time If not NULL, the wall clock time required for this SHT
-    (in seconds)will be written here.
+    (in seconds) will be written here.
   \param opcnt If not NULL, a conservative estimate of the total floating point
     operation count for this SHT will be written here. */
 void sharp_execute_mpi (MPI_Comm comm, sharp_jobtype type, int spin,