atmqty: A Python Package for Calculating Atmospheric Quantities

Introduction

This package contains methods to calculate atmospheric quantities (on the Earth) 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. The current version is 0.2.0.2.

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. This package has not been developed/maintained since 2004. It's published for historical and educational purposes only. I would not recommend you to use it for your own work as is.

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

Web site index:


Package Description

Overview

There are three ways of using this package: (1) for its central definition of atmospheric constants, (2) as a suite of procedures to calculate selected atmospheric quantities using Numeric arrays as input, and (3) for the AtmQty object, which manages the calculation of a self-consistent set of atmospheric quantities.

Here we provide a brief summary of using the package. Further description is in the reference manual.

Atmospheric Constants: The AtmConst class provides a comprehensive (someday) and consistent definition of important atmospheric constants. Constants are defined both as class attributes and also as instance attributes whose initial values are set by the class attribute version. This "double-definition" enables one to make local changes to local instances of the AtmConst class without having the changes propagate to all subsequent references. At the same time, you can change the value in all subsequent references, if you wish, by altering and using the class attribute definition.

The AtmConst class is found in the atmconst module in the package. Here is an example of accessing the gas constant for dry air, both as a class attribute and an instance attribute:

>>> from atmqty.atmconst import AtmConst
>>> AtmConst.R_d
287.05000000000001
>>> 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, and also gives more information about the difference in using the class and instance attributes.

Procedural Functions: You can use this package for its "procedural functions" (i.e. functions to be used procedurally) that calculate "atmospheric quantities" (quantities that are "directly derivative," i.e. not requiring time integration or modeling, from standard state variables). These procedures are invoked by function call and accept state variable Numeric arrays as input. A summary list of all such procedural functions is here. Each such procedural function is a public function in a module of the same name.

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])
>>> a = theta(p, T)
>>> a
[ 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.

Given vectors describing the latitude (lat), longitude (lon), and pressure level (lev) values of our domain, defining the AtmQty object is as easy as:

>>> import atmqty
>>> x = atmqty.AtmQty(lat, lon, lev, missing=1e+29)

The AtmQty class can handle missing values. As default, the class assumes missing values are set to 1e+20. In this example, missing values will have the value 1e+29.

All atmospheric quantities (e.g. state variables, derived state variables) are stored in the data structure attribute qty. All quantities in qty are rank 3 arrays spanning the (lat, lon, lev) space. (The first array index describes latitude, the second longitude, the third level.) If we have such an array T of temperature that we want to add to the quantities data structure, we type:

>>> x.add_qty({'T':T})

To calculate derived quantities, we use methods built into the AtmQty object. The theta method, for instance, calculates potential temperature:

>>> x.theta()

and the resulting potential temperature is stored in attribute x.qty with a predefined name. (A list of the names of all quantities currently reserved is here.) Methods to calculate a whole host of quantities exist, including: saturation vapor pressure, mixing ratio, density, static stability. A list of all methods to calculate quantities is here.

To retrieve and set (by reference) the potential temperature to a separate variable:

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

You can also transform one AtmQty object into another AtmQty describing another domain using the transform_AQobj function.

Please read this concise yet complete overview of the key features of the AtmQty class; it'll gives you what you really need to know. Details regarding the AtmQty class are found in the reference manual.

Importing the Package

As with all Python packages, import statements that specify the full package/module name will import the appropriate module. Thus, to import the module eice, which contains one public function eice, the statement:

import atmqty.eice

will enable you to use the function eice with the full import name specified, for instance:

press = atmqty.eice.eice(T)

Using from ... import ... allows you to use a function without including the package/module name:

from atmqty.eice import eice
press = eice(T)

What is different in this package, however, is that the __init__ file for the package contains import statements for all submodules. Thus, when you import the package (i.e. import atmqty) or a submodule within it (e.g. import atmqty.eice) you automatically import all submodules and the functions defined in them into the namespace. As a result: 

import atmqty
press = atmqty.eice.eice(T)

will work, as will: 

import atmqty as A
press = A.eice.eice(T)

and even this: 

import atmqty.eice
pot_temp = atmqty.theta.theta(p, T)

Summary of Bug Fixes, Updates, and Version History

A summary list of bugs and fixes, updates to the package, and a summary of the version history (with links to gzipped tar files of previous releases of the package) is found here.

[Back up top to the Introduction.]


Help and Examples

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

Summary sheets for this package:

Example web pages of using atmqty functions:

The reference manual has many more details regarding the structure and use of this package.

[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 page.

Dependencies

Python: atmqty has been tested on and works on v2.2.2 and 2.3.3.

Full functionality of atmqty requires the following packages and modules be installed on your system and findable via your sys.path:

cdms is the core package to the Climate Data Analysis Tools (CDAT). sphere is a contributed package to CDAT. Numeric and MA are part of the Numerical Python (Numpy) package. gemath is distributed by myself.

Installation of Numpy and gemath is trivial. Installation of CDAT (both core and contributed packages), on the other hand, is more difficult (see their web site for details). However, a significant portion of atmqty functionality only requires Numpy and gemath. See the module list for information regarding dependencies for each module.

Package 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.2.0.2. 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.2.0.2.tar.gz
tar xvf atmqty-0.2.0.2.tar

There are a few ways you can install the package. For all these methods, first go into the atmqty-0.2.0.2 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.2.0.2 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.2.0.2. 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 Rodrigo Caballero, Christian Dieterich, Mike Fiorino, Martin Juckes, Ag Stephens, and Dean Williams for 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: July 16, 2004 by Johnny Lin <email address>. License.