SPHEREPACK 3.1: A Model Development Facility

by

John C. Adams and Paul N. Swarztrauber

August 2003

Computing on the sphere tutorials

Important information for users of SPHEREPACK version 2.0

Additions to SPHEREPACK 3.0 as of August 2003

ABSTRACT

SPHEREPACK 3.1 is a collection of FORTRAN programs that facilitates computer modeling of geophysical processes. The package contains programs for computing certain common differential operators including divergence, vorticity, gradients, and the Laplacian of both scalar and vector functions. Programs are also available for inverting these operators. For example, given divergence and vorticity, the package can be used to compute the velocity components. The Laplacian can also be inverted and therefore the package can be used to solve both the scalar and vector Poisson equations. Its use in model development is demonstrated by a sample program that solves the time-dependent non-linear shallow-water equations. Accurate solutions are obtained via the spectral method that uses both scalar and vector spherical harmonic transforms that are available to the user. The package also contains utility programs for computing the associated Legendre functions, Gauss points and weights, and multiple fast Fourier transforms. Programs are provided for both equally-spaced and Gauss distributed latitudinal points as well as programs that transfer data between these grids.

This work was partially supported by the Computer Hardware, Advanced Mathematics, and Model Physics (CHAMMP) Program which is administered by the Office of Energy Research under the Office of Health and Environmental Research in the U.S. Department of Energy, Environmental Sciences Division.

OBTAINING SPHEREPACK SOFTWARE

Documentation for driver subroutines can be accessed as text files from this site (see Table 1 in this document). The entire SPHEREPACK fortran package can be downloaded after signing a UCAR licensing agreement which includes, among other provisions, that the software is not to be used for commercial purposes, modified, or distributed further. The SPHEREPACK manual can be downloaded as a pdf or postscript file (go to the end of this document for instructions).

When you order SPHEREPACK from NCAR you are assured of receiving original source code from its creators. You avoid security conerns associated with pirated or "shared" software. It will also be possible to contact you when software corrections and improvements occur.

To order SPHEREPACK 3.1, complete the SPHEREPACK 3.1 order form

Overview

SPHEREPACK 3.1 is a collection of FORTRAN programs that facilitates the development of computer models of geophysical processes. In addition to the programs in SPHEREPACK 1.0, it contains a suite of programs for the application of certain common differential operators including vorticity, divergence, gradient, Laplacian, and latitudinal derivatives. In addition, programs are available for inverting these operators. For example, given vorticity and divergence, the package can be used to reconstruct the corresponding vector function. Also, given the gradient, the corresponding scalar function can be computed. Both the scalar and vector Laplacian can be computed or inverted. Therefore the programs can be used to solve both the scalar and vector Poisson equations.

The package can also be used to solve time dependent partial differential equations. In particular, the package facilitated the development of nine spectral models of the shallow-water equations that were evaluated in (Swarztrauber, 1996). One such model is given in section 3.3 which provides an example of how SPHEREPACK 3.1 can be used to solve the nonlinear shallow-water equations on the sphere. The package also contains utility programs for computing the associated Legendre functions, multiple fast Fourier transforms, an icosahedral geodesic, and Gauss points and weights. All computations can be performed on either a Gauss or equally-spaced latitudinal grid and programs are available for interpolating between these grid systems. There is no difference in the accuracy or computing time of these systems; however, they alias differently (Temperton, 1991).

SPHEREPACK 3.1 is a significant extension of SPHEREPACK 1.0 which included programs for the spherical harmonic analysis and synthesis of scalar functions only. In addition to these programs, and those listed above, SPHEREPACK 3.1 contains separate programs for the analysis and synthesis of vector functions. Although the components of a vector function, such as a wind field, are smooth in Cartesian coordinates, they can nevertheless be discontinuous in spherical coordinates because of the discontinuity in the coordinate system itself (Swarztrauber, 1993). Therefore the spectral representation and analysis of a vector function is fundamentally different from that of a scalar function.

Scalar and vector harmonic analyses are used for problem solving in spherical coordinates in the same way that Fourier analysis is used in Cartesian coordinates. Consequently SPHEREPACK 3.1 provides the same high level of accuracy that the spectral method provides in Cartesian coordinates. Furthermore, accuracy is uniform on the sphere and independent of the location of the poles. This eliminates a number of computational difficulties associated with solving partial differential equations on the sphere including the accuracy and stability problems that can be created by the clustering of points near the pole. Interpolation and smoothing on the sphere are also significantly facilitated by harmonic analysis (Swarztrauber, 1979). Indeed the package includes programs for interpolating between Gaussian and equally-spaced latitudinal grids.

Contents of SPHEREPACK 3.1

