.. default-role:: py:obj

.. toctree::
   :maxdepth: 2
   :hidden:

   userguide/index
   examples/index
   api/index
   changelog
   devguide/index


Introduction
============

`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_:

.. code-block:: bash

   $ conda install -c conda-forge windspharm

Released versions of `windspharm` can be downloaded from `Github <https://github.com/ajdawson/windspharm/releases>`_.
After downloading the source code archive, unzip it and change into the unzipped archive's directory, then to install it:

.. code-block:: bash

   $ python setup.py install

You can also check out the source code for the development version from the `github repository <https://github.com/ajdawson/windspharm>`_ to access features which are not yet in the released version.


Requirements
------------

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).


.. warning::

  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 :ref:`standard <standard-interface>` 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 :ref:`iris cubes <iris-interface>`, :ref:`xarray DataArrays <xarray-interface>`, and :ref:`cdms2 variables <cdms-interface>`.

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:

.. code-block:: python

   import iris
   from windspharm.iris import VectorWind


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

   # 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()


Citation
--------

If you use windspharm in published research, please cite it by referencing the `peer-reviewed paper <http://doi.org/10.5334/jors.129>`_.
You can additionally cite the `Zenodo DOI <https://zenodo.org/badge/latestdoi/20448/ajdawson/windspharm>`_ 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 :doc:`devguide/index`.


.. _UVCDAT: http://uvcdat.llnl.gov/

.. _iris: http://scitools.org.uk/iris

.. _xarray: http://xarray.pydata.org

.. _numpy: http://numpy.scipy.org

.. _pyspharm: https://code.google.com/p/pyspharm

.. _setuptools: https://pypi.python.org/pypi/setuptools

.. _issues: http://github.com/ajdawson/windspharm/issues?state=open

.. _windspharm: http://ajdawson.github.com/windspharm

.. _conda: http://conda.pydata.org/docs/

.. _binstar: https://binstar.org