CORRELATION PLOTS ARITHMETIC FUNCTIONAL SPECIFICATION Gregory R. White First Published June 29th, 1993 Last Updated August 17th, 1993 ( Changed default labeling scheme ) Found in doc$spec:crr_arith_funcspec.txt Assoc. doc doc$spec:crr_arith_sysspec.txt INTRODUCTION This document describes proposed additions to the correlation plots interface necessary to provide an 'arithmetic capability'. OUTLINE In outline, arithmetic processing will be implemented by extending the allowed assignments of Sampled Variable (SV) buttons, to include arithmetic expressions. Then the values in the data array corresponding to an SV, will be either derived directly, as they are now from SLC db device values and PHYS variables etc, or indirectly as the result of their expression. The interface and operation of 'spreadsheet' software is a rough analogy. ENTERING AN EXPRESSION When a SV button is pressed, the user will be able to enter either a database entity (as is currently defined, that is, including PHYS variables, TIME etc), or an expression in some of the other SVs. The entry of an expression, as opposed to a valid input as currently defined, shall be distinguished by the use of an assignment (=) character in the input sequence. The placement of the '=' in an expression denotes whether the SV is being labeled with a variable name; if the '=' is the first non-blank character, then the SV's label remains at its default value. Alternatively, the '=' may appear after a variable name and before the arithmetic expression, in which case the SV is to be labeled with that variable name. In addition, it will be possible to refer to an SV to by its Correlation Plots index number, (between 1..160) escaped by the '#' sign. For example, having pressed the bottom-left SV panel button, the following may be input: toro dr13 - SV is assigned to partial device input. Correlation Plots will start a dialogue to establish the full device name (as is currently implemented). = sin(#4) - SV is assigned from result of function on sampled variable number 4. = B1 / B2 - SV is assigned from the value resulting from the data acquisition of two other SVs (see below). Pyield1 = B1 / B2 - SV is assigned from the value resulting from the data acquisition of two other SVs, and the result is labeled Pyield. AverageYield = (Pyield1 + Pyield2 + Pyield3)/3 - SV is assigned from three other SVs. In practice the level of parenthesis nesting will be limited to 10. LABELING Since the expression entered for a sampled variable can include any other variable (step or sampled) there must be some way to label the variables. The labeling will be oriented around row and columns; rows indexed by number, columns indexed by letter, as in most spreadsheets. On the 8 acquisition panels, the top two Sampled Variable rows have three columns each; the two rows beneath that have 7 columns each. This provides for 160 sampled variables. From one acquisition panel to the next the letters will repeat but the numbers will not. So, it is proposed that the following be the allowed sampled variable label defaults: A1-G4 on the first panel, A5-G8 on the second ... A29-G32 on the last panel. The value of a step variable may be used in an expression, but step variables may not be assigned from expressions. Step variables will have the labels STV1 and STV2. ARRAY OPERATIONS Elements of the target array will be computed from the corresponding elements of the arrays given in the expression entered for that target SV. No linear recurrence operations will be offered in the first release, so there will be no need to subscript all of the SV labels with a sample index. But this also means that it will not be possible to do operations on sub-arrays. For instance, given that SV button E2 has been pressed, the following might be a permitted expression to enter: = A1 + sqrt(B2) meaning each element of E2 should be computed from the congruent elements of A1 and B2. But the expressions such as A1[SAMP] = B1[SAMP-1] will not be allowed. FUNCTIONS In the first release, the following functions will be offered: power [via the ^ operator], exp(), sin(), cos(), atan(), log(), log10(), sqrt(), int() [rounded down to nearest integer], abs(). CONSTANTS Additionally, some predefined constants will be available. In the first release that list will be: PI 3.141593 E 2.718282 DEG 57.295779 PHI 1.618034 Physical constants and their values will be added as requested. PARSING AND EVALUATION Parsing for correct syntax will be performed at the time the expression is entered. Evaluation of the data for all expression defined SVs, will be performed at the end of the data acquisition cycle. An additional button will be provided for controlling evaluations. The button "EVAL ALL SV" will re-evaluate all the expression SVs. Going back to the entry for E2: "A1 + sqrt(B2)". At the time the expression for E2 is entered, if A1 or B2 have not been previously assigned, no message of the kind 'Undefined Variable' will be issued at the time. However, at the time the expression is evaluated, if A1 or B2 still have still not been assigned, then there will be such a message. The order of evaluation The scheme for evaluating the expression for an SV is subject to the order in which expressions are entered on SV buttons (i.e., their Sampled Variable number). The order of evaluation will proceed sequentially, from low numbered sampled variables (A1) to high numbers (FF3). The evaluation of expressions which contain references to sampled variables that are themselves defined by expressions will not chain. Therefore, it will be necessary to assign all "expression" sampled variables whose values are to be used in other expressions, to a lower button than that which uses the value. This is as it is in spreadsheets. For instance, the following will not be allowed; A1 = A3 where A3 = A2 and A2 is defined as a variable. The assignment of A3 from A2 is legal in this case because A2 is defined as a device. But the assignment of A1 from A3 is not because A3's data values will not be known at the time that A1 is evaluated. This is a case of an 'Undefined Variable' and such a message will be issued. PLOT LABELS The axes of plots for SVs defined by an expression, will be labelled with the expression, including, if present, any variable name on the LHS. In addition, the translation of the variable names used in the target expression will be given. Since the translation of a variable might itself be an expression, the extent, or level, of translation will have to be specifiable. A display of the definition of all SV's expressions will be available. MISCELLANEOUS FUNCTIONS A button will be provided in the first release for listing the definitions of all SVs defined by expressions. The first 24 characters of an expression will be printed on the button to which it is assigned. Auxiliary I/O. The Button File facility will be amended so as to save expressions for SVs. The output file types, such as 'spreadsheet', will also be amended in order to handle non-device column headers.