The contents of the package are listed here with a sentence or two description of each program. The package consists of driver programs that compute or invert the differential operators that are required by the user's application. In turn, the driver programs call the utility programs that implement the analyses and syntheses required by the harmonic or spectral method on the sphere.

Most of the programs that compute the differential operators require the harmonic analysis of the scalar or vector function prior to computing the operator. For example, to compute the Laplacian of a scalar function using slapec, one must first compute the spectral coefficients using subroutine shaec. The reason shaec is not called by slapec is to avoid repeated computation of spectral coefficients when more than one differential operator is applied to the same function.

The major options provided by SPHEREPACK are:

1. The colatitudinal grid can be either Gaussian or equally-spaced. There is no restriction on the number of grid points in either the latitude or longitude direction. The spectral truncation is always triangular.
2. Computations can be performed on the entire sphere or, if symmetries permit, on the northern hemisphere only. The user can specify even or odd symmetry about the equator and thereby halve both storage and computing time.
3. The user can elect to store certain quantities for repeated use in subsequent calls to the same subroutine. Storage is increased from O(N**2) to O(N**3) and computing time is reduced by about 30%.
4. When applicable, the differential operators and harmonic transforms can be applied to multiple functions with a single subroutine call. This reduces the computing time for additional functions by about 30% compared to multiple calls of the subroutine. This is usually used with the O(N**2) storage option.

A list of user entry programs is given below. Where applicable, the programs are named with the following conventions: The characters sh or vh denote scalar and vector harmonic transforms respectively. The character a or s denotes analysis or synthesis. The character g or e denotes Gaussian or equally-spaced latitudinal grid, and the character c or s denotes whether or not the quantities in 3. above are computed or stored. That is, whether the O(N**2) or O(N**3) storage option is selected.

Note: for latitudinal derivatives of scalar functions use the gradient programs.

vtsec

computes the derivative of the vector function with respect to colatitude on a equally-spaced grid using O(N**2) storage, initialized by vtseci.

vtses

computes the derivative of the vector function with respect to colatitude on a equally-spaced grid using O(N**3) storage, initialized by vtsesi.

vtsgc

computes the derivative of the vector function with respect to colatitude on a Gaussian grid using O(N**2) storage, initialized by vtsgci.

vtsgs

computes the derivative of the vector function with respect to colatitude on a Gaussian grid using O(N**3) storage, initialized by vtsgsi.

grades

computes the gradient of a scalar function on an equally spaced grid using O(N**3) storage, initialized by vhsesi.

gradec

computes the gradient of a scalar function on an equally spaced grid using O(N**2) storage, initialized by vhseci.

gradgs

computes the gradient of a scalar function on a Gaussian grid using O(N**3) storage, initialized by vhsgsi.

gradgc

computes the gradient of a scalar function on a Gaussian grid using O(N**2) storage, initialized by vhsgci.

igrades

computes a scalar function whose gradient is a given vector function on an equally spaced grid using O(N**3) storage, initialized by shsesi.

igradec

computes a scalar function whose gradient is a given vector function on an equally spaced grid using O(N**3)storage, initialized by shseci.

igradgs

computes a scalar function whose gradient is a given vector function on a Gaussian grid using O(N**3) storage, initialized by shsgsi.

igradgc

computes a scalar function whose gradient is a given vector function on a Gaussian grid using O(N**2) storage, initialized by shsgci.

dives

computes the divergence of a vector function on an equally spaced grid using O(N**3) storage, initialized by shsesi.

divec

computes the divergence of a vector function on an equally spaced grid using O(N**2) storage, initialized by shseci.

divgs

computes the divergence of a vector function on a Gaussian grid using O(N**3) storage, initialized by shsgsi.

divgc

computes the divergence of a vector function on a Gaussian grid using O(N**2) storage, initialized by shsgci.

idives

computes an irrotational vector function whose divergence is given on an equally spaced grid using O(N**3) storage, initialized by vhsesi.

idivec

computes an irrotational vector function whose divergence is given on an equally spaced grid using O(N**2) storage, initialized by vhseci.

idivgs

computes an irrotational vector function whose divergence is given on a Gaussian grid using O(N**3) storage, initialized by vhsgsi.

idivgc

computes an irrotational vector function whose divergence is given on a Gaussian grid using O(N**2) storage, initialized by vhsgci.

vrtes

computes the scalar vorticity of a vector function on an equally spaced grid using O(N**3) storage, initialized by shsesi.

vrtec

computes the scalar vorticity of a vector function on an equally spaced grid using O(N**2) storage, initialized by shseci.

vrtgs

computes the scalar vorticity of a vector function on a Gaussian grid using O(N**3) storage, initialized by shsgsi.

