Windspharm: A High-Level Library for Global Wind Field Computations Using Spherical Harmonics

The windspharm library is a Python package for performing computations on global wind fields in spherical geometry. It provides a high-level interface for computing derivatives and integrals of vector wind fields over a sphere using spherical harmonics. The software allows for computations with plain arrays, or with structures that include metadata, integrating with several popular data analysis libraries from the atmospheric and climate science community. The software is available on Github.


Introduction
Analysis of global wind fields is common in meteorology and climate science. Often we want to examine not just the vector wind field, but more complex derived quantities that allow deeper insight into the properties of the flow such as rotation and convergence/divergence. These properties of the flow are often expressed as derivatives or integrals of the vector wind. For example vorticity, a measure of rotation in a fluid, is computed as the curl of the wind field, and the corresponding streamfunction is the inverse Laplacian of vorticity. The derivative quantities could be computed via finite difference approximations, although care needs to be taken to correctly account for spherical geometry. However, the integral quantities can be much more difficult to compute.
One way to approach the problem of computing complex derivatives and integrals over the sphere is to use a spectral representation, where a field over the surface of a sphere is represented as the summation of a finite series of basis functions. The appropriate basis functions on the sphere are the spherical harmonics [1]. Spherical harmonics have some nice properties that make derivatives and integrals of fields expressed in terms of them straightforward to compute. For example, the inverse Laplacian operator required to compute streamfunction from vorticity is simply a scalar multiplication in the spectral representation, since the Laplacian of a spherical harmonic is proportional to the spherical harmonic itself [2]. A particular caveat of using the spectral approach is that the field to be analysed must have global coverage, it cannot work on data that cover only a limited area of the globe as the expansion in terms of basis spherical harmonics would not be defined. However, there are still many use cases in meteorology and climate science where this restriction does not present a problem.
Computations using the spectral method require a spherical harmonic transform, a procedure that takes a field defined on a regular global grid and transforms it into its spectral representation in terms of spherical harmonic coefficients. An inverse spherical harmonic transform procedure is also required in order to return a field represented in terms of spherical harmonic coefficients back to a regular grid. Finally, procedures to compute derivatives and integrals of the fields in spectral form are required. These are not trivial to implement, and doing so is out of scope for most researchers simply wishing to analyse global atmospheric circulation. However, these transforms and calculus operations are commonly used in atmospheric modelling, and well tested and optimized implementations of the required algorithms already exist. The windspharm library is designed to bridge the gap between the data analyst and the numerical computation, by providing a simple high-level interface to an existing numerical code that performs the complex calculations for the spectral method.
Of the existing software packages for computing with spherical harmonics, many are intended as low-level building blocks for implementing computational models [3,4,5,6]. These packages expose the spectral transform algorithms at a low-level, and are not easy to use or appropriate for most data analyst users. Some packages offer a higher-level interface to spherical harmonic computations aimed at data analysis, for example NCL [7] has a good suite of spherical harmonic operators that are tailored to atmospheric science use cases, although the capability to retain metadata through the computations is only partial due to language-level restrictions. windspharm was designed to allow users to take advantage of the powerful spectral computations without having to handle spherical harmonic coefficients themselves. The windspharm library brings a high-level interface, designed to be easy to use for atmospheric science use cases, along with good metadata support to atmospheric scientists working with Python.

