| | |
- AtmQty
class AtmQty |
| |
Atmospheric quantities in a latitude, longitude, level domain.
All attributes in this class that are "atmospheric quantities"
are assumed to be on the same latitude, longitude, level slab on
a spherical grid. Latitude and longitude are always given in
decimal degrees. The level coordinate can be different units
depending on the instantiation of the object. Methods operating
on this object are consistent with each other (i.e. equations
for all quantities are physically consistent) and thus all
quantities for a given instantiation of the object, for a given
set of initial state variables (added to the object by the class
method add_qty) are consistent with each other (assuming there
is no recalculation of already calculated values during that
instantiation of the object).
Usually latitude and longitude span the entire sphere, but this
is not required. Vertically the domain can encompass any number
of levels, with a minimum of one level. (Of course, certain
methods, such as centered differencing, that require a minimum
number of points, will not work if the number of points in the
domain is not large enough. The method will fail appropriately
in such cases.) However, the domain must be contiguous in all
three spatial dimensions.
This class allows one to define a missing value (self.missing).
All quantities that have this value are considered missing and
calculations done using those values will return a missing
value. Note that the same location may have missing value in
some quantities and not others; missing values do not have to
be co-located. This type of tracking of missing values is used
instead of masks to save memory; however, some use of the MA
module is made to help us temporarily manage missing values.
Note that since missing values are stored as self.missing, all
long-term storage of quantities and argument passing (in and
out) of quantities is through plain Numeric arrays, not MA
arrays.
Object Attributes (besides self.qty):
* self.const: Atmospheric constants. An instance of class
AtmConst in module atmconst.
* self.lat: Latitude [deg] vector for all "quantities". Mono-
tonically increasing.
* self.lon: Longitude [deg] vector for all "quantities". Mono-
tonically increasing.
* self.lev: Vertical level for all quantities. Level "type" is
given in self.lev_type. The units of lev depends on lev_type
(see description of self.lev_type for details). Monotonic,
either increasing or decreasing.
* self.lev_type: The level "type" given in dimension lev, and
which can have the following values:
+ "pressure": Vertical levels are in pressure coordinates
and lev is in units hPa (default value of lev_type).
+ "isentropic": Vertical levels are in isentropic (constant
potential temperature levels) coordinates and lev is in
units K.
* self.missing: Missing value value. Floating point scalar.
If undefined at object instantiation, is set to 1e+20.
* self.P_surf: Surface pressure [hPa]. Used to calculate
altitude. Either floating point scalar or a Numeric array
of shape (Numeric.size(self.lat), Numeric.size(self.lon)).
Has no missing values. Value is set to None on object
instantiation. The attribute value can be changed directly
or via the P_surf keyword in class method alt.
* self.p0: Reference pressure used to calculate potential
temperature [hPa]. Floating point scalar. If lev_type is
"isentropic," this is the reference pressure associated with
the isentropic levels and is set on object instantiation. If
lev_type is "pressure", this attribute is the reference pres-
sure used in calculating potential temperature; it is thus
undefined until potential temperature is calculated. In both
cases, this attribute should not be changed directly.
* self.qty_shape: The shape of all self.qty quantities. 3-
integer tuple (Numeric.size(self.lat), Numeric.size(self.lon),
Numeric.size(self.lev)). Defined on object instantiation.
* self.T_surf: Surface temperature [K]. Used to calculate
altitude. Either floating point scalar or a Numeric array
of shape (Numeric.size(self.lat), Numeric.size(self.lon)).
Has no missing values. Value is set to None on object
instantiation. The attribute value can be changed directly
or via the T_surf keyword in class method alt.
Quantities Data Structure Object Attribute:
* self.qty: Dictionary of quantities variables. All quan-
tities (but not boundary conditions), whether they are input
parameters or are calculated from input parameters, are stored
in this dictionary. Possible key values include:
+ 'alt': Geopotential altitude, based on 1976 U.S. Standard
Atmosphere [m]
+ 'e': Vapor pressure (with respect to over water) [hPa].
+ 'eice': Saturation vapor pressure over ice [hPa].
+ 'esat': Saturation vapor pressure over water [hPa].
+ 'fc': Coriolis parameter [1/s].
+ 'gpot': Geopotential height [m].
+ 'N2': Static stability (a.k.a. square of the buoyancy fre-
quency) [1/s**2].
+ 'p': Pressure [hPa].
+ 'pv': Potential vorticity [m^2 s^-1 K kg^-1].
+ 'q': Specific humidity [kg/kg]
+ 'r': Mixing ratio [kg/kg].
+ 'RH': Relative humidity (based on esat) [unitless fraction].
+ 'rho': Air density (including moisture effects).
+ 'T': Temperature [K].
+ 'theta': Potential temperature [K].
+ 'theta_e': Equivalent potential temperature [K].
+ 'T_v': Virtual temperature [K].
+ 'u': Zonal velocity [m/s].
+ 'v': Meridional velocity [m/s].
+ 'vort_rel': Relative vorticity [1/s].
Values corresponding to these keys are Numeric floating point
arrays, with a shape specified by self.qty_shape.
For details regarding attributes set on object instantiation,
particularly regarding which ones must be fixed for the life of
the instance, see the manual section on the AtmQty class (sub-
topic "Object Instantiation") at:
http://www.johnny-lin.com/py_pkgs/atmqty/doc/manual.html.
The class method add_qty adds variable(s) to the self.qty
dictionary. If a quantity is an input parameter state variable,
you have to use this method first to add the variable to self.qty
in order for it to be available for calculations. This is used
instead of requiring variables be in argument lists in class
methods, to simplify bookkeeping of what variables are defined
and what are not. Quantities are deleted from self.qty by the
class del_qty method. One can obtain a quantity from the
self.qty data structure with the get_qty method.
Note that depending on what lev_type is the quantities pressure
and potential temperature may be an input state variable or a
calculated derived variables. Also, because all state and
derived quantities are in self.qty, when an object method is
called to calculate a derived quantity, the only inputs that
are supplied in the method argument list are optional ones.
References Quoted in this Class Definition:
* Holton, J. R. (1992): An Introduction to Dynamic Meteorology,
3rd edition. San Diego, CA: Academic Press, 511 pp.
|
| |
Methods defined here:
- __init__(self, lat, lon, lev, lev_type='pressure', missing=1e+20, p0=None)
- Initialize basic class attributes.
Method Arguments:
* lat: Latitude [deg]. Numeric floating point vector.
* lon: Longitude [deg]. Numeric floating point vector.
* lev: Vertical level. Numeric floating point vector.
* lev_type: The level "type" given in dimension lev.
Scalar string.
* missing: Missing value value. Numeric floating point
scalar, if defined. Default is 1e+20.
* p0: Reference pressure [hPa]. Floating point scalar.
Details regarding arguments are in the docstring for the
class. Note initializing an object of this class requires
the gemath package.
- add_qty(self, *quantities)
- Add/replace variable(s) to quantities data structure.
Method Arguments:
* *quantities: Each argument is a dictionary with at least
one key:value pair where the key is the name of the variable
and the value is the variable. The key is a string scalar
and the value is a Numeric floating point array. See the
class docstring for details on possible values of the key
and additional conditions the value must meet. There can
be as many arguments as desired in the add_qty method call.
The method adds all the key:value pairs in all the arguments
to the self.qty quantities data structure of the object. If
self.qty already contains a term, this method replaces that
term's entry with the input argument value.
Method checks that each added quantity has the same shape as
attribute self.qty_shape.
Examples of syntax:
x = atmqty.AtmQty(lat, lon, lev, missing=1e29)
x.add_qty( {'e':e} )
x.add_qty( {'q':q}, {'T':T} )
x.add_qty( {'RH':RH, 'esat':esat, 'r':mix_ratio} )
- alt(self, P_surf=None, T_surf=None)
- Calculate geopotential altitude.
Method Arguments:
* P_surf: Surface pressure at latitude-longitude locations.
Either a Numeric array of shape tuple (Numeric.size(self.lat),
Numeric.size(self.lon)) or a scalar. Can have no missing
values. Default is None, which means the value of self.P_surf
is used. If self.P_surf is None, standard sea level pressure
is used at all locations.
* T_surf: Surface temperature at latitude-longitude locations.
Either a Numeric array of shape tuple (Numeric.size(self.lat),
Numeric.size(self.lon)) or a scalar. Can have no missing
values. Default is None, which means the value of self.T_surf
is used. If self.T_surf is None, standard sea level tempera-
ture is used at all locations.
Required Quantities in self.qty: p.
Method adds/recalculates geopotential altitude to the self.qty
quantities data structure (with key 'alt'), overwriting if the
term previously exists. If 'p' does not already exist, that
quantity is first calculated using the press method.
Method overwrites self.P_surf and self.T_surf with whatever
values are used in calculating altitude.
- del_qty(self, *quantities)
- Delete variable(s) from quantities data structure.
Method Arguments:
* *quantities: Each argument is a string scalar of the key
name of the variable in the quantities data structure.
See the class docstring for details on values of the variable
name. Note if this method is used to remove all entries in
self.qty, self.qty is not set to None but becomes an empty
dictionary.
- eice(self)
- Calculate saturation vapor pressure over ice.
Method Arguments: None.
Required Quantities in self.qty: T.
Method adds/recalculates saturation vapor pressure over ice
to the self.qty quantities data structure (with key 'eice'),
overwriting the term if it previously exists.
- esat(self)
- Calculate saturation vapor pressure over liquid water.
Method Arguments: None.
Required Quantities in self.qty: T.
Method adds/recalculates saturation vapor pressure over liquid
water to the self.qty quantities data structure (with key
'esat'), overwriting the term if it previously exists.
- fc(self)
- Calculate Coriolis parameter.
Method Arguments: None.
Required Quantities in self.qty: None.
Reference: Holton, p. 40.
Method adds/recalculates Coriolis parameter to the self.qty
quantities data structure (with key 'fc'), overwriting if the
term if it previously exists.
- get_qty(self, quantity)
- Get variable from quantities data structure.
Method Argument:
* quantity: String scalar of the key name of the variable
in the quantities data structure to obtain.
See the class docstring for details on values of the variable
name. Note this method does not remove the variable from the
quantities data structure.
- get_qty_asMA(self, quantity)
- Get variable from quantities data structure in MA form.
Method Argument:
* quantity: String scalar of the key name of the variable
in the quantities data structure to obtain.
The returned MA array is formed using the copy=0 flag in the
MA.masked_values function, and thus follows the rules of that
package regarding whether the return value is a reference or
a memory copy.
See the class docstring for details on values of the variable
name. Note this method does not remove the variable from the
quantities data structure, nor change the entry in self.qty to
MA form.
- has_qty(self, quantity)
- Check if quantities data structure has quantity.
Method Argument:
* quantity: String scalar of the key name of the variable
to check the quantities data structure for.
See the class docstring for details on values of the quantities
names. Returns 1 if quantities data structure self.qty has
quantity; 0 if not.
- ipv(self)
- Calculate isentropic potential vorticity.
Method Arguments: None.
Required Quantities in self.qty: fc, N2, rho, vort_rel
Method adds/recalculates isentropic potential vorticity to
self.qty (with key 'pv'), overwriting the term if it previ-
ously exists. If 'fc', 'N2', 'rho', and 'vort_rel' do not
already exist, this method first calculates these quantities
using the applicable methods. Algorithm used to calculate pv
is based on that used in the NCEP/NCAR reanalysis, with major
differences.
If lev_type is not isentropic level(s) and this method is
called an error is produced.
Reference:
* Iredell, Mark: "How does NCEP/NCAR reanalaysis compute the
potential vorticity on isentropic surfaces?" NCEP/NCAR Reanal-
ysis FAQ: http://dss.ucar.edu/pub/reanalysis/FAQ.html.
- isnew(self)
- Check if object is newly instantiated.
Method Arguments: None.
Checks whether the object is in a state consistent with being
a newly instantiated object (returns 1 if is in such a state
and 0 if not). "Newly instantiated" in this case means an
AtmQty object that is initialized solely from an argument
list, with no quantities added/deleted and attributes added/
deleted. Obviously, exhaustive tests cannot be done, but this
method checks a number of conditions consistent with such a
state.
- list_all_qty(self)
- List all quantities names in quantities data structure.
Method Arguments: None.
See the class docstring for details on values of the quantities
names.
- mix_ratio(self)
- Calculate mixing ratio.
Method Arguments: None.
Required Quantities in self.qty: p and e, or q.
Method adds/recalculates mixing ratio to the self.qty quan-
tities dictionary (with key 'r'), overwriting the term if it
previously exists. If 'q' does not already exist, then 'p'
and 'e' are checked to see if either already exist; if either
do not, this method first calculates each of them that do not
exist using the applicable method.
- press(self)
- Calculate pressure (from temperature, potential temperature).
Method Arguments: None
Required Quantities in self.qty: theta, T.
Method adds/recalculates pressure to the self.qty quantities
dictionary (with key 'p'), overwriting the term if it previous-
ly exists. If lev_type is pressure level(s) and this method is
called, an error is produced.
- rho(self)
- Calculate air density.
Method Arguments: None.
Required Quantities in self.qty: T_v, p.
Method adds/recalculates air density (including moisture
effects) to the self.qty quantities data structure (with key
'rho'), overwriting if the term previously exists. If 'T_v'
does not already exist, this method first calculates it using
the virt_temp method.
- static_stability(self)
- Calculate static stability.
Method Arguments: None.
Required Quantities in self.qty: T, alt.
Method adds/recalculates static stability to the self.qty
quantities dictionary (with key 'N2'), overwriting if the
term previously exists. If 'alt' does not already exist in
qty, this method first calculates 'alt' using the method alt
(with no keywords).
- theta(self, p0=1000.0)
- Calculate potential temperature.
Method Arguments:
* p0: Reference pressure [hPa]. Floating point scalar.
Optional (default set to 1000). Class attribute self.p0
is set to the value of this argument.
Required Quantities in self.qty: p, T.
Method adds/recalculates potential temperature to the
self.qty quantities data structure (with key 'theta'), over-
writing if the term if it previously exists. self.p0 is
set to the value of argument p0. If lev_type is isentropic
level(s) and this method is called, an error is produced.
- vapor_press(self)
- Calculate vapor pressure over liquid water.
Method Arguments: None.
Required Quantities in self.qty: p and r, q and r, or RH
and esat.
Method adds/recalculates vapor pressure to the self.qty quan-
tities data structure (with key 'e'), overwriting the term if
it previously exists. If 'esat' does not already exist in qty
(and 'RH' exists, and 'r' and 'q' both do not exist), this
method first calculates 'esat' using the method esat. If 'r'
does not exist in qty, and 'RH' does not exist, this method
first calculates 'r' using the method mix_ratio.
- virt_temp(self)
- Calculate vapor pressure over liquid water.
Method Arguments: None.
Required Quantities in self.qty: r, T.
Method adds/recalculates virtual temperature to the self.qty
quantities data structure (with key 'T_v'), overwriting if the
term previously exists. If 'r' does not already exist in
self.qty, this method first calculates it using the method
mix_ratio.
- vort_rel(self)
- Calculate relative vorticity.
Method Arguments: None.
Required Quantities in self.qty: alt, u, v.
Method adds/recalculates relative vorticity to the self.qty
quantities data structure (with key 'vort_rel'), overwriting
if the term previously exists. The 'default_spherical' al-
gorithm from gemath.curl_2d is used. If 'alt' does not al-
ready exist in qty, this method first calculates 'alt' using
the method alt (with no keywords). Method assumes we're on
the Earth and that the mean radius of the earth coincides
with an atmospheric altitude of 0.
Note that if quantity 'alt' contains any missing values, for
the purposes of this current method only, the altitude at
those missing value locations is set to 0.
| |