vrtgc

computes the scalar vorticity of a vector function on a Gaussian grid using O(N**2) storage, initialized by shsgci.

ivrtes

computes a divergence-free vector function whose vorticity is given on an equally spaced grid using O(N**3) storage, initialized by vhsesi.

ivrtec

computes a divergence-free vector function whose vorticity is given on an equally spaced grid using O(N**2) storage, initialized by vhseci.

ivrtgs

computes a divergence-free vector function whose vorticity is given on a Gaussian grid using O(N**3) storage, initialized by vhsgsi.

ivrtgc

computes a divergence-free vector function whose vorticity is given on a Gaussian grid using O(N**2) storage, initialized by vhsgci.

idvtes

computes a vector function with given divergence and vorticity on an equally spaced grid using O(N**3) storage, initialized by vhsesi.

idvtec

computes a vector function with given divergence and vorticity on an equally spaced grid using O(N**2) storage, initialized by vhseci.

idvtgs

computes a vector function with given divergence and vorticity on a Gaussian grid using O(N**3) storage, initialized by vhsgsi.

idvtgc

computes a vector function with given divergence and vorticity on a Gaussian grid using O(N**2) storage, initialized by vhsgci.

slapes

computes the scalar Laplacian of a scalar function on an equally spaced grid using O(N**3) storage, initialized by shsesi.

slapec

computes the scalar Laplacian of a scalar function on an equally spaced grid using O(N**2) storage, initialized by shseci.

slapgs

computes the scalar Laplacian of a scalar function on a Gaussian grid using O(N**3) storage, initialized by shsgsi.

slapgc

computes the scalar Laplacian of a scalar function on a Gaussian grid using O(N**2) storage, initialized by shsgci.

islapes

computes a scalar function whose scalar Laplacian is given on an equally spaced grid using O(N**3) storage, initialized by shsesi.

islapec

computes a scalar function whose scalar Laplacian is given on an equally spaced grid using O(N**2) storage, initialized by shseci.

islapgs

computes a scalar function whose scalar Laplacian is given on a Gaussian grid using O(N**3) storage, initialized by shsgsi.

islapgc

computes a scalar function whose scalar Laplacian is given on a Gaussian grid using O(N**2) storage, initialized by shsgci.

vlapes

computes the vector Laplacian of a given vector function on an equally spaced grid using O(N**3) storage, initialized by vhsesi.

vlapec

computes the vector Laplacian of a given vector function on an equally spaced grid using O(N**2) storage, initialized by vhseci.

vlapgs

computes the vector Laplacian of a given vector function on a Gaussian grid using O(N**3) storage, initialized by vhsgsi.

vlapgc

computes the vector Laplacian of a given vector function on a Gaussian grid using O(N**2) storage, initialized by vhsgci.

ivlapes

computes a vector function whose vector Laplacian is a given vector function on an equally spaced grid using O(N**3) storage, initialized by vhsesi.

ivlapec

computes a vector function whose vector Laplacian is a given vector function on an equally spaced grid using O(N**2) storage, initialized by vhseci.

ivlapgs

computes a vector function whose vector Laplacian is a given vector function on a Gaussian grid using O(N**3) storage, initialized by vhsgsi.

ivlapgc

computes a vector function whose vector Laplacian is a given vector function on a Gaussian grid using O(N**2) storage, initialized by vhsgci.

sfvpes

computes the stream function and velocity potential of a vector function on an equally spaced grid using O(N**3) storage, initialized by shsesi.

sfvpec

computes the stream function and velocity potential of a vector function on an equally spaced grid using O(N**2) storage, initialized by shseci.

sfvpgs

computes the stream function and velocity potential of a vector function on a Gaussian spaced grid using O(N**3) storage, initialized by shsgsi.

sfvpgc

computes the stream function and velocity potential of a vector function on an Gaussian spaced grid using O(N**2) storage, initialized by vhsgci.

isfvpes

computes a vector function with a given stream function and velocity potential on an equally spaced grid using O(N**3) storage, initialized by vhsesi.

isfvpec

computes a vector function with a given stream function and velocity potential on an equally spaced grid using O(N**2) storage, initialized by vhseci.

isfvpgs

computes a vector function with a given stream function and velocity potential on a Gaussian spaced grid using O(N**3) storage, initialized by vhsgsi.

isfvpgc

computes a vector function with a given stream function and velocity potential on a Gaussian spaced grid using O(N**2) storage, initialized by vhsgci.

trssph

transfers scalar data from one spherical grid to another. The grids can be Gaussian or equally spaced.

trvsph

transfers vector data from one spherical grid to another. The grids can be Gaussian or equally spaced.

