`atmqty`

Manual: `AtmQty`

OverviewThe `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`

):

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, missing=1e+29)

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