An unformatted data file consists of an optional header, followed by a list of floating point numbers and integers. In many cases these numbers will be arranged in columns. Each line of the header must begin with the comment symbol # (the pound sign). As soon as dstool reads a line which does not begin with a pound sign, it will assume that it should begin to read data. A typical header looks something like the following:
# Written by Tom Jones, Sun Jun 16 19:20:43 EDT 1991 # This file contains fixed points for a time-indep 4D symplectic mapping. # They were calculated using Maple. # The parameters for this run are: a = 0.3; b = -0.734; c = 1.24; # These fixed points occur on the plane w = 0. # The variables contained here are x,y,z. # Color is ON # Symbols are ONIt is suggested that every data file has a header of the above type which identifies what the file contains and what relevant system parameters were at the time that the file was created.
When loading unformatted data, the user is given the option to load the data into an appropriate memory object. When the user chooses the memory object which will contain the unformatted data, dstool loads the data. It is assumed that the unformatted data is appropriate for the chosen data object. Furthermore, each file may contain at most one type of data. For example, if a data file contains trajectory data, then that same data cannot also contain fixed point data.
When loading unformatted data, dstool always reads the current values of the phase space variables, the parameters (visible in the Selected Point Panel), the plotting symbol and size (visible in the Defaults Panel), and the current plotting color. Unless these values are set by the unformatted data file being read, they are used as default values. For example, if the user is reading in fixed point data and does not set color or symbol information within the file, then the current color and symbol are used to plot the unformatted data. In this same example, if the user does not include information on parameter values, then the current parameters are used.
We've already looked at a sample header for an unformatted data file. The remainder of that same file might look something like the following:
5.6319926e-13 5.6319926e-13 -1.689818e-12 7 6According to the header, the first three columns are the x, y, and z values of each fixed point. The fourth column contains color information and the last column contains symbol information. To load this file into dstool, the user would first set the parameter values a, b, and c, to reflect those parameter values specified in the header. The variable w should also be set to the value 0, since each of these fixed points occur in the plane w=0. Variables and parameters may be explicitly set in the Selected Point Panel. Since the particular set of equations being studied is time independent, the user may choose to ignore the variable time.
0.485636829 0.852655 0.500015 23 11
-0.485636322 0.852655 0.500001 59 16
The user then selects the unformatted load option from the Load Window, types in a valid directory and filename, and proceeds to choose panels items which tell dstool that the file to be read contains fixed point data, color information, and symbol information. The user then tells dstool that it should expect to read the variables x, y, and z by selecting the appropriate rows of the variables list. See the User's Manual for more information on how to use the Load Window.
When the user finally presses the Load command button, dstool finds the specified file (provided the file exists and is readable), skips over the header, and reads the three fixed points from the file into fixed point memory objects. Associated with each memory object is optional color and symbol data. In the example above, the first fixed point is assigned color 7. This means that whenever a ``pick color'' colormap is in use, then the color of the fixed point will be the seventh color on whatever colormap is currently in use. (If a ``depth'' colormap is in use, then the color of the fixed point depends on its coordinates; if an alternating colormap is in use, the color of the fixed point will be whatever the current alternating color was when the fixed point was loaded.) Similarly, the second and third fixed points are assigned the twenty-third and fifty-ninth color, respectively, whenever a ``pick color'' colormap is in use.
Also associated with each memory object is a symbol. In the example above, the first fixed point was
assigned symbol 6, the second was assigned symbol 11, and the third, symbol 16. The table below
summarizes what integer is associated with each symbol.
|
Additional comments about the way dstool reads unformatted data:
5.6319926e-13 5.6319926e-13 -1.689818e-12 7 6 0.48563682 0.852655 0.500015 23 11 -0.485636322 0.852655 0.500001 59 16