| | |
- __builtin__.object
-
- State
class State(__builtin__.object) |
| |
Collection of Field objects at one time.
The State class is a container that is a collection of Field class
objects at the same instance in time or time "tendency" (actually
the time differential multiplied by one time step, i.e. the amount
to add to a current variable in order to obtain the variable one
timestep later). The State keys for mapping the Field objects are
the id attributes in the Field objects; the keys in a State object
are unique.
Public Instance Attributes:
* id: This identifier contains information about whether the con-
stituent Fields are full variables (i.e. not a "tendency") or
"tendencies" and the relative time the State is at. The follow-
ing values are possible:
"tm1": Full variable at time equals 0 minus one timestep.
"t0": Full variable at time equals 0.
"tp1": Full variable at time equals 0 plus one timestep.
"tend1": Value to add to a "t0" State object to obtain a
"tp1" State object. Taken to be at the same time
as id "t0".
The number after "m" or "p" can be values other than "1", and
denote the number of timesteps added to or subtracted from time
0. String. Default is None.
* long_name: Description of the object, containing information
about the collection of Field objects. Default is None.
* time: Time of the State. Floating or integer. In units of
attribute time_units. Default is None.
* time_units: Units of the attribute time. String. Default is
None.
All the instance attributes can be set directly or via keywords
passed in the instantiation parameter list. See the __init__
function docstring for details.
Example:
>>> from field import Field
>>> data1 = [1.1, 3.0, -4.8, 2.9, 2.1]
>>> data2 = [31.1, 0.4, 4.0, -4.9, 9.1]
>>> data3 = [3.1, 2.4, 4.9, 8.1, -9.2]
>>> f1 = Field(data1, id='u', units='m/s', axis=['Latitude'])
>>> f2 = Field(data2, id='v', units='m/s', axis=['Latitude'])
>>> f3 = Field(data3, id='w', units='m/s', axis=['Latitude'])
>>> s = State(f1, f2, f3, long_name='winds', id='t0')
>>> print s.id
t0
>>> print s.long_name
winds
>>> print s.time
None
>>> print s.keys()
['u', 'w', 'v']
>>> print type(s['u'])
<class 'field.Field'>
>>> print s['v'].id
v
>>> ['%.6g' % s['v'][i] for i in range(len(s['v']))]
['31.1', '0.4', '4', '-4.9', '9.1']
|
| |
Methods defined here:
- __contains__(self, item)
- __delitem__(self, key)
- __getitem__(self, key)
- __init__(self, *args, **kwds)
- Initialize class object.
Positional Arguments:
* All arguments of this initialization function are assumed to
be Field objects which are put into the container's data
structure, private attribute _data. If any of the arguments
have the same id attribute, only the last Field object in the
argument list with that id will be stored; the rest will be
ignored.
Keyword Arguments:
* All keywords are attributes of the instance. Any other key-
words in the calling line are ignored. See the class doc-
string for details.
The private variable _data is the data structure that holds
all the Fields. The keys to _data (accessible via the public
method keys) are the Field.id attributes and the values of
_data (accessible via the public function values) are Field
objects.
- __iter__(self)
- Returns an iterkeys equivalent iterator over State data.
- __len__(self)
- __setitem__(self, key, value)
- add(self, *args)
- Add/overwrite Field objects given in args to State object.
Field objects specified in arguments are added by reference,
not by copy.
Positional Arguments:
* All arguments are Field objects and are added to the State
object self in the order they are given in the argument list.
The list of arguments should have unique id attributes; an
exception is thrown if this is not true. If self already has
a Field object with the same id as an object in args, the
object in args replaces the object in self.
- clear(self)
- Clears all Field objects in the State object.
- copy(self)
- Returns deepcopy of State object.
- copymeta(self)
- Returns deepcopy of State object metadata.
The entire State object is copied, except for the Field data
held in the State container. Thus, the returned State object
contains no Field object data, just State metadata.
- copysubset(self, keylist)
- Returns copy of a subset of the State object.
Returns a new State object that consists of only those Field
variables that have a key given in keylist. All contents of
the new State object (including Field data) are deep copies
of the elements of the original State object.
Positional input argument:
* keylist: A list or tuple of keys (or a single scalar key)
that specify the Field objects to include in the returned
State object. The values of these keys are equivalent to
the id attribute of the Field objects.
If any of the Field keys in keylist do not exist in self, a
KeyError exception is thrown.
- has_key(self, key)
- Returns True if Field object of id key is in State object.
- is_conformable(self, ignore=None, include=None)
- Returns True if all Field objects are conformable.
Method examines the shape of each Field object in the State
object and returns True if all Field objects are conformable.
The Field objects are conformable if their data arrays all
have the same shape. Scalars and one-element array Field
objects are assumed to be conformable to any sized array.
Field objects that are axes (i.e. extra_meta.isaxis is True)
are not compared.
Note: Part of the conformability test uses the Numeric/
numarray function allclose on array shapes. If the allclose
test returns False or throws an exception for any reason (not
just ValueError, which occurs for different shapes), this
method returns False.
Keyword Input Parameters:
* ignore: A list of Field ids of Field objects in the State
object to ignore in making the conformability test (if the
id does not exist in the State object, there's nothing to
ignore and the check continues on). These Field objects
are not modified in any way in the State object. Default
is None.
* include: A list of Field objects to include as being a
part of the State object for the purposes of making the
conformability test. These Field objects are assumed to
not be a part of the State object, nor are they added into
the State object. The include objects can have ids that
are the same as Field objects in the State object. In
those cases, this method uses the include objects instead
of the same-named objects in State. Default is None.
Examples:
>>> data1 = N.array([1.1, 3.0, -4.8, 2.9, 2.1])
>>> data2 = N.array([[31.1, 0.4], [4.0, -4.9]])
>>> data3 = N.array([[-1.1, 3.4], [9.0, -8.2]])
>>> f1 = field.Field(data1, id='Ts', units='K')
>>> f2 = field.Field(data2, id='u', units='m/s')
>>> f3 = field.Field(data3, id='v', units='m/s')
>>> s = State(f1, f2, id='t0')
>>> print s.is_conformable()
False
>>> f1 = field.Field(1.1, id='Ts', units='K')
>>> s.add(f1)
>>> print s.is_conformable()
True
>>> print s.is_conformable(include=[f3])
True
>>> f1 = field.Field(data1, id='Ts', units='K')
>>> s.add(f1, f3)
>>> print s.is_conformable(ignore=['Ts'])
True
- items(self)
- Returns copy of list of all Field items in State object.
The copy is a shallow copy (I think) and thus references to
other objects are not copied recursively.
- keys(self)
- Returns copy of list of all Field object ids in State object.
The copy is a shallow copy (I think) and thus references to
other objects are not copied recursively.
- max_shape(self)
- Returns shape of array needed to hold all non-axis Fields.
Method examines the shape of each Field object in the State
object (for which extra_meta.isaxis != True) and creates a
tuple that has the number of dimensions of the largest Field
object data array. Each dimension in this returned shape
tuple is the maximum size of all non-axis Field objects for
that dimension. If every Field object in the State object is
has extra_meta.isaxis == True, an empty tuple is returned.
Example:
>>> data1 = N.array([1.1, 3.0, -4.8, 2.9, 2.1])
>>> data2 = N.array([[31.1, 0.4], [4.0, -4.9]])
>>> f1 = field.Field(data1, id='Ts', units='K')
>>> f2 = field.Field(data2, id='v', units='m/s')
>>> s = State(f1, f2, id='t0')
>>> print s.max_shape()
(5, 2)
- meta_ok_to_interface(self, IMobj, check_long_name=False)
- Returns True if metadata passes checks for interfaces.
Tests whether the Field objects metadata in the State object
passes consistency checks in accordance with the description
given in InterfaceMeta object IMobj. If all the Field objects
pass, this method returns True. See the docstring for the
Field class for details as to what the consistency checks
entail.
Positional Input Argument:
* IMobj: InterfaceMeta object that defines the accepted
metadata that you wish to check this State variable's
Field variable's metadata against. For details see:
http://geosci.uchicago.edu/csc/modelutil/doc/imeta.html
Keyword Input Arguments:
* check_long_name: If set to True, the method not only
checks units but also long_name. Default is False.
- refdata(self)
- Returns reference to data of State object.
This returns a reference to the private attribute _data, which
is a dictionary.
- setdata(self, data)
- Reference State private _data attribute to data.
This makes a reference of data to the private attribute _data,
which is a dictionary. Thus, argument data must be a diction-
ary.
- subset(self, keylist)
- Reference a subset of the State object.
Returns a new State object that consists of only those Field
variables that have a key given in keylist. Though the State
object is new, the Field objects it holds are references (not
copies) to the corresponding Field objects held in the origin-
al State object container. Other attributes in the returned
State object are a deep copy of the elements in the original
State object.
Positional input argument:
* keylist: A list or tuple of keys (or a single scalar key)
that specify the Field objects to include in the returned
State object. The values of these keys are equivalent to
the id attribute of the Field objects.
If any of the Field keys in keylist do not exist in self, a
KeyError exception is thrown.
- values(self)
- Returns copy of list of all Field objects in State object.
The copy is a shallow copy (I think) and thus references to
other objects are not copied recursively.
- wrap(self)
- Connect the MPI parallel subdomains of all Field variables.
Runs through all Field variables in the State variable and ex-
ecutes the wrap method for each Field.
Data and other attributes defined here:
- __dict__ = <dictproxy object>
- dictionary for instance variables (if defined)
- __weakref__ = <attribute '__weakref__' of 'State' objects>
- list of weak references to the object (if defined)
| |