atmqty Manual: AtmQty Overview

The AtmQty class manages the calculation of self-consistent atmospheric quantities on a 3-D latitude, longitude, level grid on the sphere. In this overview we provide a concise description of using the class.

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 vectors describing 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"). In this example we assume the vertical coordinate is pressure levels (which is the default lev_type):

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

NB: Once an AtmQty object is instantiated, domain-describing attributes must be fixed for the life of that instance. See the manual discussion of instantiation for details (particularly regarding instances when lev_type = "isentropic"). The summary of object attributes also provides additional information.

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. (Here is an example of the shape of this pattern.) We make a few of the elements in temperature near the South Pole be "missing," and add extra "shallow" dimension to represent the single level, so the array is rank 3, not 2. The add_qty method adds the temperature and humidity to a quantities data structure in the object:

>>> 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 atmospheric quantities managed by the object, whether they are input values or are calculated, are in the attribute qty. Thus, in the above example, the data structure of atmospheric quantities is x.qty. Each quantity in qty has shape qty_shape (a 3-element integer tuple given by the sizes of attributes lat, lon, lev), and is an array spanning the space given by that tuple. Thus, quantity slices [0,:,0] in the above example are the points at 90 S, 850 hPa, over all longitudes.

Now we can use the object to calculate quantities derivative from temperature and specific humidity. The theta method, for instance, calculates potential temperature:

>>> x.theta()

and the resulting potential temperature is stored in attribute x.qty. You can get the values stored in qty with the get_qty method. (A list of the names of all quantities currently reserved is here.) So, if we want to set the potential temperature to a separate variable (say T_pot), type:

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

The method get_qty_asMA does the same thing as get_qty, but returns an MA masked array of the quantity. This is handy for plotting and other functions that often utilize masked arrays.

Don't forget that Python assignments do not copy data but rather create only a reference. To get a separate copy of the data, use the copy method in the module copy:

>>> import copy
>>> T_pot_separate = copy.copy( x.get_qty('theta') )

Note that the order in which you calculate quantities matters. For instance, method static_stability requires altitude already exists; unless it has been added to the quantities data structure, the method alt must be called before static_stability. In many (if not most) cases, quantity calculation methods in the AtmQty object automatically calculate dependencies, as needed, if they don't yet exist (for instance, in the static_stability example above). See the docstring description of the available object methods for a list of their dependencies and when those dependencies are automatically resolved.

There are two broad types of object methods: methods related to object management (e.g. information about the qty data structure, the state of the object, etc.) and methods for calculating atmospheric quantities. These are described in summary lists of the object management methods and the quantity calculation methods.

All atmospheric quantities calculated by using package atmqty's procedural functions are calculated by methods in class AtmQty, but the reverse isn't true; class AtmQty calculates some quantities for which there are no equivalent procedural functions. This is because calculating some quantities (e.g. isentropic potential vorticity) requires exactly the type of manipulation that AtmQty exists to provide; it doesn't make sense to write a procedural function to perform those tasks already more robustly formulated in AtmQty's object-oriented structure.

Finally, you can transform one AtmQty object into an AtmQty describing another domain. The following command:

>>> xnew = atmqty.transform_AQobj.transform_AQobj(x, y)

creates a completely separate AtmQty object xnew (with no shared data) which is filled with the same quantities and attributes of x, but interpolated onto the domain specified by y. Objects x and y are unchanged. This is particularly useful for interpolating quantities from pressure coordinates to isentropic coordinates.