Program:       FUNPLOT

Purpose:       Interactive function plotting utility.

Category:      MATH, UTILITY

File:          funplot.src

Author:        J.P. Terlouw

Description:   FUNPLOT is an interactive mathematical function plotting
               utility based on the GIPSY graphical interface routines (Ggi).
               It is intended to be self-explanatory.

               When FUNPLOT is started, an X-window appears with a number
               of input fields, push-down buttons, scroll-down menus, and
               a plotting area. A default function is provided which can
               be helpful for users who want to explore the program's
               possibilities.

               One of the most important input fields, labeled "f(x)="
               allows the user to specify the function to be explored.
               This is a function of X; other names used is this function
               are parameters which can be changed interactively.
               This can be done by typing values in the input fields
               corresponding with the parameters, or graphically by
               moving a gauge (valuator) with the mouse. The gauge's range
               can be specified by typing in its limits fields or by pressing
               buttons which perform a zoom or translation on the range.
               The X- and Y-ranges of the plot can be changed in a similar
               way.
               Function example: A1*exp(-B1*(x-C1)**2)+A2*exp(-B2*(x-C2)**2)
               In this example there are six parameters:
               A1, B1, C1, A2, B2, C2.

               A parameter can be a single value (this is the default)
               or a list of values, using the GIPSY standard notation
               for number lists (see input.doc). In the latter case the
               associated gauge is blocked until a single value is given
               again. The number of points must not exceed the number
               in the "#PTS" field.

               With the "DERIV" button the plotting of the derivative
               can be switched on and off.

               Buttons "AXES", "GRIDS" and "VALUES" allow to enable and
               disable the plotting of axes, grids and parameter values.

               The "FFT" button pops up a secondary window showing the
               Fourier transform of the given expression. Display options
               are: real-imaginary, amplitude-phase and power spectrum.

               The "LABELS" button pops up a secondary window which allows
               the user to specify axis- and top labels for both the
               main plot and the FFT plot.

               In the main plot window position information can be obtained
               with the cursor. Left button: display coordinates below
               plot; middle button: also log in log file.
               The x- and y-coordinates are written to keywords XC= and
               YC=, respectively, so that these values can also be used
               in the expression (see below). If the control key is pressed,
               writing to these keywords does not take place.
               
               It is possible to make a hardcopy of the displayed plot(s)
               by first selecting an output device from the menu "PLOTTER"
               and then pressing the "PLOT" button.

Keywords:      There are many keywords, which can all be set by
               modifying fields, pressing buttons etc. in the X-window,
               so knowledge of these is usually not necessary.
               It is useful however to be aware that all input fields,
               menus, gauges etc. are tightly coupled with GIPSY keywords.
               This implies that the state of the program is preserved
               by Hermes. This state can be used to write a default file
               or to resume operation by using the macro ("!FUNPLOT").
               In numerical input fields all GIPSY's number input
               facilities can be used, e.g. the upper limit of a gauge
               can be specified as "2*PI".

   FUNCTION=   The function to be explored. This can be any expression in X.
               The following functions can be used in this expression:
               
               SQRT, SIN, ASIN, COS, ACOS, TAN, ATAN, EXP, LN, LOG,
               SINH, COSH, TANH, RAD, DEG, SINC, SEC, CSC, COT, ACOSH,
               SECH, CSCH, COTH, BJ, BY, BI, BK, SIGN, STEP, RECT,
               INT, NINT.

               The following constants are recognized:
               
               PI             3.14159....
               C              speed of light (SI)
               H              Planck (SI)
               K              Boltzmann (SI)
               G              gravitation (SI)
               S              Stefan-Boltzman (SI)
               M              mass of sun (SI)
               P              parsec (SI)

               To prevent that such constants conflict with any parameters,
               they must be enclosed by braces, e.g. FUNCTION=a*{C}*x .

        XC=    The cursor writes to these keywords, so that the parameters
        YC=    XC and/or YC, which are coupled to the cursor, can be used
               in the function.

Updates:       Sep 15, 1997: JPT, Document created.
               Feb 25, 1998: JPT, Eliminated private Ggi code, library used,
                                  cursor interaction implemented.
               Sep 11, 1998: JPT, Added Fourier transform and some other
                                  improvements.
               Sep 23, 1998: JPT, Added labels window.
               Nov 16, 1998: JPT, Changed for PGPLOT multiple device capability.
               Feb 17, 2000: JPT, Changed help button into help menu.
               Aug 29, 2000: JPT, cursor keyword interaction corrected.
               Apr 14, 2009: VOG, Cleaned up a bit and tested new definition
                                  of fie_nint() in fie.c which uses floor()
                                  to get the nearest integer