\section{Caveats} This help file is based heavily on the information from Xmath. Only those features that are currently implemented are described here. Tune in later for more functionality. And what is the root of the word "functionality", but "fun"! Play around with the stuff in the menus. You'll figure it out... For more detailed information, look at the source code for the parser. /mit/atdev/src/fmax/grammar.y is the yacc grammar for all the command expression handling stuff. \section{Plotting} \subsection{Plotting Expressions} To plot an expression, type: plot With this syntax, the independant variable is always "x". Examples: plot sinh(x) (hyperbolic sin of x) plot (x+1)**2 (x+1 squared) plot sqrt(x) (squareroot of x) \subsection{Plotting Data from a File} You can plot data from a file, by selecting the "Read Data File" entry from the "File" menu, or by typing plot "filename" The file should have one or two columns of numbers in it, and nothing else. If there is only one column, then it is treated as y data, and the x values are taken to be successive integers starting from 0. If there are two columns, they are taken to be x and y values. ***At present, you can only load 2 column files, and only with the 'plot "filename"' syntax.*** \subsection{Plotting Arrays of Numbers} fmax allows you to define and manipulate arrays of numbers. (See the "Arrays" section below.) To plot an array of x values against an array of y values, type: plot(, ) So for example, if t is an array of points between 0 and 2*pi, then the following command plots points in a circle: plot(sin(t), cos(t)) And the following plots a Lissajous figure: plot(sin(2*t), cos(3*t)) If you plot only one array, it is taken as an array of y points, and the x points are taken to be successive integers starting with 0. For example with t defined the same way, plot(sin(t)) would plot points on a sine wave. Note that what distinguishes this plotting syntax from the others is the presence of the parentheses around the expressions. \subsection{Customizing Plots} Each plotted function in fmax has it's own display characteristics which can be customized to suit the user. As well, the axes themselves have attributes that can be altered. \subsubsection{Autoscaling} When the autoscaling option is on (button is visibly "pushed"), fmax will automatically adjust the size of the x and y axes up or down to fit the maximum and minimum values currently plotted. If you plot data from files, fmax will automatically adjust the axes so that all data points are displayed. If autoscaling is set off (not visibly pushed), fmax will never automatically adjust the axes. You can turn the autoscaling option on and off by clicking on the "Autoscale" option on the Options menu. Alternatively, you may use the keyboard to type Meta-A to toggle the option on and off. \subsubsection{Setup Axes} By clicking on the "Setup X/Y/Y2 Axis" option on the Edit menu, you will bring up a dialog box with many editable characteristics of the chosen axis. These are as follows: Min/Max: Enter the maximum and minimum values for the axis in the given boxes to set the range. Just type over the values already there. Transform: This button lets you select between linear (normal) and logarithmic transforms to be applied to the axis. Note that fmax will not let you apply logarithm mode if that axis extends below zero. Label: Enter the label for the selected axis. Fonts: The dialog lets you choose from a number of different fonts and font sizes for the axis label and the axis tics. Draw Grid: It is sometimes useful to have reference points or "graph paper" drawn in the background on the plot window. This button toggles the dots perpendicular to the selected axis on and off. Tic Information: These let you specify the interval between tic marks drawn and numbered on the axes. A value of zero is the default and means that fmax should choose a reasonable value itself. These boxes are self-explanatory. After setting your options to your desire, you may Apply the options to the graph, Done the window without applying the changes, Reset the values, or obtain Help. Usually, you will want to Apply the changes, then Done the window. Note that there are keyboard accelerators for setting up each of the three posible axes: Meta-X for the x axis, Meta-Y for the y axis, and Meta-2 for the optional second y axis. \subsubsection{Plot Styles} A plot style indicates how a plot is to be drawn -- with solid or dotted lines, or with circles, or triangles, for example. When you use the "Setup Selected Plot" option from the Edit menu, you will be presented with a dialog box that will allow you to customize the chosen plot. Name: This is the title of the selected plot, that is displayed when the Legend is visible. You may type over the previous string. Data Points Connected: Toggling this on will tell fmax to create a line from data point to data point in sequence. Mark Points/Marker: When Mark Points is set on, the Marker option is retrieved and the selected shape is used to mark the data points on the plot. Draw Impulses: This seems to draw some pretty random lines that probably have a deep inner significance to Dave F. Actually, I'm sure they are useful and important, but I really have no idea what they represent. Line Width: The thickness of the plotted line is selected with this button. The default is zero, which usually defaults to one. Style/Dash Length: You may choose either a solid or a dashed line for each of the plots on your graph. If the dashed option is chosen, then the length of the dashes (and the spaces between them) is specified in pixels by Dash Length. Again, as with the Setup Axis dialog, four option buttons are given at the bottom of the dialog. After setting your options to your desire, you may Apply the options to the graph, Done the window without applying the changes, Reset the values, or obtain Help. Usually, you will want to Apply the changes, then Done the window. This dialog can also be brought up by typing Meta-S on the keyboard. \subsubsection{Labels and Decorations} fmax allows the user to decorate the plot window with a title, a legend, annotations, and axis labels. Each of these is completely editable. By choosing Set Title (Meta-T) from the Edit menu, you are asked to input the title, and then it is place above the plot. On the Options menu there is a toggle button to turn on and off the display of the legend. Within the Annotations menu, there options to create, edit, move, and delete. Each of these is fairly self-explanatory. \subsubsection{Zooming} To zoom in to any arbitrary rectangle on the plot window, click the mouse and drag out that rectangle over the plot window with the mouse. To zoom back out, use either the Zoom Out option from the Options menu, or type Meta-Z at the keyboard. \section{Math With Fmax} \subsection{Constants} Integer constants are simply series of digits. All integers are understood to be base 10. There is a machine dependant limit on the maximum positive and negative size of integers. Integer constants that are too big will be handled incorrectly. Real constants have a decimal point or an exponent. Exponents are given in the standard `E' notation. (eg. 3.4e12 means 3.4 time 10 to the power of 12) Complex constants are also allowed and are indicated as {real,imag}. \subsection{Complex Numbers} Fmax deals with complex numbers as naturally as with real numbers. It represents them inside of curly brackets (`{' and `}'). If you type "sqrt(-4)" fmax responds with "{0, 2}" which represents the complex number 0 + 2i. You can use complex numbers in the same way. For example 2.17281728**{0,3.14159} is approximately equal to -1. Note that the values inside the curly brackets must be numeric constants. You cannot use variables or expressions as elements in this complex number notation. In order to represent complex variables, first define the variable i or j, and use it as in standard mathematical or physcial notation: i = {0,-1} z = 3*a + 4*b*i \subsection{Expressions} Expressions in fmax are in infix notation. Most any mathematical expression from C, Pascal, Fortran, or BASIC is valid in fmax. Fmax supports the relational and boolean algebraic operators of C. If you are familiar with other languages, you may not recognize some of these operators. The order of evaluation is standard, and as usual, parentheses alter that order for an expression. Exponentiation is indicated with two stars (**) rather than with a caret (^), and some function names may not be as you expect them. \subsection{Variables and Assignment} Just about anything can be a variable name. ("plot" and "clear" and any other commands are exceptions). To assign a value to them, just use "=": a = 3 If there is no decimal point in a number, fmax will store it internally as an integer. Complex numbers are represented as follows: \{ real part, imaginary part \} For example: a = sin({2,3}) \subsection{Arrays} \subsubsection{Defining Arrays} To define an array in fmax, you can simply list its elements: a = [1, 2, 3, 4] To create an array which is a partition of an interval, use the following syntax: a = [min:delta:max] which will define a to be the array [min, min+delta, min+2*delta, ... max] You can omit the delta: a = [min:max] in which case it is taken to be 1.0. As an example, the following partitions the interval between 0 and 2 pi. t = [0.0 : .1 : 6.28] \subsubsection{Using Arrays} You can use an array almost anywhere that you would use a scalar. Calling a function f with the array a [a1, a2, a3...an] results in the array [f(a1), f(a2), f(a3)...f(an)] Adding a scalar to an array adds the scalar to each element of the array. Adding an array to an array is legal only if they have the same number of elements and adds element by element. Other operators behave similarly. The operator "+/" sums the elements of an array: +/[1,2,3,4] would result in 10. There are analogous operations for all the other binary operators (-/, */, **/ etc.) The operator "$" returns the number of elements in an array. Thus to take the average of the elements of an array a, you would type: +/a / $a \subsection{Functions} The following table lists the primitive functions fmax understands. For help defining your own functions, see Defining New Functions below. \begin{verbatim} abs absolute value. Returns the magnitude of a complex argument. acos inverse cosine, arccos. Returns a radian value. ang returns the phase of a complex number, its "angle" asin inverse sine, arcsin. Returns a radian value. atan inverse tangent, arctan. Returns a tangent value. besj0 j0 Bessel function. Argument is in radians. besj1 j1 Bessel function. Argument is in radians. besy0 y0 Bessel function. Argument is in radians. besy1 y1 Bessel function. Argument is in radians. ceil the ``ceiling'' function. Returns the smallest integer not less than its argument. Ignores the imaginary part of complex arguments. cos cosine. Argument is in radians. cosh hyperbolic cosine. Argument in radians. exp exponential. $e^{x}$ floor the ``floor function''. Returns the largest integer not greater than its argument. Ignores the imaginary part of complex arguments. imag returns the imaginary part of a complex number. int returns the integer part of its argument, truncated towards zero. Ignores the imaginary part of complex numbers. log natural logarithm. log10 base 10 logarithm. real returns the real part of its argument. sgn signum. sgn(x) = 1 if x > 0, -1 if x < 0, and 0 if $x=0$ Ignores the imaginary part of its argument. sin sine. Argument in radians. sinh hyperbolic sine. Argument in radians. sqrt square root. tan tangent. Argument in radians. tanh hyperbolic tangent. Argument in radians. \end{verbatim} \subsection{Operators} The table below lists the operators xmath understands. The number in the Precedence column has no meaning other than to group operators with the same precedence. An asterisk in the Special column means that the operator accepts only integer arguments. A percent sign in that column means that the operator has a boolean value. \begin{verbatim} Operator Usage Operation Precedence Special --------------------------------------------------------------------------- - -a unary minus 12 ~ ~a one's complement 12 * ! !a logical negation 12 *% ** a**b exponentiation 10 * a*b multiplication 9 / a/b division 9 % a%b modulo 9 * + a+b addition 9 - a-b subtraction 9 < a a>b greater than 8 % >= a>=b greater than or equal 8 % == a==b equality 7 % != a!=b inequality 7 % & a&b bitwise and 6 * ^ a^b bitwise exclusive or 5 * | a|b bitwise inclusive or 4 * && a&&b logical and 3 *%1 || a||b logical or 2 *%1 ?: a?b:c ternary operator 1 2 -------------------------------------------------------------------------- \end{verbatim} Notes: (1) The && and || operators "short circuit" as in C. That is, the second argument to && is evaluated if and only if the first is true, and the second argument to || is evaluated if and only if the first is false. (2) The ternary operator is a conditional operator. If expression a is true then the value of the expression is the value of b, otherwise the value of the expression is the value of c. a must evaluate to an integer. Note: The ternary operator, and the and and or operators have not yet been fully tested. \subsection{Defining New Functions} You must use the keyword "define" in order to define a function. You can define single or multi-variate functions: define f(x) = x + 1 or define hypot(x,y) = sqrt(x**2 + y**2) Once you've defined it, you can use your function like any of the built in ones. \section{Files} \subsection{Printing Your Plot} Clicking on the Print option in the File menu will expose a dialog box. Choose the size of the output you desire in the Width/Height boxes, and if you like, change the Units and/or the Orientation (Portrait is the normal print style, while Landscape is rotated counter-clockwise 90 degrees. Be sure to type in the printer you would like the output to be sent to. Click on the Print button to send the PostScript output to the printer, select Cancel to abort the printing, or choose Help for information. \subsection{Saving Your Plot} By clicking on the Print option in the File menu, a dialog box will be exposed. From the Print To: button, choose File. Type in the full path name you would like to save the PostScript file under. Set the proper values for Height, Width, Units, and Orientation if you prefer something other than the default settings. Click on the Print button to save the output under the name you gave, select Cancel to not save the file, or choose Help for information.