Time, Cycle and StateIndex Issues
Information regarding time, cycle and state index appears internally in VisIt code and throughout the GUI and CLI. This page attempts to define what these terms mean and describe how VisIt handles this information.
A database in VisIt typically represents a series of time states output by some simulation code. Also, typically, such a series takes the form of a sequence of files on disk; one file for each time state. Now, VisIt in fact imposes no requirement on how a database is decomposed into files. VisIt can just as easily read data from a database that consists of just a single state (in one or more files) as it can read a database having many time states all within the same file. The purpose in describing the typical case of databases that consist of one file per time state is to provide a context for the discussion of time, cycle and state index.
In Visit, the time associated with a state in a sequence of states in a database is the independent variable, t, in the system of time-dependent equations the numerical simulation producing the data is designed to solve. Just as x, y, and z represent the coordinates of a point in space, time or t represents the coordinates of a snap-shot of a simulation's state in time.
The other terms, cycle and state index are in some sense alternative coordinates for time. In VisIt, cycle represents the number of iterations of the main (outermost) loop of the numerical simulation. For example, a numerical simulation may make 10 iterations or cycles through its main loop to advance 1 microsecond in time. Finally, in VisIt state index represents a zero-origin, natural numbering of the sequence of states in a database, 0...NumStates-1. Other common names for state index in VisIt parlance are frame (e.g. frame in a movie), step, time step or time state.
A set of files representing a sequence of states for a database input to VisIt might look like this...
Filename(s) Time(s) Cycle(s) State(s) foo_01234.silo 0.0046 1234 0 foo_04561.silo 0.00487 4561 1 foo_17925.silo 0.0112 17925 2 foo_38223.silo 0.045 38223 3
This is the basic and typical situation. Now, a number of issues conspire to make VisIt's handling of time, cycle and state index a little more complicated than this. First, not all file formats support the concept of time and/or cycle. So, this information is really optional. VisIt can always fall back to using state index if either time or cycle information is not available. Next, not all databases VisIt reads store data from different states in different files. Such databases are called MT (multiple time-step) databases. As a convenience, users often encode information (usually the cycle) into the filename itself. When VisIt is working with databases consisting of many states spread over many files, it can be prohibitive to open each and every file solely to obtain time and/or cycle information. To the extent that it can, VisIt does attempt to make (cheap) guesses at this information when it can.
VisIt attempts to guess only cycle information from a filename. When it makes an attempt to guess the cycle from a filename, if the underlying operations to find a numerical value in the string representation of the filename work and succeed in converting it to an integral value, then it takes the resulting number as a guess of the cycle. However, VisIt deems its own guess as unreliable by indicating that the cycle is not accurate. By default, VisIt does not ever attempt to guess time from a filename. This is primarily because time is ordinarily a floating point value containing a decimal point (e.g. a dot) and VisIt would not be able to distinguish it from a dot preceeding, for example, a file extension. Finally, you can adjust VisIt's logic for how it guesses cycles from filenames by specifying the -cycleregex command-line option when launching VisIt.
In the database plugin interface, there are four methods a plugin may, at its option, implement to manage time and cycle information apart from VisIt's guessing at it. These are...
GetTimeFromFilename() GetCycleFromFilename() GetTime() GetCycle() GetTimes() GetCycles()
Certainly, this interface has diffused from its original design a bit and so some methods do not necessarily make much sense for some types of databases. For example, for an MT database, the filename based methods are not that useful because a single file contains multiple states. Apart from that however, for ST databases the filename based methods are very useful to implement when it makes sense as it allows VisIt to obtain cycle (or time) information without having to actually open the files. When a plugin implements GetCycleFromFilename(), even it its implementation is simply to turn around and call VisIt's internal method that guesses cycles from filenames (e.g. return avtFileFormat::GuessCycle), this is a way for the plugin to not only implement its own parsing of cycle information from filenames put also inform VisIt when (and if) the resulting values are accurate. VisIt trust's a plugin's implementation of the filename based methods even if it does not trust its own.
The non-filename based methods to obtain time of cycle information from a plugin typically require the plugin to open the file and read some data out of the file. These are much more costly operations. So, VisIt will attempt to call these other methods only when is unable to obtain accurate values via the filename based methods or when preferences have been set to tell VisIt to try harder to get accurate cycles and times. This preference causes VisIt to open each and every file in a database to obtain accurate time and/or cycle information by calling the plugin's GetTime()/GetCycle() methods.