tempus Recorder File (trf) User's Guide

What is a tempus Recorder File (trf)?
How do I create a trf file?
How do I use a trf file?
What is in a trf file?
What types of data can be stored in trf files?
trf file Step-by-Step

What is tempus Recorder File (trf)?

A tempus Recorder File (trf file, read "turf file") is the primary mechanism by which tempus-based applications save results to disk. trf files provide a flexible and efficient mechanism to store all sorts of data throughout a tempus run and to access that data for analysis in post-processing tools such as Matlab. The following are some of the features of trf files:

Efficiency: trf files are created to minimize the amount of disk I/O during a tempus run and to expedite the loading of data during analysis. During creation, trf files are buffered on a variable-by-variable basis to minimize the number of times hardware I/O operations have to be performed. The size of the buffer is typically based on the size of the underlying data to be written. trf files are created using a random-access address linking approach which makes it possible to get directly to the data of interest during post-analysis.
Flexibility: trf files store any type of data to disk in such a way that the data is easily identified and accessed. trf files contain fields for data types and variable names. The dotted-notation used in tempus output variable names allows data to be easily tracked to the source and allow for flexibility in post-processing.

Not only do trf files store the results from numerous individual runs of tempus Systems (all of the runs in a run set) but they can also be extended to contain the results of multiple run set executions. In this way a user performing a particular study can keep together a large group of related data resulting from the execution of a number of tempus run sets.

Because the trf file is very modular users can access data from a trf file even while it is being created. This is very useful in viewing the early results of a long tempus run set execution.

Planned improvements to trf files include the addition of data compression capabilities, the storage and retrieval of data based on tempus run parameter settings, and the ability to store data which is not a tempus System Output.

How do I create a trf file?

The tve provides a mechanism that allows you to specify which tempus System Outputs are to be recorded during System execution. The trf file is created during execution of a tempus System for which such recording has been specified.

How do I use a trf file?

Once you have created a trf file by executing a tempus System, the primary mechanism for accessing the file is the Matlab-based trf toolbox. The trf toolbox is a library of m-file routines that allow data stored in trf files to be conveniently and efficiently loaded into Matlab variables. Once loaded, the data can be accessed for visualization and analysis using all the standard Matlab commands.

What is in a trf file?

trf files are random-access disk files written throughout the execution of a tempus run set. Depending on instructions from the user, System Outputs are periodically written to the file. The user can specify a particular rate at which data is to be stored or he can indicate that a System Output ought to be stored every time it is modified.

trf files are organized into a series of runs each containing a time-history of the variables selected for recording. For each run, a unique name is generated based on the settings of run set loop variables. If there are no loop variables, the run is named after the run set itself. For example, suppose that there are three run set loop variables, iturb, jwind, and krand. These might be used to perform a Monte Carlo study based on a number of different turbulence and wind speeds, where iturb is an index into an array of turbulence strengths, jwind an index into an array of wind speeds, and krand a random seed index. In this case, the generated run names would be of the form:

iturb=i, jwind=j, krand=k

where i, j, and k are the values of these loop variables for a particular run within a tempus run set. When executing a run set of 10 turbulence strengths, 5 wind speeds, and 30 Monte Carlo iterations each, the sequence of run names would be the following:

"iturb=0,jwind=0,krand=0", "iturb=0,jwind=0,krand=1",�,"iturb=0,jwind=0,krand=29", "iturb=0,jwind=1,krand=0", "iturb=0,jwind=1,krand=1",� "iturb=0,jwind=4,krand=29", "iturb=1,jwind=0,krand=0",�"iturb=9,jwind=4,krand=29"

Figure 1 of the trf toolbox User's Manual contains a graphical display of the runs in a case where 5 turbulence strengths, 1 wind speed, and 10 Monte Carlo iterations were used.

For each run, time-histories of user specified variables are stored. Within a particular run set these variables are usually, but not necessarily, the same. The variables are identified by their tempus variable name which is specified in dotted notation and is dependent on the location within the tempus Block Diagram of the System from which the variable originates. The general form of a variable name in a trf file is:

universe.top_level_system.subsystem. (�) .subsystem.output

where the universe is usually the name of the run set being executed, top_level_system is the instance name of the top-level system in the run set, subsystem. (�) .subsystem are the names of the nested subsystems in which the tempus System containing the recorded output is contained, and output is name of the Output for which recording was selected. For example, suppose the user selects the output slopes of a subsystem named wfs contained in another subsystem named nop in a top-level system called may08. The resulting variable name is then may08.nop.wfs.slopes (see Figure 1 of the trf toolbox User's Manual again). Table 1 illustrates how a trf-file is logically organized.

Table 1: The Logical Organization of a trf file

Run Names	Variables
iloop=0,jloop=0,�,nloop=0	tlb.subsys�.subsys.output tlb.subsys�.subsys.output �
iloop=0,jloop=0,�,nloop=1	tlb.subsys�.subsys.output tlb.subsys�.subsys.output �
�	�
iloop=0, jloop=0, �, nloop=nn	tlb.subsys�.subsys.output tlb.subsys�.subsys.output �
�	�
iloop=0, jloop=1, �, nloop=0	tlb.subsys�.subsys.output tlb.subsys�.subsys.output �
�	�
iloop=0, jloop=nj, �, nloop=0	tlb.subsys�.subsys.output tlb.subsys�.subsys.output �
�	�
iloop=1, jloop=0, �, nloop = 0	tlb.subsys�.subsys.output tlb.subsys�.subsys.output �
�	�
iloop=ni, jloop=nj,�, nloop = nn	tlb.subsys�.subsys.output tlb.subsys�.subsys.output �

What types of data can be stored in trf files?

Practically any type of tempus System Output can be stored to a trf file. This includes all System Outputs of type T, Vector<T>, Array<T>, and Grid<T> where T is int, float, double, or Complex. WaveTrain users will notice the conspicuous absence of the type WaveTrain from this list. This is because WaveTrain is a complex object whose state can only be properly sampled by an WaveTrain System of type WaveSensor. Typically, sampling a WaveTrain is done by inserting a sensor such as a WaveSampler or a Camera at the end of a beam train.

Currently, multiply dimensioned objects such as Array<T> and Grid<T> are stored as a linear vector and dimension information is not stored. In addition, with Grid<T> types, the physical grid parameters (spacing and extent) are not stored. Although there are simple mechanisms by which users can overcome this limitation, we nonetheless plan to fix it.

All data stored in trf files is stored in its native format (int, float, etc.), however, Matlab is structured to operate on double precision floating point numbers. Therefore, when data is loaded into Matlab using the trf toolbox, it is converted to double precision.

trf File Step-by-Step

Specify tempus System outputs that are to be recorded while in the tve session.
Execute the tempus System.
While in Matlab, open a trf file.
Load trf file data into Matlab variables.
Plot and manipulate data loaded from a trf file.