Version 3 routines for conformal and smoothed mappings from various
polyhedra to the sphere. R. J. Purser, NCEP 2003 (jim.purser@ncep.noaa)

	OVERVIEW OF THE MAPPING SUITE
The geometries supported are given 3-letter codes as follows:
	cub : cubic
	dod : dodecagonal
	ico : icosahedral 
	oct : octagonal
	sqr : square
	tet : tetrahedral
with the prefix, c, (for example, ccub) denoting the conformal variety, and
the prefix, s, (for example, scub) denoting the "smoothed" (more homogeneous)
variety. The "primary" utility routines that must be compiled (and preferably
organized into their respective libraries) before using the higher level
mapping routines are prefixed by p and are as follows:
	pkinds : The module supplying the Fortran 90/95 real and complex
	         "kind" parameters for single and double precision.
		 COMPILE THIS FIRST AND PUT THE MODULE WHERE IT IS 
                 AVAILABLE TO ALL THE OTHER PROGRAMS.
	pfft   : Fourier routines, only used by routines in ccub1.f90,
                 cdod1.f90, etc, to initialize the conformal coefficients.
	pgeo   : Standard geography transformation routines.
	pinv   : Linear inversion utilities.   } Not used for conformal, but
	pleg   : Spherical harmonics utilities } only for smoothed mappings.
	ptay   : Taylor series utilities.

	pfig   : If you want a crude graphics package, create new directory,
                 "pfig" and copy the contents of pfig_src into it. (Keep
	         pfig_src as safe back-up, because the Makefile often
	         messes things up too badly to allow easy recovery!) Adapt
		 the Makefile carefully, and use it to construct the 
		 library, libpfig.a, in the desired location. However,
		 this suite is not an integral part of the mapping suite
		 and no guarantees are given!

A "secondary" suite of generic "hedral" utilities, used only for the smoothed
mapping options, must only be compiled AFTER the compilation of pleg:
	shed   : General input/output and smooth sphere-to-sphere mappings
                 (used only for the "smoothed" mapping options).

The higher level routines deal with the complete mappings. We will take the
cubic geometry as the representative example.

	CONFORMAL MAPPINGS
	In directory ccub, the source file, ccub.f90, contains the main
suite of utility mapping routines and modules. COMPILE IT BEFORE THE OTHERS.
If the dataset containing the Taylor series is not given, or if it is 
required to compute it again at a different truncation or precision, it is
necessary to compile source file, ccub1.f90. Typically, ccub.o and ccub1.o
are stored in a convenient library. For graphical depiction of maps obtained
under these transformations, some routines analogous to those given in
the suite, ccub2.f90, will be needed. ccub2.f90 use the graphics package
"pfig" (source provided, for completeness, in directory pfig_src) but the 
user will invariably wish to use his/her own graphics utilities and rewrite 
some of the tasks performed in ccub2.f90 in his/her own way. Other source
files provided as examples are: ccuba.f90, the program that controls the
initial creation of dataset(s) containing the basic conformal mapping
coefficients for this hedron; ccubb.f90, a program illustrating the creation
of maps (using the pfig package).

	SMOOTHED MAPPINGS
	Continuing with the cube as the paradigm, the "smoothed" mapping
routines are contained in directory scub. The main source code is provided
in scub.f90. ENSURE THAT THE ROUTINES IN ccub.f90 ARE COMPILED FIRST AND
THEIR MODULES AND COEFFICIENT DATASETS ARE MADE AVAILABLE HERE. The example 
program, scuba.f90, shows how to create a dataset containing the coefficients
needed to modify the conformal mapping to a more homogeneuos "smoothed"
mapping. Prerequisites are the pair of relevant symmetry files for this 
hedron. For the cube, the suggested names for the "integer" and "real" parts 
of the symmetry data are ticub080.dat and trcub080.dat, which encode the
symmetric combinations of vector spherical harmonics up to truncation 80.
These binary files are hardware dependent, so they must be created from
a generic source, which is the ASCII file tacub080.dat in directory shed.
To convert the ASCII file to the binary pair, use the program atofg.f90
also supplied in /shed/. scubb.f90 provides some graphics examples 
(cf. ccubb.f90). which invoke the routines of scub2.f90 (cf. ccub2.f90).

	VERSION 3 CONVENTIONS. Note that the variational principle, upon
