Condition

Module "history_condition"

Class Condition

An instance of Condition can be thought of as something that can be tested as either true or false at a given time. In the history package, Conditions are used to determine when Tags are to be collected. Generally, the facilities of class Tag are used for most conditions, but in special cases a user may wish to create a complicated condition by using the following classes (each of which is an heir of condition) to create a Condition object which is then used as an argument to method set_condition in class Tag.

A condition when evaluated by a call to the method evaluate (cycle, time) actually sets two attributes: state and state_final. The explanation of the purpose of state_final involves the intended use of Class Condition to represent conditions under which items should be sampled. Some conditions, particularly those involving a fixed stride in time, may be false at a particular sample but true later on. In order to ensure that the samples collected represent the full time range, we want to collect a sample at the last time even though it may not be the "tick" on which such a periodic condition is true. However, any condition that has past the last time at which it can be true should not be collected.

Thus, state_final is set by each condition in a manner appropriate to its nature.

Using a condition

A condition c can be tested at a given cycle/time as follows:

c.evaluate (cycle, time)

if c.state:

...condition was true...

if c.state_final:

...condition true when intended for use as "last" sample

Module Constants

	ForeverCycle = 1000000 ForeverTime = 1.0 * ForeverCycle are a time and cycle that are smaller than any time and cycle.
	NeverCycle = - 1000000 NeverTime = - 1.0e30 are a time and cycle that are bigger than any time and cycle.
	EveryCycle is an instance of class Condition that always evaluates to true.

Conditions available

These conditions are all heirs of Condition. A routine set with identical arguments to the constructor can be used to change the condition after creation.

	OneTime (time) This condition evaluates true when the time is reached.
	Cycles (start_cycle, stop_cycle = ForeverCycle, stride = 1) This condition evaluates true every so many cycles
	Times (start_time, stop_time = ForeverTime, stride = 1.0) This condition evaluates true every so many "seconds"
	And (Condition1, Condition2) This condition evaluates true if both are true
	Or (Condition1, Condition2) This condition evaluates true if one of the conditions is true
	Not (Condition1) This condition evaluates true if the condition is not true
	When ("expression to be evaluated", context = "__main__") This condition evaluates true if the first argument evaluates true in the given context. The context can be (a) a dictionary, (b) a string naming a module, or (c) a module. In (b) and (c) the modules' __dict__ is used.

Defining new conditions

To define a new kind of Condition, inherit from Condition and define a method _value (self, cycle, time) which evaluates the condition at that time and returns a tuple-pair of logical values. The first should be the value of the condition, true or false, at the current time. The second should be true or false under assuming this is the "last" timestep.

You can assume that _value (res. _value_last) is called only once for a given cycle number, and that these calls are in increasing order for both cycle and time.

Note: Your __init__ routine must call Condition.initialize (self).

It is recommended that you also redefine __repr__ and __str__, and name any routine which resets the condition set.