Module spharm

source code

Introduction

This module provides a python interface to the NCAR SPHEREPACK library. It is not a one-to-one wrapper for the SPHEREPACK routines, rather it provides a simple interface oriented toward working with atmospheric general circulation model (GCM) data.

Requirements

• numpy, and a fortran compiler supported by numpy.f2py.

Installation

• Download module source, untar.
• run python setup.py install (as root if necessary). The SPHERPACK fortran source files will be downloaded automatically by the setup.py script, since the SPHEREPACK license prohibits redistribution. To specify the fortran compiler to use (e.g. g95) run python setup.py config_fc --fcompiler=g95 install. f2py -c --help-fcompiler will show you what fortran compilers are available.

Usage

>>> import spharm
>>> x=spharm.Spharmt(144,72,rsphere=8e6,gridtype='gaussian',legfunc='computed')

creates a class instance for spherical harmonic calculations on a 144x72 gaussian grid on a sphere with radius 8000 km. The associated legendre functions are recomputed on the fly (instead of pre-computed and stored). Default values of rsphere, gridtype and legfunc are 6.3712e6, 'regular' and 'stored'. Real-world examples are included in the source distribution.

Class methods

• grdtospec: grid to spectral transform (spherical harmonic analysis).
• spectogrd: spectral to grid transform (spherical harmonic synthesis).
• getuv: compute u and v winds from spectral coefficients of vorticity and divergence.
• getvrtdivspec: get spectral coefficients of vorticity and divergence from u and v winds.
• getgrad: compute the vector gradient given spectral coefficients.
• getpsichi: compute streamfunction and velocity potential from winds.
• specsmooth: isotropic spectral smoothing.

Functions

• regrid: spectral re-gridding, with optional spectral smoothing and/or truncation.
• gaussian_lats_wts: compute gaussian latitudes and weights.
• getspecindx: compute indices of zonal wavenumber and degree for complex spherical harmonic coefficients.
• legendre: compute associated legendre functions.
• getgeodesicpts: computes the points on the surface of the sphere corresponding to a twenty-sided (icosahedral) geodesic.
• specintrp: spectral interpolation to an arbitrary point on the sphere.

Conventions

The gridded data is assumed to be oriented such that i=1 is the Greenwich meridian and j=1 is the northernmost point. Grid indices increase eastward and southward. If nlat is odd the equator is included. If nlat is even the equator will lie half way between points nlat/2 and (nlat/2)+1. nlat must be at least 3. For regular grids (gridtype='regular') the poles will be included when nlat is odd. The grid increment in longitude is 2*pi/nlon radians. For example, nlon = 72 for a five degree grid. nlon must be greater than or equal to 4. The efficiency of the computation is improved when nlon is a product of small prime numbers.

The spectral data is assumed to be in a complex array of dimension (ntrunc+1)*(ntrunc+2)/2. ntrunc is the triangular truncation limit (ntrunc = 42 for T42). ntrunc must be <= nlat-1. Coefficients are ordered so that first (nm=0) is m=0,n=0, second is m=0,n=1, nm=ntrunc is m=0,n=ntrunc, nm=ntrunc+1 is m=1,n=1, etc. The values of m (degree) and n (order) as a function of the index nm are given by the arrays indxm, indxn returned by getspecindx.

The associated legendre polynomials are normalized so that the integral (pbar(n,m,theta)**2)*sin(theta) on the interval theta=0 to pi is 1, where pbar(m,n,theta)=sqrt((2*n+1)*factorial(n-m)/(2*factorial(n+m)))* sin(theta)**m/(2**n*factorial(n)) times the (n+m)th derivative of (x**2-1)**n with respect to x=cos(theta). theta = pi/2 - phi, where phi is latitude and theta is colatitude. Therefore, cos(theta) = sin(phi) and sin(theta) = cos(phi). Note that pbar(0,0,theta)=sqrt(2)/2, and pbar(1,0,theta)=.5*sqrt(6)*sin(lat).

The default grid type is regular (equally spaced latitude points). Set gridtype='gaussian' when creating a class instance for gaussian latitude points.

Quantities needed to compute spherical harmonics are precomputed and stored when the class instance is created with legfunc='stored' (the default). If legfunc='computed', they are recomputed on the fly on each method call. The storage requirements for legfunc="stored" increase like nlat**2, while those for legfunc='stored' increase like nlat**3. However, for repeated method invocations on a single class instance, legfunc="stored" will always be faster.