/*! \mainpage libpsht documentation
  <ul>
  <li>\ref introduction "Introduction"
  <li><a href="modules.html">Programming interface</a>
  </ul>
 */

/*! \page introduction Introduction to libpsht

  "PSHT" is an acronym for <i>Performant Spherical Harmonic Transforms</i>.
  All user-visible data types and functions in this library start with
  the prefix "psht_", or with "pshts_" and "pshtd_" for single- and
  double precision variants, respectively.

  <i>libpsht</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>).
  A map is defined as a set of <i>rings</i>, which in turn consist of
  individual pixels that
  <ul>
  <li>all have the same colatitude and</li>
  <li>are uniformly spaced in azimuthal direction.</li>
  </ul>
  Consequently, a ring is completely defined by
  <ul>
  <li>its colatitute (in radians)</li>
  <li>the number of pixels it contains</li>
  <li>the azimuth (in radians) of the first pixel in the ring</li>
  <li>the weight that must be multiplied to every pixel during a map
      analysis (typically the solid angle of a pixel in the ring) </li>
  <li>the offset of the first ring pixel in the <i>map array</i></li>
  <li>the stride between consecutive pixels in the ring.</li>
  </ul>
  The map array is a one-dimensional array of type <i>float</i> or
  <i>double</i>, which contains the values of all map pixels. It is assumed
  that the pixels of every ring are stored inside this array in order of
  increasing azimuth and with the specified stride. Note however that the rings
  themselves can be stored in any order inside the array.

  The a_lm array is a one-dimensional array of type <i>pshts_cmplx</i> or
  <i>pshtd_cmplx</i>, which contains all spherical harmonic coefficients
  for 0<=m<=mmax and m<=l<=lmax. There is only one constraint on the
  internal structure of the array, which is:

  <code>Index[a_l+1,m] = Index[a_l,m] + stride</code>

  That means that coefficients with identical <i>m</i> but different <i>l</i>
  can be interpreted as a one-dimensional array in <i>l</i> with a unique
  stride.

  Several functions are provided for efficient index computation in this array;
  they are documented \ref almgroup "here".

  Information about a pixelisation of the sphere is stored in objects of
  type psht_geom_info. It is possible to create such an object for any
  supported pixelisation by using the function psht_make_geometry_info();
  however, several easier-to-use functions are \ref geominfogroup "supplied"
  for generating often-used pixelisations like ECP grids, Gaussian grids,
  and Healpix grids.

  A distinctive feature of PSHT is the ability to execute several transforms
  simultaneously (as long as they have the same geometry information and
  a_lm structure); this has the advantage that the spherical
  harmonics only have to be evaluated once for all of the transforms, saving
  a substantial amount of CPU time. The set of functions dealing with such
  <i>job lists</i> is implemented twice, both for \ref sjoblistgroup "single"
  and \ref djoblistgroup "double" precision transforms.

  Currently, PSHT supports the following kinds of transforms:
  <ul>
  <li>scalar a_lm to map</li>
  <li>scalar map to a_lm</li>
  <li>polarised a_lm to map</li>
  <li>polarised map to a_lm</li>
  <li>spin(1-100) a_lm to map</li>
  <li>spin(1-100) map to a_lm</li>
  <li>scalar a_lm to maps of first derivatives</li>
  </ul>

  All these different kinds can be mixed freely within a job list; i.e., it is
  possible to perform an a_lm->map and a map->a_lm transform simultaneously.

  PSHT supports shared-memory parallelisation via OpenMP; this feature will
  be automatically enabled if the compiler supports it.

  PSHT will also make use of SSE2 instructions when compiled for a platform
  known to support them (basically all Intel/AMD processors running a 64bit
  operating system).

  The spherical harmonic transforms can ce executed on double-precision and
  single-precision maps and a_lm, but for accuracy reasons the computations
  will always be performed in double precision. As a consequence,
  single-precision transforms will most likely not be faster than their
  double-precision counterparts, but they will require significantly less
  memory.

  Two example and benchmark programs are distributed with PSHT:
  <ul>
  <li>psht_test.c checks the accuracy of the (iterative) map analysis
      algorithm</li>
  <li>psht_perftest.c checks the performance of single or multiple
      transforms</li>
  </ul>
*/