atmqty: A Python Package for Calculating Atmospheric Quantities

Introduction

This package contains methods to calculate atmospheric quantities that are directly derivative (i.e. not requiring time integration or modeling) from standard state variables. The AtmQty class that manages these quantities and the AtmConst class of atmosphere-related constants are defined in this package.

Although I've used these routines in my own research, I cannot guarantee that they will work for your purposes. More disclaimers and other fine print is below.

If you email me your email address, however, I'll let you know of any major bugs that are found in this package.

The page is subdivided into these categories:


Package Description

General

Atmospheric Constants: There are three ways of using this package. The first way is to use it only for the AtmConst class, which provides a comprehensive and consistent definition of important atmospheric constants. Constants are defined in the class as object attributes. The AtmConst class is found in the atmconst module in the package. Here is an example of creating an object of constants and accessing the gas constant for dry air:

>>> from atmqty.atmconst import AtmConst
>>> const = AtmConst()
>>> const.R_d
287.05000000000001

The pydoc documentation for the AtmConst class provides details as to what constants are defined and their units.

Procedural Functions: The second way is to use this package is to use the "procedural functions" (i.e. functions which we can use procedurally) that calculate "atmospheric quantities" (quantities that are "directly derivative," i.e. not requiring time integration or modeling, from standard state variables). The modules in this package (except __init__ and atmconst) describe such procedural functions, which are invoked by function call and accept state variable Numeric arrays of any size and shape as positional argument input. In general each module (besides __init__ and atmconst) contains a single function of the same name as the module.

For instance, say you have arrays of pressure and temperature and you want to calculate potential temperature. The function theta in module theta will do the trick. Below is an example of this:

>>> import Numeric as N
>>> from atmqty.theta import theta
>>> p = N.array([1000., 850., 500.])
>>> T = N.array([273.1, 257.3, 233.1])
>>> var = theta(p,T)
>>> var
array([ 273.1 , 269.53760511, 284.18991897])

If the input arrays have missing data (and the missing data need not be at the same locations among the different input fields), the missing keyword specifies the value of the missing data, and the function will return output that has that value at locations where the calculation of the atmospheric quantity could not be done (as default, missing values are assumed to be 1e+20). The following example shows how to calculate potential temperature when 1e+29 represents a missing value:

>>> import Numeric as N
>>> from atmqty.theta import theta
>>> p = N.array([1000., 1010., 1008.2])
>>> T = N.array([273.1, 1e+29, 278.4])
>>> a = theta(p, T, missing=1e+29)
>>> a [ 2.73100000e+02, 1.00000000e+29, 2.77750730e+02,]

AtmQty Object: Finally, you can use this package to define an object from the AtmQty class which manages the calculation of self-consistent atmospheric quantities on a 3-D latitude, longitude, level grid on the sphere. Below is an example of defining an AtmQty object on a single-level (at 850 hPa) latitude-longitude domain, based on "made-up" data. First, we initialize the object given the latitude (lat), longitude (lon), and pressure level (lev) values of our domain. The level type (lev_type) can be set to either pressure levels ('pressure') or isentropic levels ('isentropic'):

>>> import atmqty
>>> import Numeric as N
>>> lat = N.arange(13) * 15.0 - 90.0
>>> lon = N.arange(25) * 15.0 - 180.0
>>> lev = N.array(850.)
>>> x = atmqty.AtmQty(lat, lon, lev, lev_type='pressure', missing=1e+29)

Note that the AtmQty class can handle missing values. As default, the class assumes missing values are set to 1e+20. In our synthetic dataset, missing values will have the value 1e+29, and we set this when we instantiate the AtmQty object. Also, to save typing we import the Numeric package as N. Once the object is instantiated, do not change any of the spatial dimensions or the missing value value; if you do you could make the atmospheric quantities in the object inconsistent with each other.

Next we create our "made-up" dataset of temperature (T) and specific humidity (q), basing it on a pattern (base) that consists of two "distorted bulls-eyes" of opposite polarity, centered over the poles. We make a few of the elements in temperature near the South Pole be "missing." We add extra "shallow" dimension to represent the single level, so the array is rank 3, not 2, and use the add_qty method to add the temperature and humidity to a quantities dictionary in the object. The final line:

>>> base = N.outerproduct(N.sin(lat*N.pi/360.), N.cos(lon*N.pi/360.))
>>> base = N.reshape(base, (base.shape[0], base.shape[1], 1))
>>> T = (base * 10.) + 257.3
>>> T[1,2:5,0] = 1e+29
>>> q = N.absolute(base) * 5e-3
>>> x.add_qty( {'q':q, 'T':T} )

All quantities managed by the object, whether they are input values or are calculated, are in the object attribute qty. Thus, in the above example, the dictionary of atmospheric quantities is x.qty.

Now we can use the object to calculate quantities derivative from temperature and specific humidity. To calculate potential temperature, we use the object's theta method:

>>> x.theta()

