THE IGR CALCULATOR

The help file from the Calculator window, (authors A.L. & P.O.D) :
		   ================
                   CUIGR CALCULATOR
		   ================

INTRODUCTION
============
The Calculator, Figure I, is a tool for manipulating the 
quantities that should be plotted by the cuigr client.
It can be started from the igr "Select" menu.


OVERVIEW
========
The Calculator can do arithmetical operations on the quantities
defined in igr. It can make functions to operate on them, rotate
them and "join" quantities.
The client also defines which plot in igr the result of the
operations will be seen, and on which axis.
Examples:
---------
- 'p3y = q1 + q2'  Which means that the sum of quantities q1 and
  q2 will be plotted in plot 3 on the y-axis (and time along the
  x-axis which is default).
- 'p4x = q2' and
  'p4y = 4*(q1 - q0)' will plot the expression of the quantities 
  q1 and q0 as a function of the quantity q2. 
- 'p1y = {T0*q2}[0]' will plot the first component of the result
  of the multiplication of tensor T0 (to be set up by the user) 
  and the quantity q2.

The expressions are typed in the text field at the top of the
window. The plot specifications and quantity codes can alternatively
be chosen from the pull-down menus just below the input text field.
The result will then be seen in the text field at the bottom of the
window, see Figure II.
When an update is performed (either on the time manager or in igr)
the expressions in the lower text field will be used to define what
to plot in the different plots of igr.

Precedence in arithmetical expressions:
---------------------------------------
Unaryminus has the highest precedence. '*' and '/' have higher 
precedence than  '+' and '-'. To override this precedence scheme
use paranthesis.

Normalization of vectors
------------------------
If the quantity to plot is of type vector, or the result of the expression
is of type vector, the norm is computed so vectors become scalars before 
they are plotted.

Polar coordinates
-----------------
If the quantity to plot is of type vector, or the result of the expression
is of type vector, it can be converted into the components of a polar
coordinate system (r, phi, theta).

Joining of data
---------------
Joining will be performed if needed. 
E.g. p0y = q0 + q1,  if q0 and q1 do not have the same number of samples
or the sample times are not the same, the Calculator will automatically
join the least sparse of the two quantities to the same time line as
the most sparse one.

Word explanations and definitions:
----------------------------------
- Binding, the connection of a quantity or an expression of quantities 
  to a plots  x- or y-axis
- Setting, used in the same meaning as binding
- Joining, the modification of a quantity so its sample frequency and 
  "time line" will be in accordance with another quantity
- Plot name, a 'p' and the plot number, e.g. q3
- Tensor name, a 'T' or 't' and the tensor number, e.g. T5


INSTRUCTION SECTION
===================

How to start the Calculator
-----------------------
The Calculator can be started by choosing 'Calculator' in the 
'Select' menu on the 'igr' menu bar.

How to exit the Calculator
--------------------------
To exit the Calculator either press the 'Cancel' button or
choose 'Pop down' in the 'File' menu.

How to make bindings
--------------------
To make a binding of an expression of quantities to a plots x- or
y-axis, use the input text field a the top of the window.
First should the plot name (a 'p', the plot number, e.g. p12) and axis
specification (x or y) be typed in. Then an equal sign as a separator, 
and finally the expression.
Examples:
p0y = q0
p2x = q1*q2 + 10.0
If the axis is not specified, Calculator will assume that it is the
y-axis.
The plot names can alternatively be choosen from the 'plot x' and
'plot y' menus below the input text field. These menus contain the
first 20 plot names and axis. Choosing one of these will clean the 
input text field and print the plot name and an equal sign.

How to make corrections
-----------------------
Point with the mouse on the character just after the part to erase.
Press the left button and the cursor is in position for using the
'Back space' button.

How to set up a tensor
----------------------
Under the menu 'Options', choose 'Tensor' and a window will pop up,
Figure III.
That window have a field for a 3x3 tensor where all elements can
be typed in separately. 
First choose a tensor name on the menu below the tensor field.
Up to eight different tensors can be defined. Type in the tensors
elements and press the 'Define' button. This tensor can know be
used in expressions in the Calculator.

How to save a tensor to file
----------------------------
In the Tensor windows File menu, choose 'Save'. A file selector
will then pop up. Select the file name where to save the tensor
currently seen in the Tensor windows tensor field. Press
the 'OK' button and the tensor will be written to the file and
the file selector window will disappear.

How to read a tensor from file
------------------------------
In the Tensor windows File menu, choose 'Read'. A file selector
will then pop up. Select the file You will read the tensor from.
Press the 'OK' button and the tensor will be copied to the Tensor 
windows tensor field, and the file selector window will disappear.
Press the 'Define' button on the Tensor window so this tensor
can be used in the Calculator.

Expression with tensors
-----------------------
Tensors can be multiplied to quantitiess, e.g.
p0y = T1*q2
The result of the expression (T1*q2) is of type vector and the
norm will be computed so it can be plotted.
If a specific component of the vector should be plotted, it can
be obtained by extracting it from the result, e.g.
p0y = {T1 * q2}[1]
where the second component is extracted (the components are
numbered 0, 1 and 2). Observe curly braces should be used, not 
paranthesis.

How to erase all settings
-------------------------
To take away all bindings and make the plot text field clean,
choose 'Release all bindings' under the 'Edit' menu.

How to retrieve the default settings
------------------------------------
To erase all bindings and retrieve the default bindings, choose
'Reset to default bindings' under the 'Edit' menu.

