See the Release Notes for the latest changes. This document describes version 2.0, which will be released shortly. The tutorial has not yet been updated to this version.
Many programs consist of a set of steps that can be thought of as representing the evolution of the calculation in time. PyHistory is a Python language facility enabling the user of a Python program to create a series of samples, at different times, of the values of Python expressions. Such a series is called the history of the expression, and each expression whose history is to be taken is called an item. The simplest item can be thought of as the name of a variable whose values are to be collected.
The user may choose a particular medium in which the history will be collected. Five interesting media that are provided are:
A tag is a group of items which are to be stored in a particular medium, and sampled at the same times. A tag is the basic unit that the user deals with, and in fact most users will deal mostly with the interface of class Tag. A tag contains:
A user creates one or more tags, usually via a function that creates the tag with a certain medium. Then, the user adds items to each tag and sets the frequency of collection and possibly the logical condition desired for that tag. Finally, the program calls the sample method of the standard collector object at the end of each time step, and the sample_final method at the end of the calculation.
In this example, a single tag named tag1 is created that will be stored in a text file. (Since the file name is not specified, textfile_tag calculates it as history_tag1.txt.) The tag has two items named "x" and "y" and will be sampled every 5 cycles beginning at cycle 10 and ending at cycle 50 (inclusive). However, samples will only be taken if the expression "x > 1.4" is true. An additional time-invariant item "s" will be collected only once at the first opportunity.
from history import * mytag = textfile_tag ("tag1") mytag.item ("x") mytag.item ("y", "x*x") mytag.item_static ("s", "'hello world'") mytag.frequency (10, 50, 5) mytag.when ("x > 1.4")
for i in range (100): x = .2 * i time = i/10. cycle = i collector.sample (cycle, time) collector.sample_final (cycle, time)
You may never need to go beyond the interface shown here. However, if necessary you can create new media, create complicated conditions governing the collection of tags, and use the package to call functions rather than collect items.
To use Pact/PDB files in this example, rather than a text file, we would simply change the first two lines to:
from pdb_history import * mytag = PDBfile_tag ("tag1")
LLNL's set of Python extensions is available at no cost. The package, including this documentation, has been released for free redistribution by the Regents of the University of California. Please see the legal notices in the source files for details.
To obtain PyHistory, ftp://ftp-icf.llnl.gov/pub/python/LLNLDistribution.tgz. Unzip and untar it to get a directory tree rooted at LLNLDistribution. PyHistory is a subdirectory of this directory.
PyHistory itself contains only Python source files. There is no C extension to build. To add the PyHistory package to your program, place its Python source files somewhere in the search path of the application. They can be added to the python lib directory, for example.
If you wish to use pdb_history.py, you must install the PyPactPDB package and PACT. This is explained in the PyPactPDB documentation.
The history package itself consists of these modules:
In addition there are modules defining optional media:
Each of the modules contains a test routine, and there are several stand-alone test routines.
Reading the section PyHistory -- A More Elaborate Example is the best way to learn to use PyHistory. If you decide to use the PactPDB modules, you will need to read the documentation for PyPactPDB to learn how to read the files it produces with Python, PDBView, or Yorick. (See the module PR.py in PyPactPDB). There is also a tutorial set of viewgraphs available. (Acrobat 3 Format).
Please see the Legal Disclaimer.
UCRL-12859, Part 3