The NEW VAR button on the control panel is used to add new physical variables to the button matrix. There are three kinds of new variables you can add:
Cloned variables: these are copies of existing variables. You can use a cloned variable to make two different isosurfaces of the same variable simultaneously, for example.
External function variables: you can invoke an external function (which you write) to compute a new variable as a function of existing variables.
Computed variables: you can compute a new variable by typing in a formula involving values of existing variables.
When you click on the NEW VAR button a window appears which lists the variables that you can clone, lists the external functions that you can invoke, and lets you type in a formula for computing a new variable. After a new variable has been created a new row of buttons will be added to the control panel for the new variable. You can then make isosurfaces, contour slices, etc. of the that variable like any other.
Suppose you want to clone the U wind component variable so that you can make both +20 and -20 isosurfaces of it. First, click on NEW VAR and then select U from the pop-up window. The cloned variable will be named U'. You can then treat U' as any other variable and make an isosurface of it.
Type-in formulas let you type in mathematical expressions to compute new variables as a function of existing variables. For example, to compute wind speed from U, V, and W you would enter the formula:
SPD3D = SQRT( U*U + V*V + W*W ) |
To compute the ration of the dew point (TD) to the temperature you would enter the formula:
RATIO = TD / T |
Formulas may use the names of existing variables, numbers, the arithmetic operations +, -, *, / and ** (exponentiation), and the functions SQRT, EXP, LOG, SIN, COS, TAN, ATAN (arc tangent), ABS (absolute value), MIN and MAX. MIN and MAX take two arguments, while the other functions all take one argument.
There is a special operator 'time'. This will allow one to choose the grid values for a certain time step relative to the current time step. The format is 'time(var, time_step_change). If the var is subsituted with the word 'time' then the grid will be a constant value, the number of second since the first time step. For example in order to create a time derivative of U of the type:
you would enter the formula:
dUdt = ( time(U,1) - time(U,-1) ) / ( time(time,1) - time(time,-1) ) |
Click on the OK button to compute the new variable or CANCEL to discard the formula. You can edit the formula later by selecting it again from the NEW VAR pop-up window.
When multiple data sets are being viewed in one display a period and data context index number must be appended to the end of each variable in the formula. For example the above formula might instead look like:
SPD3D.2 = SQRT(U.0*U.0 + V.2*V.2 + W.2*W.2) |
To compute the difference of two seperate variables you would enter the formula:
DIFFT.0 = T.0 - T.1 |
If there are multiple data sets but no index number appended then it will be assumed that the variable belongs to the first data set (i.e., index 0) deposited into the display. In some cases the time steps for two different variables will not coincide. When this happens the variable is computed according to the time steps of the data set which the new variable belongs to. Time steps will be matched as close as possible and time steps out of range from one other will be void of data. For example, in the formula "DIFFT.0 = T.0 - T.1", if the time steps were such:
Table 6-1. Data Context 0
| Date(YYDDD) | Time(HH:MM:SS) | |
|---|---|---|
| Time 0 | 82091 | 0:00:00 |
| Time 1 | 82091 | 2:00:00 |
| Time 2 | 82091 | 4:00:00 |
| Time 3 | 82091 | 6:00:00 |
| Time 4 | 82091 | 8:00:00 |
| Time 5 | 82091 | 10:00:00 |
Table 6-2. Data Context 1
| Date(YYDDD) | Time(HH:MM:SS) | |
|---|---|---|
| Time 0 | 82091 | 2:30:00 |
| Time 1 | 82091 | 4:30:00 |
| Time 2 | 82091 | 6:30:00 |
| Time 3 | 82091 | 8:30:00 |
The resulting variable "DIFFT.0" would contain the data:
External analysis functions are an advanced feature, so new Vis5D users may want to skip this section for now.
An external analysis function is a function written by you in FORTRAN which is called by Vis5D to produce a new variable as a function of the existing variables. As an example, there is included a function SPD3D which computes wind velocity as: SPD3D = SQRT( U*U + V*V + W*W ). Be aware that the external function feature is intended for experienced Vis5D users who are also proficient FORTRAN programmers.
All external functions must be placed in a directory named "userfuncs" (this may be changed in the vis5d.h file). This is relative to the current directory when you run vis5d. For example, suppose you always run vis5d while in "/usr/jones/data", then your analysis functions must be in "/usr/jones/data/userfuncs". Also, this directory contains a script "externf" which is used to compile your function.
To write an external function it's best to copy one of the supplied examples and then modify it. The included "userfuncs/example.f" is fully commented for this purpose. Later, when you call your function from within vis5d, the function will be invoked once for each time step. The arguments passed to the function include (the data set is the first data set in the display associated with the current control panel):
the number of physical variables in the data set
the name of each variable
the size of the 3-D grid
the date and time of the time step
map projection and vertical coordinate system information
the actual 3-D grids of data for each physical variable
Your function will have to scan the list of variable names to find the ones it needs for the computation. Then it must do the actual computation, generating a new grid of data to return to vis5d. The examples we've included demonstrate how to do this. Specifically, you should look at example.f which has detailed documentation of the function arguments. The map projection and vertical coordinate system arguments work in exactly the same way as the v5dCreate library call discussed in section 3.1 .
Suppose you want your function to be named "delta". Then the name of the FORTRAN program must be "delta.f". You would compile the function by typing "externf delta". If there are no errors, an executable file "delta" will be written. Then in vis5d when you select NEW VAR, "delta" should appear in the list of functions in the pop-up window.
There are two places for vis5d to get the grid data which it passes to your external function: from the original, uncompressed McIDAS file or the compressed v5d/comp5d file. The uncompressed McIDAS data is better because it has more precision. If the McIDAS file can't be found, then the compressed data which vis5d has in memory will be passed to your external function. Note that this has no bearing whatsoever on the construction of your external function.
You can retrieve the position and values of the data probe from within your function. To get the position of the probe use:
CALL PROBEPOS( ROW, COL, LEV, LAT, LON, HGT ) |
The position in grid coordinates will be returned in ROW, COLumn, and LEVel. The position in geographic coordinates will be returned in LATitude, LONgitude, and HeiGhT.
To get the value of any physical variable at the current probe position and current time step use:
VALUE = PROBEVAL( VAR ) |
where VAR specifies which physical variable you want.