atmqty
: A Python Package for
Calculating Atmospheric Quantities
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:
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'
):
Note that the
>>> 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)
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:
All quantities managed by the object, whether they are input values or are calculated, are in the object attribute
>>> 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} )
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:
The potential temperature is now calculated and stored in the object's quantities dictionary
>>> x.theta()
x.qty
. If we want
to set the potential temperature to a separate variable (say
T_pot
, we can use the get_qty
method:
or directly access the potential temperature entry in the
>>> T_pot = x.get_qty('theta')
x.qty
dictionary:
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
>>> T_pot = x.qty['theta']
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:
AtmQty
atmospheric quantities object into another, which gives a
straightforward way of interpolating quantities from one grid
to another, or averaging along an axis (e.g. zonally) to
effectively reduce the object in dimension.
A summary list of bugs and updates to the package is found here.
The module listing section below includes
pydoc generated
documentation of the modules in the package. The Python
interactive help
method provides similar
functionality:
help(atmqty)
:
Help for the package (including the AtmQty
class).
A list of all modules in this package is found in the
"Package Contents" section of the help output.
help(atmqty.M)
:
Details of each module "M", where "M" is the module's name.
[Back up top to the Introduction.]
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.]
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.
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.
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:
This will install the package
python setup.py install
atmqty
in the
default site-packages directory in your default Python.
You'll probably need administrator privileges,
however, in order to do this install.
This will install the package
python setup.py install --home=~
atmqty
in the
directory ~/lib/python/atmqty
(where ~ means your home directory).
However, you'll need to make sure ~/lib/python is on your path.
import atmqty
command only looks for a
directory named atmqty on your Python path and executes
the __init__.py file in it. Of course, you'll have to
make sure the directory atmqty is in is on your path.
Where
import sys
sys.path.append('newpath')
'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!
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.]
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):
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.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.
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.