The potential temperature is now calculated and stored in the object's quantities dictionary x.qty. If we want to set the potential temperature to a separate variable (say T_pot, we can use the get_qty method:

>>> T_pot = x.get_qty('theta')

or directly access the potential temperature entry in the x.qty dictionary:

>>> T_pot = x.qty['theta']

Other quantities (e.g. vapor pressure, etc.) are calculated similarly. A detailed description of which methods are available to the object are in the module listing below. All code is written in the Python language (with the Numerical Python (Numpy) extension, which includes the Numeric, MA packages) and can probably run on any platform on which Python and Numpy runs. A few of the modules, however, do use packages that are available on a limited number of platforms (again, see the module listing below for details).

Planned future development of the package:

Bugs and Updates

A summary list of bugs and updates to the package is found here.

Help

The module listing section below includes pydoc generated documentation of the modules in the package. The Python interactive help method provides similar functionality:

Finally, here are some summary sheets for this package:

[Back up top to the Introduction.]


Module Listing

All modules in the package are listed below. The "Module Name" column provides links to the module source code. The "Pydoc" column provides links to documentation produced from the module docstrings by the pydoc tool. The "Depend" column indicates which modules have package dependencies beyond built-in Python, Numpy, and other atmqty modules; if the module has no such dependencies, the column is filled with "None".

For a detailed description of the entire package, see the pydoc generated documentation for __init__.py.

Module Name Pydoc Depend Function
__init__.py HTML None Initialize package; define class AtmQty of atmospheric quantities.
atmconst.py HTML None Define class AtmConst of atmospheric constants.
eice.py HTML None Calculate saturation vapor pressure over ice.
esat.py HTML None Calculate saturation vapor pressure over liquid water.
is_numeric_float.py HTML None Check whether a variable is a Numeric array of floating point type.
package_version.py HTML None Sets package version.
theta.py HTML None Calculate potential temperature.
vapor_press.py HTML None Calculate vapor pressure.
virt_temp.py HTML None Calculate virtual temperature.
Module Name Pydoc Depend Function

[Back up top to the Introduction.]


Downloading and Installing the Package

Platforms

I've only tested atmqty on a GNU/Linux system, though it should work on any Unix platform that runs Python with Numpy.

Since I'm distributing the package as a gzipped tar file, if you're using Windows email me about getting the source code or download the modules one at a time from the module listing section above.

Dependencies

Almost all the routines in atmqty require Numerical Python (Numeric, MA). Make sure these packages are already in your system and that the directories they are in can be found in your sys.path. atmqty itself is written entirely in the Python language.

Downloading and Installing

First, get the following file:

Expansion of the tar file will create the directory atmqty-0.1. This directory contains the source code, the full documentation (HTML as well as images), a copy of the license, and example scripts.

To unzip and expand the tar file, execute at the command line:

gunzip atmqty-0.1.tar.gz
tar xvf atmqty-0.1.tar

There are a few ways you can install the package. For all these methods, first go into the atmqty-0.1 directory:

You can append entries to your path by:

import sys
sys.path.append('newpath')

Where 'newpath' is the full path of the location you're appending to your Python path. Thus, if the directory atmqty is in a directory /home/jlin/lib/python, 'newpath' is '/home/jlin/lib/python'. You can automate this by making the proper settings in a user customized .pythonrc.py file.

That's it!

Installing a Local Copy of the Documentation

The atmqty-0.1 directory contains a complete copy of the documentation for the package, including images. Keep this directory around (you can rename it) if you'd like to have a local copy of the documentation. The front page for all documentation is the doc/index.html file in atmqty-0.1. The most recent copy of the documentation is located online here.

[Back up top to the Introduction.]


Copyright and Licensing

Software License

Unless otherwise stated, the Python, Fortran, and/or C++ routines described on this page or which reference this page are copyright © 2003-2004 by Johnny Lin and constitute a library that is covered under the GNU Lesser General Public License (LGPL):

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA.

You can contact Johnny Lin at his email address or at the University of Chicago, Department of the Geophysical Sciences, 5734 S. Ellis Ave., Chicago, IL 60637, USA.

A copy of the GNU LGPL can be found here. Please note that these disclaimers of warranty supercede any implied or explicit warranties or claims found in the text of the routine source code themselves.

Documentation License

The referring web page is part of the documentation of the atmqty package and is copyright © 2003-2004 Johnny Lin. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license can be found here. The Transparent copy of this document is located at http://www.johnny-lin.com/py_pkgs/atmqty/doc/index.html.

[Back up top to the Introduction.]


Acknowledgements: Thanks to Dean Williams for the help! This work was carried out partially at the University of Chicago Climate Systems Center, funded by the National Science Foundation (NSF) Information Technology Research Program under grant ATM-0121028. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author and do not necessarily reflect the views of the NSF.

Return to Johnny Lin's Python Library.
Return to Johnny Lin's Home Page.

Valid HTML 4.01! Valid CSS! Updated: February 18, 2004 by Johnny Lin <email address>. License.