Implementation and architecture
The windspharm library is implemented in a hierarchical structure. The core of the library consists of a solver object, which is constructed by passing input vector wind components on a regular grid represented as NumPy arrays [8]. Method calls to the solver object are made to construct the required output, again in the form of gridded arrays. Given vector wind components the solver can compute vorticity (relative and absolute), divergence, streamfunction, velocity potential, and rotational and divergent components of the wind field. Figure 1 shows example outputs from computing vorticity and streamfunction from a wind field. The solver can also apply spectral truncation to scalar fields, and compute the gradient of an arbitrary scalar field. These supplementary operations are useful for processing quantities output from other methods of the solver.
The solver is built on top of the pyspharm library, which is a Python interface to the SPHEREPACK software [3,9]. All of the numerical computation is handled by SPHEREPACK, a well-tested and highly optimized computational core, via the pyspharm Python interface. The primary role of windspharm is to provide an interface to these computations that does not expose the details of the methods. The user inputs data on a regular grid and always gets back results on the same regular grid, with windspharm managing calls to pyspharm to perform the operations required to compute the result.
On top of the core solver are several interfaces that can work with data structures that contain structured metadata as well as data values. Currently there are metadata interfaces that understand the data structures from iris [10], xarray [11], and cdms2 (part of UV-CDAT) [12]. The purpose of these interfaces is to allow the application of the computational routines to metadata-containing data structures without losing metadata. The consistency of metadata and data provenance in general are extremely important for correct and reproducible science, so this functionality holds significant value. The metadata interfaces are able to use the provided metadata to automatically reconfigure input data structures to the form required by the computational routines, and reform the output to match the input shape and dimensionality in a way that is transparent to the user. The presence of metadata also allows windspharm to perform more comprehensive error checking (e.g., identification of invalid input grids). The metadata interfaces are therefore not only convenient for the user, but also provide a benefit for program correctness. Extending the library to support other metadata-containing data structures is straightforward since the hierarchical design allows the implementation of additional metadata interfaces without having to implement any of the numerical components.

Quality control
The windspharm library features a suite of unit and integration tests that test the core functionality of the software. The end user can run these tests against their installed version of windspharm to verify it is functioning correctly. The test suite is updated as development on the library progresses. A continuous integration service Travis CI [13] is used to automatically run the full test suite on a variety of Python versions each time a pull request to the windspharm repository is made, which helps to ensure that changes and new features do not break the existing functionality.
The windspharm library also comes with some example programs and data, to demonstrate examples of how the library may be used. These example programs may require additional dependencies for plotting output, which are noted within the documentation for each program.

Linux, OSX
Programming language Python 2.7 or Python > = 3.3 Dependencies windspharm has a set of core dependencies that must be installed to use the software: • setuptools > = 0.7.2 • numpy > = 1.6 • pyspharm > = 1.8 The metadata interfaces are optional, and must be supported by additional optional dependencies. It is not expected that any one user would require all the available metadata interfaces, only needing the dependency for their interface(s) of choice from the list below: • iris > = 1.2 (for the iris metadata interface) • cdms2 (for the cdms2 metadata interface) • xarray (for the xarray metadata interface) Running the provided test suite also requires additional optional dependencies that are not required for normal use of windspharm:

English
(3) Reuse potential windspharm has been well used in the meteorology and climate science community. The library is distributed as part of the Ultrascale Visualization Climate Data Analysis Tools (UV-CDAT) project [12], and has been used in a significant number of publications that the author is aware of [14,15,16,17,18,19,20,21,22,23,24]. The library is also provided as part of the JASMIN Analysis Platform [25], indicating it has a significant user base. The potential for reuse is high, since windspharm implements a simple interface to complex vector computations that are extremely common in meteorology. Multiple metadata interfaces add to this potential, by allowing easy access to metadata retaining computations without forcing a particular environment on the user. Some users may be concerned about errors arising from the representation of the Earth as a sphere. On the typical spatial scales analysed with windspharm, errors due to shape of the Earth approximations are likely to be negligible. In addition to this, most applications of windspharm are to model derived data sets where the model will also have used a spherical Earth approximation, and therefore this potential source of error is not a concern. There also is potential for reuse in the wider field of planetary sciences. The package was designed for studies of terrestrial winds, but supports setting the radius of the sphere used in the spherical harmonic computations to an arbitrary distance, allowing its use on data and model output relevant to non-Earth planets with different planetary scales.
The software is documented on-line at http://ajdawson.github.io/windspharm. The software is supported on a voluntary basis through the repository's issue tracker. Contributions to the project are welcomed, and can be submitted by making a pull request to the windspharm Github repository.