How to erase a binding
----------------------
To erase one or more bindings, and still keep the other, mark
those bindings by clicking on them with the mouse. Then, in the
'Edit' menu, select 'Clear marked plot'. The marked bindings will
then dissappear, and if an update is performed, these plots will
no more be seen.
To take away an unwanted marking of a binding, point on that 
binding with the mouse and press the control key and the left 
button on the mouse.

How to take away an error message
---------------------------------
To erase the error message in the error message label (below
the 'Apply' and 'Cansel' buttons) either correct the error and
make an "apply" again or select 'Clean input line' in the
'Edit' menu.


REFERENCE SECTION
=================

MENU BAR:
-------
File, pull down menu with:
- Pop down, will pop down the Calculator window

Edit, pull down menu with:
- Clean input line
  Erase the text in the input text field and reset the error label
- Clean marked plot
  Will take away the bindings that are marked in the plot text field
- Reset to default bindings
  Will replace bindings for plot 0 to 19 with the default bindings
- Release all bindings
  Will erase all bindings

Option, pull down menu with:
- Tensor
  Will pop up a window with the ability to type in a 3x3 tensor.

  File, pull down menu with:
  - Read tensor, which will pop up a file selector for saving the
    current tensor
  - Save tensor, which will pop up a file selector for reading a
    tensor from a file into the current tensor
  Option, pull down menu with:
  - Reset to unit tensor, which will erase the current tensor and
    fill in the unit tensor.
  Tensor menu: 
    A table of the tensor names available
  Define button: 
    Makes the current tensor defined 
  Apply button: 
    Makes the current tensor defined and prints the tensor name 
    in the input text field.
  Cancel button: 
    Pops down the tensor window

Help
Shows this text in a separate window

INPUT TEXT FIELD:
-----------------
  The place where one types in what will be plotted along the x- and
  y-axis (default for the x-axis is time).
  exponent with e or E.
  Joining Join(q3,expr) or JOIN or join or j

  To bind a quantity to a plot without manipulation:
    p2y = q3    quantity number 3 will be plotted on the y-axis
		in plot number 2
    p1x = q1    quantity number 1 will be plotted on the x-axis
		in plot number 1

  Multiplication and division have higher precedence than addition 
  and subtraction:
    p0y = 3*q0 + q1/10 means (3*q0) + (q1/10) not ((3*q0) + q1) / 10

  Unaryminus has the highest precedence:
    p1y = q0 * -q1  means q0 * ( -q1)

  Quantities of vector type:
    p0y = q0    will compute the norm  (r=sqrt(x^2 + y^2 + z^2)) of q0 
                before it's sent for plotting.
    p0y = q0 [0]   will extract the first component of q0. The
		components are named 0, 1, and 2.

  Converting cartesian vectors to polar coordinate components:
    p0y = pol_r(q0) will compute the norm  (r=sqrt(x^2 + y^2 + z^2))
    p0y = pol_phi(q0) will compute phi (phi = arctan(y/x))
    p0y = pol_th(q0) will compute theta (theta = arccos(z/r))

  Tensor operations:
    p0y = T2*q0
    p0y = {T2*q0}[1] to extract component 2 of the result
	  curly brackets must be used, paranthesis are not allowed
	  for this case

  Plotting a constant (can only be done for the y-axis):
    p0y = 3.14

  Forced joining of a quantity:
    p0y = q0 + Join(q0, q1)  will first join q1 to the same time
			     line as q0 and then perform q0 + q1

PULLDOWN MENUS:
---------------
Quantity, pulldown menu:
  A menu with the 20 first quantities (quantities with higher
  numbers has to be typed by hand). The text on the selected
  button will be inserted at the cursor position in the input text field.

Plot x, pulldown menu:
  A menu with the first 20 plot numbers. When a button is selected, the
  input text field will be erased an the text on the buttom plus 'x' and
  an equal sign, will be printed.

Plot y, pulldown menu:
  Same as for the plot x menu except that 'x' is replaced with 'y'.

ACTION BUTTONS:
---------------
Apply button
  Have the same function as typing a return in the input text field,
  checks the text string and add the binding to the list shown in
  the plot text field. If the text string is not ok, it will instead
  show an error message on the error label.

Cancel button:
  Makes the calculator window disappear (pop down). The information in
  the plot text field is saved and is rertrieved when the Calculator 
  is poped up again.

ERROR LABEL:
------------
  When an error occurs will this field pop up and show the error message.
  When the error is corrected or the input text field clean with 'clean
  input line' will the message disappear.

PLOT TEXT FIELD:
----------------
  Shows the bindings that are prepared (of default bindings).
  If You want to take away one or more bindings, click on them
  with the mouse, and then choose the function 'Clean marked bindings'
  in the 'Edit' menu.
  To take away a marking use ctrl-left button on the mouse.

  The plot text field shows what calculations will be performed when an
  update is requested. At startup of the client we have default
  bindings, i.e. quantity n is bounded to plot n, where n is 0 to 19.


APPENDIX A Error messages and recovery procedures
=================================================
- 'Non existing quantity: qX' No parameter has been bound to the 
  quantity qX, or, a parameter has been bound to it but no update
  has been performed.
- 'Function not implemented' FUNC(...) the function name is misspelled
  or is not implemented.
- 'Syntax error' The expression in the input line is not syntactically
  correct. It can be that the expression is not completed or some
  character is missing or put at the wrong place.
- 'Non-existing tensor Tx' The Tensor is not defined. Under 'Option'
  choose 'Make Tensor' and type in the wanted tensor. Then press 
  the 'Define' button and this tensor can be used by the Calculator.


SEE ALSO
========
igr


BUGS
====
Focus is not on the input text field if the pointer is
not there.

p[nn]x cannot be seen in the plot if we have other bindings
in the same igr panel.