\section{Caveats} Fmax is a new and improved interface to the internals of xmath. It allows you to graph equations very easily and will create xy and barchart graphs. It is still under development meaning that suggestions, comments, and bug reports (Send mail to bug-fmax@athena) are welcome. A couple of important things to know when using fmax: 1) You must hit a return when typing text or numbers in the dialog boxes to setup the axes, plots, etc. If you hit the Apply button and nothing happens, this may be the reason. 2) You may need to click the left mouse button in the input window (the one that says "fmax>") in order to get input focus. If you are typing and nothing appears, click the mouse button. \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 first choosing the type of plot you want from the "Plot" menu and then selecting the "Read Data File" entry from the "File" menu, or by typing plot "filename" The file should have between one and six 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 is more than one column, each column after the first is taken to be a y value for the common x. \subsection{Plotting Barcharts} You can plot barcharts from a data file by enabling the Barchart option on the Plot menu (a toggle button will appear next to the word 'Barchart' when the option is enabled) and then plotting data as described in the previous section. \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, first chose the type of plot you want from the "Plot" menu and then type: plot [, ] So for example, if t is an array of points between 0 and 2*pi, and the XY plot type has been selected, 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. To plot a barchart from an array, simply enable the Barchart option on the "Plot" menu and type the command. Note that what distinguishes this plotting syntax from the others is the presence of the square brackets around the expressions. \subsection{Customizing Plots} Each plotted function in fmax has its 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. (Be sure to hit a return in the boxes that you type in before hitting the Apply button!!!) 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. You will usually 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 - XY Plots} 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. Before chosing this option you must select the plot you wish to set up by clicking the left mouse button on its name in the Legend. If you do not select a plot, the last one drawn will be chosen. 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: Specifies that a line should be drawn from the x (y) axis vertically (horizontally) to the given point. Line Width: The thickness of the plotted line is selected with this button. The default is zero, which tells fmax to draw lines using the fastest method that it knows. Lines drawn with a width value of zero will usually have an actual width of 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{Plot Styles - Barcharts} Barcharts also have a plot style that indicates how a plot is drawn. If the selected plot is a barchar, you will be presented with a dialog box that will allow you to customize it. (Make sure that you hit a return in the parameter boxes before applying the changes!) Name: This is the title of the selected plot, that is displayed when the Legend is visible. You may type over the previous string. Number of Points: The number of points in the data set. Xmin: Specifies the first bar's position on the X axis. Xmax: Specifies the last bar's position on the X axis. Density: Controls the thickness of the plot's bars. Valid values are between 0.0 and 1.0, inclusive. If the density is set to 0.0, each bar looks like a thin straight line. Increasing the density value causes each bar to become wider until at 1.0 each bar's rightmost edge will touch it's next neighbor's leftmost edge. Shading: If turned on, all bars will be filled with the pattern specifed by the Fill Pattern option. Pattern: A predefined set of seven patterns to use for shading. Note that shading must be turned on for this to take affect. \subsubsection{Customizing the Plotter} Selecting the option "Customize Plotter" (Meta-C) on the Edit menu will bring up a dialog box that will permit you to customize the plotter. The editable characteristics are as follows: Title: The title to be displayed centered above the plotting area of the widget. Fonts: The dialog allows you to choose from a number of different fonts and font sizes for the plotter title. Framed Axes: Specifies whether the axes should be drawn as a "frame" around the entire plotting area. If on, the top and right hand sides of the plotting area will be drawn with unnumbered tic marks. If this resource and floating axes are both on, the results are unspecified. Show Legend: Toggle between displaying and not displaying the legend. Show Secondary Y Axis: Specifies whether the second Y2 axis should be displayed at the right of the plotting area Rank Children: Specifies the order that plots are drawn. If off, plots are drawn in the order they are created. If on, each plot can be ranked with an integer that specifies its redraw priority with the AtPlot resource XtNrankOrder. Floating X Axis: If on, specifies that the x-axis should "float" and intersect the y-axis at the y-axis's origin. If off, specifies that the x-axis should be drawn at the bottom of the plot area. Floating Y Axis: If on, specifies that the y-axis should "float" and intersect the x-axis at the x-axis's origin. If off, specifies that the y-axis should be drawn at the left edge of the plot area. Show Legend: Specifies whether the legend should be drawn. Force Square: Specifies whether the user-coordinate to pixel-coordinate scaling factors should be the same for the x and y axes. This forces a "square" coordinate system. In enforcing this constraint, the axis that is adjusted will always have its domain or range increased, never decreased. This resource only effects the x and y axes -- it does not effect the y2 axis. AutoScale: Specifies whether the plotter should adjust the bounds on its axes to be fit the data displayed exactly. If on, the axis bounds will be adjusted. In the case where an axis would be scaled to a single point (horizontal or vertical lines), the axis is scaled from 0.0 to the point. \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 will be asked to input the title, which is placed 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. You may also set the title, and X, Y, and Y2 axes labels from the fmax> prompt using the commands "title", "xlabel", "ylabel", and "y2label", respectively. For example, the command title "Test Results" will set the title string to "Test Results". \subsection{Viewing Plots - the View Menu} \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. Alternatively, you can zoom in using the "Zoom In" option on the View menu, or by typing Meta-I at the keyboard. To zoom back out, use either the "Zoom Out" option from the View menu, or type Meta-Z at the keyboard. \subsubsection{Panning} The menu options Pan Left, Pan Right, Pan Up, and Pan Down allow you to view a different part of the plot. By panning in different directions you can see more of a function plot. \subsubsection{Reset View} The Reset View menu option sets all of the axis boundaries to the values they had when the last plot created was first plotted. This is a convienient way to get back to where you started after zooming and panning. \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 fmax 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! factorial 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. (Also be sure to hit a return in the parameter box!) 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. \section{Other Commands} \subsection{Clear} Typing "clear" at the fmax prompt will delete all the plots at one time. \subsection{Set} The set command allows you to set options for the graph style. \subsubsection{Number of Samples} The option "numsamples" allows you to specify the number of samples to be used in a drawing a plot. For example, set numsamples 200 would set the number of samples to 200. The default value is 100. \subsection{Display of Assignments} You can control whether or not fmax prints out the results of a variable when you declare it with the set display [on, off] command. For example, the command set display off will disable subsequent printing on assignments. You can enable display by typing set display on The default is to enable display.