windspharm is a Python package for performing computations on global wind fields in spherical geometry. It provides a high level interface for computations using spherical harmonics. windspharm is capable of computing the following quantities from an input vector wind:

  • divergence
  • vorticity (relative and absolute)
  • streamfunction
  • velocity potential
  • irrotational and non-divergent components of the wind (Helmholtz decomposition)
  • vector gradient of a scalar function
  • triangular truncation of a scalar field
  • magnitude (wind speed)

Download & Installation

The easiest way to install is via conda:

$ conda install -c conda-forge windspharm

Released versions of windspharm can be downloaded from Github. After downloading the source code archive, unzip it and change into the unzipped archive’s directory, then to install it:

$ python install

You can also check out the source code for the development version from the github repository to access features which are not yet in the released version.


This package requires as a minimum that you have numpy and pyspharm available, and requires setuptools for installation. The windspharm.iris interface can only be used if the iris package is available (see the iris documentation). The windspharm.cdms interface can only be used if the cdms2 module is available. This module is distributed as part of the UVCDAT project. The windspharm.xarray interface can only be used if the xarray package is available (see the xarray documentation).


It is strongly recommended to use pyspharm 1.0.8 or later. There is a bug in versions prior to 1.0.7 that causes incorrect fields to be returned when there is more than one input field, and a small bug in version 1.0.7 that causes problems with fields with a singleton time dimension.

Getting Started

The windspharm package provides several interfaces for performing computations. The standard interface is designed to work with numpy arrays. On top of this are layers desinged to work with more advanced data structures that also contain metadata. Currently there is support for iris cubes, xarray DataArrays, and cdms2 variables.

Regardless of which interface you use, the basic usage is the same. All computation is handled by a VectorWind instance initialized with global vector wind components. Method calls are then used to return quantities of interest.

The following is a very simple illustrative example which computes the streamfunction and vorticity associated with a global vector wind field using the iris interface:

import iris
from windspharm.iris import VectorWind

# Read u and v wind components from file.
u = iris.load_cube('')
v = iris.load_cube('')

# Create an instance of the VectorWind class to do the computations.
w = VectorWind(u, v)

# Call methods to compute streamfunction and relative vorticity.
psi = w.streamfunction()
xi = w.vorticity()


If you use windspharm in published research, please cite it by referencing the peer-reviewed paper. You can additionally cite the Zenodo DOI if you need to cite a particular version (but please also cite the paper, it helps me justify my time working on this and similar projects).

Developing and Contributing

Contributions big or small are welcomed from anyone with an interest in the project. Bug reports and feature requests can be filed using the Github issues system. If you would like to contribute code or documentation please see the Developer Guide.