Home Up History Media Collector Condition Item


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.

Tag-creating Functions

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.

Class Tag

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:

  1. 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.
  2. 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).
  3. 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.


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.


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.

Extending The HistoryPackage

How to create new history media, is described in module "history_medium".