sshifte

transfers scalar data on the sphere between an equally spaced grid that is offset by a half grid increment in both longitude and latitude (which excludes the poles) and an equally spaced grid that includes the poles.

vshifte

transfers vector data on the sphere between an equally spaced grid that is offset by a half grid increment in both longitude and latitude (which excludes the poles) and an equally spaced grid that includes the poles.

note: most SPHEREPACK 3.1 software require scalar and vector fields in mathematical spherical coordinates.

shaec

computes the spherical harmonic analysis on an equally spaced grid using O(N**2) storage, initialized by shaeci.

shaes

computes the spherical harmonic analysis on an equally spaced grid using O(N**3) storage, initialized by shaesi.

shagc

computes the spherical harmonic analysis on a Gaussian grid using O(N**2) storage, initialized by shagci.

shags

computes the spherical harmonic analysis on a Gaussian grid using O(N**3) storage, initialized by shagsi.

shsec

computes the spherical harmonic synthesis on an equally spaced grid using O(N**2) storage, initialized by shseci.

shses

computes the spherical harmonic synthesis on an equally spaced grid using O(N**3) storage, initialized by shsesi.

shsgc

computes the spherical harmonic synthesis on a Gaussian grid using O(N**2) storage, initialized by shsgci.

shsgs

computes the spherical harmonic synthesis on a Gaussian grid using O(N**3) storage, initialized by shsgsi.

shpe

computes the spherical harmonic analysis and synthesis on an equally spaced grid using O(N**2) storage, initialized by shpei.

shpg

computes the spherical harmonic analysis and synthesis on a Gaussian grid using O(N**2) storage, initialized by shpgi.

vhaec

computes the vector harmonic analysis on an equally spaced grid using O(N**2) storage, initialized by vhaeci.

vhaes

computes the vector harmonic analysis on an equally spaced grid using O(N**3) storage, initialized by vhaesi.

vhagc

computes the vector harmonic analysis on a Gaussian grid using O(N**2) storage, initialized by vhagci.

vhags

computes the vector harmonic analysis on a Gaussian grid using O(N**3) storage, initialized by vhagsi.

vhsec

computes the vector harmonic synthesis on an equally spaced grid using O(N**2) storage, initialized by vhseci.

vhses

computes the vector harmonic synthesis on an equally-spaced grid using O(N**3) storage, initialized by vhsesi.

vhsgc

computes the vector harmonic synthesis on a Gaussian grid using O(N**2) storage, initialized by vhsgci.

vhsgs

computes the vector harmonic synthesis on a Gaussian grid using O(N**3) storage, initialized by vhsgsi.

alfk

computes the coefficients in the trigonometric series representation of P_nm( theta ).

lfp

uses coefficients computed by routine alfk to tabulate P_nm( theta ) at equally-spaced colatitudes.

lfpt

uses coefficients computed by routine alfk to compute P_nm( theta ) at a single colatitude theta.

lfim

given n, L,and theta_i lfim computes P_nm( theta_i ) for m=0,...,n and i=1,...,L.

lfin

given N, m, L and theta_i lfin computes P_nm( theta_i ) for n=m,...,N and i=1,...,L

Additional programs for computing the associated Legendre functions are included in ALFPACK which is also available from the National Center for Atmospheric Research.

ihgeod

computes the Cartesian coordinates of the points on the surface of the sphere corresponding to a twenty-sided geodesic.

hrfftf

multiple real forward fast fourier transforms, initialized by hrffti.

hrfftb

multiple real backward fast fourier transforms, initialized by hrffti

Additional programs are included in FFTPACK which is also available from the National Center for Atmospheric Research.

gaqd

computes the Gaussian colatitudes and weights that are used in the Gaussian quadrature.

visequ

three-dimensional rendering of a scalar function defined on an equally-spaced latitudinal grid.

visgau

three-dimensional rendering of a scalar function defined on a Gauss distributed latitudinal grid, initialized by gaqd.

visgeo

three-dimensional rendering of a scalar function defined on a geodesic grid, initialized by geopts.

Downloading SPHEREPACK 2.0 technical info:

The following NCAR Technical Note contains identities, formulas, and computational methods that are used by SPHEREPACK 2.0 and 3.1.

J. C. Adams and P. N. Swarztrauber, SPHEREPACK 2.0: A model development facility, NCAR Technical Note NCAR/TN-436-STR, September 1997.

Download the postscript version by clicking on spherepack.ps. Download the pdf version by clicking on spherepack.pdf. A postscript file named "spherepack.ps" or pdf file named "spherepack.pdf" will automatically be placed on your local computer. Print the file as would any other postscript or pdf file.

Return to beginning of this document