| | |
- stateset.StateSet(__builtin__.object)
-
- GenericModel
class GenericModel(stateset.StateSet) |
| |
A generic model.
This is the parent class for all models (thus all models are sub-
classes of GenericModel) and defines all methods and attributes
common to all models.
An object of this class is instantiated with a StateSet as input.
This class is just a StateSet class with a few extra methods added;
all StateSet methods and attributes exist and apply in GenericModel.
The StateSet must have a State object with an id attribute of "t0",
as it assumes that the "t0" State object is the state at the current
timestep, and that the model calculates starting from that point.
All container methods of this class assume that the StateSet data
is the data. Depending on what methods are applied, this StateSet
data is altered/augmented accordingly.
|
| |
- Method resolution order:
- GenericModel
- stateset.StateSet
- __builtin__.object
Methods defined here:
- __init__(self, input_StateSet)
- Instantiation method.
Method argument:
* input_StateSet: Input StateSet object.
In this instantiation method the two things that happen is that
all attributes in input_StateSet (listed in __dict__) become
attributes of this model, by reference, and the setup method is
executed.
- add_tend1(self, *args, **kwds)
- Adds args "tendency" objects to the model data container.
A call to this method is generally the final line in the user-
written overloaded tend1 method. Note the tend1 method can
have more than one call to this method, however.
Input Positional Argument(s):
* args: Field objects to add to the State object in the model
data container that has id "tend1". If such a State object
doesn't exist, the State is created. All the Field objects
in this list args should have unique ids; an exception is
thrown if not.
Input Keyword Argument:
* kwds: Dictionary of keyword arguments. Currently supports
a single keyword: mode. The mode keyword describes whether
the "tendency" object will be added to the model data contai-
ner by overwriting any previously existing "tendency" value
or summed to any previously existing "tendency" value. It
is a string with the following possible values:
+ "replace": Any previously existing "tendency" values in
the data container will be overwritten. This is the de-
fault value of mode in this method.
+ "sum_with_previous": Any previously existing "tendency"
values will be added to the value given in the input Field
object.
Most of the time the list of Field objects in args will be
local variables calculated in the tend1 method. For models
where all the tendencies in the tend1 method are calculated
by calling the tend1 methods of submodels, there will likely
be no locally calculated "tendencies" to add. In those cases,
there's nothing to add to the "tend1" State so add_tend1 will
be called with no arguments.
- asStateSet(self)
- Returns model attributes as a StateSet object by reference.
Only standard StateSet attributes (i.e. those that would be
initialized on instantiation) are part of the returned State-
Set object. Any additional attributes in the model object are
not returned.
- setup(self)
- Additional tasks to perform on object instantiation.
This method is executed upon object instantiation. Its default
behavior is to do nothing; i.e. here its a stub. Its use is in
subclasses of GenericModel where the method will be overloaded
and customized.
- step1(self)
- Integrate State one timestep forward.
If the "tend1" id State object does not exist in the model
data, method tend1 is called to calculate that "tendency".
The current State (i.e. with id attribute "t0") is then inte-
grated forward one timestep by adding the "tend1" id State
object to the "t0" State object to get a new State object
with id attribute "tp1", which is then added to the model
data. The "tend1" State object is deleted from the model
data. No other State objects in the model data are altered.
- step1_return(self)
- Integrate one timestep forward and set new timestep to t=0.
If the State object with id "tp1" does not exist, the method
calculates the state at the next timestep after "t0" (i.e.
"tp1"), shifts all State objects one timestep back, deletes
the earliest timestep, and deletes any timesteps later than
"t0". If the "tp1" object already exists, we assume that
object is the results of the integration and the integration
step is skipped. The rest of the method tasks are still com-
pleted, however.
Thus, after this method is executed, the State with id of "t0"
in the model data is the newly calculated timestep. The pur-
pose of this method is to put the model in a state ready to be
integrated another timestep.
- tend1(self)
- Calculate "tendency" for State for one timestep forward.
The "tendency" required to increment all time model calculated
prognostic variables in the current State (i.e. with id attri-
bute "t0") forward one time step is calculated. This new State
has id attribute "tend1"; only Fields that have an increment
are in this new "tend1" State object. The "tend1" State object
is added to the model container.
The "tendency" calculated here is actually the true tendency
multiplied by one timestep; thus it is the value to add to the
current state to increment one timestep forward. In other con-
texts what is called "'tendency'" here is referred to as "in-
crement".
The code structure of this method should include the following
and be in the following order:
(1) Calculate "tendency(ies)" as Field objects. These Field
objects should have attribute extra_meta.istend1=True.
(2) Add these Field objects to the model data container as a
State object with id "tend1" using the add_tend1 method.
This method call is generally the final line in the tend1
method.
The tend1 method is useful if you're only interested in the
"tendencies" or if you wish to calculate a number of "tenden-
cies" in the same time step with the same initial conditions
before completing the integration.
The use of this method is in subclasses of GenericModel where
this method will be overloaded and customized, as this method
is the meat of any model. In GenericModel, this method throws
a NotImplementedError exception, which enforces the require-
ment to overload the method.
Methods inherited from stateset.StateSet:
- __contains__(self, item)
- __delitem__(self, key)
- __getitem__(self, key)
- __iter__(self)
- Returns an iterkeys equivalent iterator over StateSet data.
- __len__(self)
- __setitem__(self, key, value)
- Method to add/rebind items.
Raises a KeyError exception if key is not equal to value.id.
- add(self, *args)
- Add/overwrite State objects given in args to StateSet object.
Positional Arguments:
* All arguments are State objects and are added to the StateSet
object self in the order they are given in the argument list.
If any of the arguments have id attributes equal to an exist-
ing key in self, the key is detached from its previous value
and associated with the new value given in the argument.
- clear(self)
- Clears all State objects in the StateSet object.
- copy(self)
- Returns deepcopy of StateSet object.
- copymeta(self)
- Returns deepcopy of StateSet object metadata.
The entire StateSet object is copied, except for the States
held in the StateSet container. Thus, the returned StateSet
object contains no data or State metadata, but rather only
StateSet metadata.
- del_earliest(self)
- Removes the earliest State object from StateSet container.
Earliest is defined in terms of relative timestep. Only non-
"tendency" State ids (i.e. those with prefix "tm", "tp", or
value of "t0") in the StateSet object are considered. All
other State ids, valid or not (e.g. "tendency" State ids like
"tend1") are ignored.
Examples of the Idea of How the Method Is Used and Works:
set = StateSet(s1, s2, s3)
set.keys() -> ['tp1', 't0', 'tm2']
set.del_earliest()
set.keys() -> ['tp1', 't0']
set = StateSet(s1, s2, s3)
set.keys() -> ['tend1', 't0', 'tm2']
set.del_earliest()
set.keys() -> ['tend1', 't0']
- del_latest(self)
- Removes the latest State object from StateSet container.
Latest is defined in terms of relative timestep. Only non-
"tendency" State ids (i.e. those with prefix "tm", "tp", or
value of "t0") in the StateSet object are considered. All
other State ids, valid or not (e.g. "tendency" State ids like
"tend1") are ignored.
Examples of the Idea of How the Method Is Used and Works:
set = StateSet(s1, s2, s3)
set.keys() -> ['tp1', 't0', 'tm2']
set.del_latest()
set.keys() -> ['tm2', 't0']
set = StateSet(s1, s2, s3)
set.keys() -> ['tend1', 't0', 'tm2']
set.del_latest()
set.keys() -> ['tend1', 'tm2']
- has_key(self, key)
- Returns True if State object of id key is in StateSet object.
- items(self)
- Returns copy of list of all State items in StateSet 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 State object ids in StateSet object.
The copy is a shallow copy (I think) and thus references to
other objects are not copied recursively.
- 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 objects
that make up this StateSet object pass 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 meta-
data that you wish to check this State variable's Field var-
iable'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 StateSet object.
This returns a reference to the private attribute _data, which
is a dictionary.
- setdata(self, data)
- Reference StateSet 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.
- shift_time_stateid(self, nstep)
- Shift State objects nstep timesteps; delete "tendencies".
The State objects in the StateSet container are all shifted
forward or backward the number of time steps given in nstep.
For example, if nstep=-1: the State object with id "t0" has
its id changed to "tm1" and the value of its time attribute
is decreased by delt; the State object with id "tm1" has its
id changed to "tm2", etc. "Tendency" State variables (e.g.
id with prefix "tend") are deleted from the StateSet, as are
State objects with None as key.
If either self.delt is None or the time attribute of a State
variable is None, the time attribute of that State variable
after the shift is set to None (if the time attribute does
not exist for that State variable pre-shift, it remains
undefined).
Positional Input Parameter:
* nstep: Number of timesteps to move all State objects for-
ward or backward. Integer. Required input, with no default
value.
Since shifting timesteps requires that all the timesteps in
the StateSet are consistent with one another, this method also
executes the time_ok() method on the post-shift States and
throws an exception if it returns False.
Example:
>>> from field import Field
>>> from state import State
>>> data1 = N.array([1.1, 3.0, -4.8, 2.9, 2.1])
>>> data2 = N.array([31.1, 0.4, 4.0, -4.9, 9.1])
>>> data3 = N.array([3.1, 2.4, 4.9, 8.1, -9.2])
>>> f1a = Field(data1, id='u', units='m/s')
>>> f2a = Field(data2, id='v', units='m/s')
>>> f3a = Field(data3, id='w', units='m/s')
>>> s1 = State(f3a, id='tend1')
>>> s2 = State(f1a, f2a, id='t0')
>>> s3 = State(f2a, id='tm1')
>>> s = StateSet(s1, s2, s3, id='velocities')
>>> s.keys()
['tm1', 'tend1', 't0']
>>> s.shift_time_stateid(-1)
>>> s.keys()
['tm1', 'tm2']
- sort_stateid(self)
- Returns a list of the State ids in time-ascending order.
Only non-"tendency" State ids (i.e. those with prefix "tm",
"tp", or value of "t0") in the StateSet object are sorted and
returned. All other State ids, valid or not (e.g. "tendency"
State ids like "tend1") are ignored.
Examples of the Idea of How the Method Is Used and Works:
set = StateSet(s1, s2, s3)
set.keys() -> ['tp1', 't0', 'tm2']
set.sort_stateid() -> ['tm2', 't0', 'tp1']
set = StateSet(s1, s2, s3, s4)
set.keys() -> ['tp1', 't0', 'tm2', 'tend1']
set.sort_stateid() -> ['tm2', 't0', 'tp1']
- state_list(self)
- Returns summary list of State objects in StateSet object.
A list of tuples is returned, each tuple describing one of the
State objects the StateSet object is a container for. Each
tuple holds the string values of the following State attributes,
in this form: (id, long_name). If either the id or long_name
attributes are empty, an empty string is returned.
Example of the Idea of How the Method Is Used and Works:
s1 = State(f1a, f2a, f3a, long_name='3-D_winds', id='t0')
s2 = State(f1b, f2b, long_name='2-D_winds')
st = StateSet(s1, s2, id='velocities')
st.state_list() -> [(None, '2-D_winds'), ('t0', '3-D_winds')]
- stateid2int(self)
- Returns list of non-"tendency" State ids as integers.
The source list of State ids is the keys in the present State-
Set object. In the returned list, "tm" ids are negative and
"tp" ids are positive. "t0" is 0. Any "tend*" terms in the
State id list are ignored. The returned list does not share
memory with the original keys list, but the order of the list
is the same as the input keys.
Example of the Idea of How the Method Is Used and Works:
set = StateSet(s1, s2, s3)
set.keys() -> ['tp1', 't0', 'tm2']
set.stateid2int() -> [1, 0, -2]
- time_ok(self)
- Returns True if passes consistency checks for time parameters.
Examines the time parameters for the StateSet container as well
as the constituent State objects to see that they are consis-
tent with each other. The StateSet container can only hold
non-"tendency" State objects (e.g. the presence of State ob-
jects with id prefixed by "tend" will throw an exception).
Method makes the following consistency checks:
- Each of the State variables have the same time_units (or un-
defined or equal to None).
- Values of time, delt, and id are consistent with each other.
If the "t0" State id does not exist, the "t0" object does
not have the time attribute (or it equals None), or the delt
attribute does not exist or equals None, this check is igno-
red and True is returned.
In the consistency checks, if an attribute is undefined or set
to None, the value is assumed to match any value. If no checks
are done, default of the method is to return True.
- values(self)
- Returns copy of list of all State objects in StateSet 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 State variables.
Runs through all State variables and executes the wrap method
for the State variable.
Data and other attributes inherited from stateset.StateSet:
- __dict__ = <dictproxy object>
- dictionary for instance variables (if defined)
- __weakref__ = <attribute '__weakref__' of 'StateSet' objects>
- list of weak references to the object (if defined)
| |