|
Release Notes
| |
Module History
NeverSampled is a large negative integer used as the value of a tag's
attribute cycle_last_sampled if the tag has not been sampled yet.
collector is an instance of class HistoryCollector, and is the default
value of the third argument in the creation of instances of Tag.
__version__ is a string giving the current version number for the
history package as a whole.
The tag is the basic quantity you use. Typically you do not create a tag directly but
rather use one of the functions that creates tags. There are four such functions supplied
in the history module:
textfile_tag (tagname, filename = '', col = collector)
If the filename is not given, it will be history_xxx.txt, where xxx is the
value of the tag name tagname. This function returns a new instance of Tag whose
medium is an instance of history_medium.Textfile. The tag is registered with the instance
of HistoryCollector supplied as the argument col.
columnarfile_tag (tagname, filename='', col = collector)
If the filename is not given, it will be history_xxx.txt, where xxx is the
value of the tag name tagname. This function returns a new instance of Tag whose
medium is an instance of history_medium.ColumnarFile. The tag is registered with the
instance of HistoryCollector supplied as the argument col.
memory_tag (tagname)
This histories collected by this tag are stored in memory. They are accessible using
method history(name).
event_tag (tagname, action, context = "__main__",
col=collector)
This function returns an instance of Tag that uses a medium that does not actually
write anything. One item is created and added to this tag. The item is an item using the
string "action" and the context given. The net effect of all this is that the
action will be evaluated in the context at the desired times.
Additionally, other files defining heirs of HistoryMedium will usually supply some
similar function for creating a Tag with the given medium, such as the pdb_history
module's PDBfile_tag function.
A tag is a group of items that should be sampled at the same times and those samples
written out to a history medium, such as a text file. Each tag has a name, a medium, and a
list of items to be sampled. Each item in turn consists of three things:
- A name for the history on the medium. The medium in turn may find it necessary to modify
the name supplied in order to make it legal for that medium; that name is called the
external name. Usually, the external name is the same as the name.
- A string, called the definition of the item. This string should be a legal Python expression
(not a Python statement, such as a print statement).
- A context in which the symbols in the string can be evaluated. A context can be
specified in three ways: a dictionary, the name of a module, or the module object itself.
When it is time to sample the item, the history collector will write the value of the
string to the medium using the context as the global context in which to evaluate the
definition string.
Tags have names so that they may be registered with their collector by name. Then, even
if you do not have a reference to the tag, you can get one from the collector. Also, you
can use the tag names to change the order in which different tags are processed, or to
delete the tag from the collector.
Creation
Tag(self, name, medium, collect = collector)
A tag with the given name, medium, is created and registered with its collector under
that name. (A tag can only be registered with one collector.) After creation, the tag
contains the attributes listed below.
A medium is an instance of a class conforming to history_medium.HistoryMedium. Some
popular media are: text files, columnar text files, memory, Pact/PDB files, and one called
Event which actually just throws the values away. Some of these media are defined in the
module history_medium, while others are in other modules, inheriting HistoryMedium and
replacing some of the methods to implement the new medium.
A collector is an instance of class history_collector.HistoryCollector. This is the
"clock" that you use to drive the entire package by calling its routine
sample (cycle, time) at the completion of each "time step" in your
calculation. Usually the default collector, the instance collector in this module, is
used. The only reason to create another one is if you have two entirely separate
"clocks" in your program.
Attributes
None of these attributes should be directly assigned by the user. Please use the
methods provided, only.
name is the name of the tag (read-only).
medium is an instance of class conforming to HistoryMedium
(read-only).
cycle_last_sampled is the integer cycle number at which the last
sample was taken. Initial value is NeverSampled (read-only).
sample_count is the integer number of times the tag has been sampled
(read-only).
condition is an instance of a class conforming to
history_condtion.HistoryCondition. (See sample, sample_final). The
default value, set at creation time, is a condtion which is always true, resulting in a
sampling at every cycle. See below for methods to use to change this.
logical_condition is an instance of a class conforming to
history_condition.HistoryCondition. See below for methods to use to change this.
Query Methods
itemnames () returns a list of the names of the items in this tag.
get_item (name) returns the item named name, or None if there
isn't one.
failing () returns a list of items which presently cause an exception
if sampled. Care should be taken in calling failing () if any item in the tag has a
definition that creates a side-effect when evaluated. Note that an item may fail because
some symbol in it is not yet defined, or has a value that is not yet appropriate. Thus, an
item may fail in this test even though in fact it is going to work correctly when the
program is run further.
history (name) returns the history stored under the given name. A
given tag may or my not support this method. This method cannot be called when the medium
is open (that is, when you are in the middle of sampling). Currently, only memory tags
support this method.
Methods to Set the Sampling Schedule
Each tag is governed by a condition. Usually, you set the condition by using one of the
variety of methods below. For advanced use, each condition must be an instance of a class
conforming to history_condition.HistoryCondition. You can create an instance of a
condition yourself and use method
set_condition (condition)
to install it in a tag.
frequency (start, stop, freq) sets the sampling condition to
sample every freq units between start and stop, inclusive. If all arguments are of integer
type, the condition is considered to be one on cycles; if any argument is a float, the
condition is one on time.
at_times (*times) takes one or more times as a list of
discrete times at which to sample. The list need not be sorted.
at_cycles (*cycles) similarly takes one or more specific
cycles at which to sample.
The logical condition, if set to a value other than None, must be a condition to be
used to govern whether or not sampling is attempted. If the logical condition is set but
not true, no sample will be collected, despite the value of the regular condition. The
logical condition may be set directly with
set_logical_condition (condition)
but it is more usual to set it with method when:
when ("expression") sets the logical condition to
When (expression). A second, optional argument can be given to specify a context, which
defaults to the global variables of the __main__ module.
Methods to Create Items
item (name, definition = None, context="__main__")
adds an item named name with the given name, definition, and context.
The string definition is the string to be evaluated, which defaults to name.
item_static (name, value = None, context="__main__")
adds an item to the tag in a similar way. The difference is that a static tag is
sampled only at the first sample time. This is useful for adding time-invariant values to
the file.
Methods to Sample
Normally, the user does not invoke these routines directly, but rather by calling the
identical methods in class HistoryCollector, usually on the standard collector.
sample (cycle, time) checks the state
attribute of the logical condition. If it is true, and the state attribute of the
regular condition is satisfied, the sample is collected. The user's sequence of calls to
sample should have successive integer values of cycle and monotonically increasing values
of time. The initial value of cycle may be anything you like as long as it is larger than
NeverCollected.
If your program has a repetitive cycle but no concept of time, you can simply use the
floating-point version of the cycle number as a time.
sample_final (cycle, time) may be called at the
final time of the program. It will example the state_final attributes of its
conditions rather than the normal state attribute. (See module
history_condition). These state_final attributes have been chosen for the time and cycle
conditions so that they are true unless the last possible time has already passed.
sample_unconditionally (cycle, time) does exactly
what it says. The logical and regular conditions are ignored. It is not intended for
normal use by the user.
The method sample_final may be called without worry about duplication of
records that may have already been made by a previous call to sample on that same
cycle.
Media Defined In Module History
Four media are defined in module history. These four classes correspond to the four
tag-creating functions defined above, and are called TextFile, ColumnarFile,
Memory, and Event. These are defined in module history
for the user's convenience. PACT/PDB files are available in module pdb_history.
The Memory tag supports the method history(name) for examining the
history. The other media create files to hold the histories.
How to create new history media, is described in module "history_medium".
|