which the definitions of the smoothed mappings depend, has been modified
in two ways since version 2:
	1.  	To start with, the non-conformal penalty
component, sa, is weighted by (1-alpha) and the inhomogeneity penalty, sb,
by alpha, which puts these two terms on a more equal footing than in
Version 2 (where the sa term was unweighted and the alpha was allowed to
be any nonnegative value). In Version 3, alpha=0 still implies the unaltered
conformal solution, but quasi-homogeneous mappings now require that alpha
be within the range [0,1]. The "homogeneous" extreme, alpha=1, is now a
possible option, but do not expect the actual mapping jacobian to be
a constant everywhere - remember that the variational principle is solved
only in the restricted subspace of distortions of the conformal mapping
that are feasible in terms of the prescribed spectral truncation of the
vector harmonics used to generate these distortions.
	2.	A new penalty, sc, has been added to the variational
function. sc is a quadratic penalty on the individual coefficients, rco,
of the spectral distortion components. The purpose of this additional term
is to suppress Gibbs effects apparent at relatively large values of alpha
caused by the abrupt truncation of the spectrum of distortion components.
If n is the total wavenumber of the vector spherical harmonic associated
with the particular component with coefficient, rco(k), the contribution of 
this component to sc is given by sc(k)= .5*(gibbssc*n)**gibbsexp*rco(k)**2.
The Gibbs suppression coefficient, gibbssc, is typically between 0 and 1;
the Gibbs exponent, gibbsexp, is real, nonnegative, and typically between
6. and 20. One has to use iterative trials to achieve the best combination
of spectral trunction (nleg), alpha, gibbssc and gibbsexp for each 
application. In many cases it will suffice to dispense with the additional
complication of the Gibbs terms and just set them both to zero. Even
for the larger values of alpha where Gibbs suppression might be desirable,
it is best to see how the grid looks with gibbssc=gibbsexp=0 and tune
alpha first, and only then apply gibbs suppression if it is needed,
with sparing use of gibbssc.

	SYMMETRIES
	The six hedral mapping geometries derive their symmetries from five
distinct symmetry groups. Note that the octagon and dodecagon geometries
do NOT possess symmetries of the regular forms of these polygons' dihedra,
but rather the lower symmetries of the square and hexagonal dihedra
respectively. (The quasi-regular octagon and dodecagon must have shapes that
allow continuous gridding by a square grid and a triangular grid 
respectively.) Here are the symmetries, their mnemonics, their orders, and
the geometries they underlie:
Symmetry          	mnemonic       order       associated geometries
cubic: 			"cub" 		48 		"cub"
hexagonal dihedron	"hex"           24              "dod"           
icosahedral:    	"ico"	       120              "ico"
square dihedron:        "sqr"		16           	"sqr", "oct"
tetrahedron:            "tet"           24              "tet"
(No hexagonal dihedral geometry is supported because it possesses no
compelling advantages). 

Although the square dihedron naturally suggests a square gridding and
the tetrahedron neturally suggests a regular triangular gridding, the
180-degree  vertex angles of these two geometries means that a 
QUASI-equilateral triangular gridding of the square dihedron and a
QUASI-square gridding of the tetrahedron are also possible. For these, it
is convenient to exploit one or other of the following approximations to
the ratio, {sqrt(3):1}:
{7:4}, {19:11}, {26:15}, {71:41}, {97:56}, etc.
The programs ssqrc.f90 and stetc.f90 are provided (together with additional
routines in rtom.f90) as examples of this approach.