GTKMathplot User Manual

Copyright (C) 2012, 2013 Ivano Primi <ivprimi (at) libero (dot) it>

Permission is granted to copy, distribute and/or modify the files of the user manual of GTKMathplot under the terms of the GNU Free Documentation License, Version 1.3 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. You should have received a copy of the GNU Free Documentation License along with GTKMathplot. If not, see http://www.gnu.org/copyleft/fdl.html.

Table of Contents

1 OVERVIEW

After starting, GTKMathplot shows a window with a menubar and two "pages" with only one page visible, namely the Input page.

The Input page contains essentially an input mask, other than a couple of buttons and a combo. In the mask you should enter the information related to the objects you want to display, in particular the associated cartesian/parametric equations. In other words, the input mask should be used to define the objects that have to be visualized.

The other page, i.e. the Output page, consists mainly of a "canvas" where to draw the mathematical objects and of some controllers. These ones can be used to adjust or change the parameters and the attributes which determine how the objects are exactly drawn. The Output page is initially hidden, and you can display it by clicking on the page indicator (page indicators are also known as tabs) with the label "Output". Whenever I say "click", here and in the following, I mean clicking with the left button of the mouse unless otherwise specified.

If you click on the "Output" tab, the Output page arises and shows a completely white canvas: since you have not entered any mathematical equation yet, there is no object to visualize. To move back to the Input page, you should either click on the "Input" tab or on the button "Back to input mask".

After entering in the Input page the description of one or more mathematical objects, you can visualize them by clicking on the button labeled with "Display/Update graphic". If you click on this button before defining any mathematical object, or after clearing all previously entered definitions, then nothing will be shown in the canvas.

The Input page provides the button "Quit", click on it to terminate the program. You can also terminate the program by clicking on the entry "Quit" from the "Main" menu in the menubar, or by pressing the key 'q' while holding down the Control key (this is the shortcut Ctrl+Q).

In the menubar you can also see the "Edit" menu. This one provides the entry "Preferences". If you click on it, then the "Preferences" window appears, where you can change some settings (like colors, symbols, paper format) which are used while drawing the mathematical shapes on the canvas or while exporting them to a Postscript/PDF file.

The menubar provides also a "Help" menu. The "Help" menu has the entries "Help", "License", and "About". Click on "License" to get a short notice about the distribution terms of GTKMathplot, on "About" to get copyright statement and email address of the author.

If you click on the entry "Help", a window is shown containing this help text. You can display the help text also by pressing the key 'h' while holding down the Control key (this is the shortcut Ctrl+H).

1.1 NAVIGATION AND EDITING

You can navigate through the elements of the graphic interface of GTKMathplot using the Tab key. Whenever you press the Tab key, the focus moves to the next element (an entry, a button, a combo) of the interface. If the focused element is a button or a combo, pressing the Enter key has the same effect as clicking on it. If the focused element is a group of radio buttons, you can use the arrow keys to change the selected button; care that Up-arrow and Left-arrow key move the selection in the same direction, just like Down-key and Right-key do. In case the focused element is a slider, you can employ the arrow keys to change the associated value: Up-arrow and Left-arrow decrease the value, Down-key and Right-key increase it. If the focused element is an adjuster, you can increase the associated value by pressing the Up-arrow key, and decrease it by pressing the Down-arrow key. Finally, if the focused element is a text entry, then you can employ all usual keys to move along it (Home and End key, in addition to the arrow keys: they all work as expected), you can erase the character under the cursor by pressing Del(ete), and the character before the cursor by pressing the Backspace (<–) key. If you want to select the text contained in an entry or part of it, then you should hold the Shift key down, either the left or the right Shift key, while pressing one of the arrow keys, or the Home key, or the End key.

Once the last element of the currently active page or window has been reached, a further pressing of the Tab key moves back to the element which was focused as first: the navigation with the Tab key is cyclic. If you want to navigate in the direction opposite to the one of the Tab key, you should hold the Shift key down while pressing Tab (this is the shortcut Shift+Tab). The navigation with Shift+Tab is also cyclic.

1.2 GENERAL SHORTCUTS

  • Ctrl+q : Quit GTKMathplot
  • Ctrl+h : Show the online help
  • Ctrl+p : Open the "Preferences" dialog window
  • Ctrl+a : Open a dialog with copyright information
  • Alt+m : Open the "Main" menu
  • Alt+e : Open the "Edit" menu
  • Alt+h : Open the "Help" menu
  • Esc : close a menu or dialog window

1.2.1 REMARKS

  • Ctrl+key is the combination obtained by holding the Control key down while pressing `key',
  • Alt+key is the combination obtained by holding the Alt key down while pressing `key',
  • Shift+key is the combination obtained by holding the Shift key down while pressing `key',
  • Esc is the Escape key.

2 THE INPUT PAGE

The Input page contains two selectors, the first one in the form of a couple of radio buttons, the second one in the form of a combo.

The radio buttons are labeled with "2D" and "3D", respectively. As the labels say, they allow to switch between two- and three-dimensional graphic mode by clicking on them. Mind that GTKMathplot allows you to plot both two- and three-dimensional shapes, but not together at once. Thus, you can not mix two- and three-dimensional objects in the same graphic but you should choose each time in which graphic mode you want to operate. The default graphic mode, i.e. the one selected after the start of the program, is the two-dimensional one.

The combo selector lets you pick up the mathematical shape you want to define or whose definition you want to change. GTKMathplot allows you to display several mathematical shapes at a time, namely up to 10 in two-dimensional mode and up to 5 in three-dimensional mode. Each shape is defined by its own equation or set of equations.

The shapes are identified by numbers (from 1 to 10 or from 1 to 5) and the combo always shows the currently selected shape. Immediately after the start of the program the selected shape is the number 1. You can switch to another shape by clicking on the combo: a menu opens and from there you can select another shape by clicking on the corresponding entry.

The most important element of the Input page is the input mask containing the "Object definition". In the input mask you should enter the mathematical definition of a curve or surface. This consists of one or more equations and of the variation interval(s) of the parameter(s) appearing in those equations.

GTKMathplot lets you define an object either by means of a single cartesian equation or by means of a set of parametric equations. The default definition type is "Cartesian", meaning that GTKMathplot expects you define a mathematical shape by means of a single cartesian equation. To switch to the "Parametric" mode, you should click on the radio button with this label. To switch back to the cartesian definition type, just click on the "Cartesian" radio button.

The actual aspect of the input mask depends on the chosen definition type.

If the active definition type is "Cartesian", then you can see one long text entry where you are supposed to enter the cartesian equation describing the object. Near to this entry, on the left side, there is either the label "y(x) = " or the label "z(x,y) = " depending whether the current graphic mode is either 2D (two-dimensional) or 3D (three-dimensional). If the definition type is set to "Parametric", you will see three long text entries marked with the labels "x(s,t) =", "y(s,t) =", and "z(s,t) =", respectively (although the "z(s,t) =" entry is disabled in two-dimensional graphic mode). In these entries you should type the parametric equations defining the object you would like to visualize. If you do not know what parametric equations are, then you will probably never need to work with the "Parametric" definition type. Anyway, if you are curious, you can know more about parametric equations by reading the section EXAMPLES.

Under the text entry/entries for the equation(s) you can see one or two rows of three text entries each. Here you should enter the minimum and the maximum value that the parameter(s) appearing in the equation can take. If you need it, you can also specify for each parameter the number of subintervals into which the variation interval (i.e. the interval between minimum and maximum of the parameter) has to be split. The default value, either 200 or 50, is adequate for the greatest part of use cases. A higher value means a smoother appearance of the displayed object, a too low value produces rough shapes with artificial edges. Mind that what 'too low' exactly means depends on the particular equation(s) defining the mathematical object. If this is visualized in a too rough way, then you should definitely increase the number of subintervals for one or both parameters.

To every mathematical object you can associate a caption, which is going to be shown in a legend near to the canvas; the caption can be entered in the text entry labeled with "caption:".

A mathematical object can be drawn by GTKMathplot in different plot styles, namely dotted, stroked, or filled. The plot style can be chosen by clicking on the corresponding radio button within the "Plot style" frame. The filled style applies only to surfaces: filled surfaces are visualized by means of filled facets (in 3D) or triangles (in 2D). Stroked curves and surfaces are visualized as metal wire skeletons formed by many, and possibly very small, segments. Dotted curves and surfaces are displayed on the canvas as sets of vertices; if these ones are displaced tightly enough, you can reconstruct from their displacement the shape of the curve or surface they belong to.

Finally, the input mask contains four buttons. The "Clear" button can be used to clear all text entries of the input mask.

If you click on the "Save to…" button, a file selector appears. Here you should choose a file where to save the current mathematical definition. The file can have an arbitrary name, but its extension should always be ".mdef", like in "ArbitraryName.mdef". If the file name you choose corresponds to an already existent file, you will be asked for confirmation before the file is overwritten with the information forming the current mathematical definition. If the current mathematical definition is not entirely correct, for example because of an error in the equation or since the maximum of a parameter is not greater than its minimum, then GTKMathplot will refuse to save anything in the chosen file and will show you a suitable error message.

What has been told about the "Save to…" function, can be repeated for the "Evaluate & Save" button. There are however two important differences. In the file you choose after clicking on "Evaluate & Save" GTKMathplot will not save the definition in the input mask, but a sequence of points coordinates separated by empty lines. GTKMathplot evaluates indeed the mathematical object defined in the input mask: it uses the entered information to compute the coordinates of the points forming the shape that it would draw on the canvas if you pressed the button "Display/Update graphic", instead of "Evaluate & Save". Mind that the file where the results of these computations will be stored should have extension ".gdat", like in like in "ArbitraryName.gdat".

The file produced by GTKMathplot when you request to evaluate and save a mathematical definition is compatible with GNUplot, meaning that you can visualize also in GNUplot the stored curve or surface by using either the `plot` command (for curves) or `splot` (for surfaces). To know more abot the format of these files, see the section FORMAT OF GDAT FILES.

If you click on the "Load from…" button, a file selector is shown on the screen. Here you should choose a file from where to load a previously saved mathematical definition. The files selector always shows you all files with ".mdef" extension contained in the selected directory. If you choose a file whose name does not end with the extension ".mdef", GTKMathplot will refuse to open it and display an error message.

2.1 SHORTCUTS FOR THE INPUT PAGE

  • Alt+l : Open file selector to load a mathematical definition from a file
  • Alt+s : Open file selector to save the current definition to a file
  • Alt+v : Same as clicking on the "Evaluate & Save" button
  • Alt+c : Clear the input mask
  • Alt+d : Display/Update graphic (switch to the Output page)

3 THE OUTPUT PAGE

The largest part of the output page is occupied by a canvas and a legend. In the legend GTKMathplot displays the captions of the objects drawn in the canvas; of course, no caption is written for objects which do not have an associated caption (see section THE INPUT PAGE to know how to associate a caption to a curve or surface).

If there are objects visualized in the canvas, this one shows on its top side:

  • the coordinates of the point of the plane/space which has been put to its center, and
  • the step of the grid, which is displayed if the "grid" check button is toggled on.

Besides the canvas and the legend, the output page contains several controllers to change the aspect of the graphic, and many buttons.

The three adjusters on the left of the canvas, labeled with "Longitude:", "Latitude:" and "Rotation angle:" respectively, can be used to change the point of view of the observer. Three-dimensional curves and surfaces are drawn by GTKMathplot using a sort of axonometric projection. They are visualized on the screen as an observer would see them from very far away using a telescope (a special one, which does not introduce special optic effects nor distorts the shapes, but only magnifies them). The adjusters can be used to change the observer's position while keeping fixed the distance between the observer and the observed shape; thus, the observer's position is constrained to be on a sphere with very large radius (ideally infinite) centered at the place occupied by the shape. You can move the position of the observer on this ideal sphere by changing the values of his longitude and latitude. In addition, you can change the rotation angle, which corresponds to rotate the telescope of the observer around the axis of its tube.

In two-dimensional graphic mode the adjusters for longitude and latitude are disabled, and you can change only the rotation angle. If you do it, you will see your graphic rotate around the center of the canvas.

Mind that longitude and rotation angle can take any integer value between 0 and 360 (degrees), while the latitude may vary only between -90 and 90 (degrees). To change any of these values you have to click on the arrows on the right side of the corresponding adjuster (Remark: if GTKMathplot has been built with GTK+3.0 or higher, then the arrows are replaced by the buttons "+" and "-"). The up-arrow (or "+" button) increases the value, the down-arrow (or "-" button) decreases it. The quantity of which the value is in-/decreased depends on which mouse button you press: for the left button is 1, for the middle button is 15, while the right button sets the value directly to its maximum or minimum.

Below the adjusters you can see two scales with sliders. The slider on the "Zoom" scale can be used to enlarge the visualized shapes or to make them smaller. The default value of the "Zoom" is 100%. You can increase it till to 1000% and decrease it till to 50% by dragging the slider.

The slider on the "Smoke density:" scale is enabled only in three-dimensional graphic mode. In three-dimensional mode GTKMathplot uses the so called smoke effect to simulate a three-dimensional appearance and give you a feeling of the distance of the different parts of a shape from the observer's position (which is your position, since you are the observer). The smoke effect is a trick to let your eyes see three-dimensional curves and surfaces even if GTKMathplot draws all shapes on a planar surface, the one of your screen. The trick consists in changing the color which the facets or segments forming a shape are drawn with: the parts of a shape "nearer" to you are drawn with a brilliant color, which color exactly depends on the current settings, and as the distance from your eyes increases the color drifts gradually toward a deep black. The speed at which this gradual drift takes place is controlled by the smoke density: a higher density means less brilliant colors, a lower density involves a slower drift towards the black. The default value for the smoke density (0.5) is adequate for the greatest part of use cases, you will rarely need to change it. By dragging the slider you can change the smoke density from a minimum value of 0 to a maximum value of 1.

To drag a slider you should click on it and move it while holding down the mouse button. Alternatively, you can use the arrow keys after activating the slider by navigating to it with the TAB (tabulator) key: left- and up-arrow move the slider to the left and decrease the associated value, right- and down-arrow move the slider to the right and increase the corresponding value. If you want to move in bigger steps, hold the Control key down while pressing an arrow key.

Under the sliders the Output page shows four check buttons, all contained in the same frame. They look as small squares and each of them has a label on its right side with the name of the associated option. Whenever you click on one of them, the corresponding option is toggled on/off. The check buttons can be used to enable/disable the visualization of:

  • x, y and (only in 3D-mode) z direction,
  • grid lines (in two-dimensional graphic mode) or points (in three-dimensional mode),
  • labelled tics along the x, y, and z direction,
  • discontinuity points of curves and surfaces (this is an experimental feature, works pretty well only for curves and is available only in two-dimensional graphic mode).

By default the visualization of these optional elements is disabled. Toggling a check button on(off) enables(disables, respectively) the visualization of the associated element. In two-dimensional graphic mode x and y direction (axis) are always drawn through the center of the canvas.

Under the frame with the check buttons you can see three buttons. If you click on "Back to input mask" (keyboard shortcut Alt+B), you will be moved back to the input page.

If you click on "Save as…" a file selector appears and you can choose a file where to save the graphic currently shown in the canvas. The file can have an arbitrary name, but its extension should always be either ".pdf", ".ps". ".eps", ".svg", or ".mgr", like in "ArbitraryName.mgr". The chosen extension determines the format used to save the image to the file, according to the following table:

extensionformat
.pdfPDF
.psPostscript
.epsEncapsulated Postscript
.svgStandard Vector Graphic
.mgrGTKMathplot Graphic

If the file name you choose corresponds to an already existent file, you will be asked for confirmation before the file is overwritten with the image shown in the canvas.

If you click on the "Load object from file" button you get the possibility to visualize the image previously stored in a file. When the file selector appears, you should choose the file where the image that you want to load has been saved. You can load an image either from a file containing data in GNUplot-compatible format whose name ends with the extension ".gdat", or from a file in GTKMathplot's own image format and whose name ends with the extension ".mgr". Other extensions or file formats are not accepted.

Remeber that files created by clicking on the "Evaluate & Save" button of the input mask (see section THE INPUT PAGE) are always in GNUplot's format. To know more about the format of these files, see the section FORMAT OF GDAT FILES.

GTKMathplot's own image files are only useful for debugging purposes, since their format is quite cumbersone, and they cannot be easily parsed.

Mind that, after loading one or more images in the canvas, they remain displayed as long as you do not move back to the input page and press the button "Display/Update graphic". Whenever you ask for un update, GTKMathplot redraws the contents of the canvas by considering only the mathematical shapes defined in the input page.

At the bottom of the output page a row of seven buttons is shown. They can be used to move the shapes in the canvas along the directions x, y, and (only in 3D-mode) z, or to reset their positions to the points where the shapes were placed immediately after displaying or updating the graphic for the last time. To reset the positions of the shapes you should click on the "Reset" button.

If you click on the "x+", "y+", or "z+" button, the objects drawn in the canvas are moved simultaneously in the direction of increasing x, y, or z coordinates, respectively. If you click on the "x-", "y-", or "z-" button, the shapes in the canvas are moved simultaneously in the direction of decreasing x, y, or z, respectively. How far the shapes are moved depends on which button of the mouse you press while clicking. If you click with the left mouse button, then the step of the movement is equal to the grid step written on the top of the canvas. If you click with the right mouse button, the step of the movement will be equal to 1/10 of the grid step.

Mind that in two-dimensional graphic mode the buttons for the z direction are disabled, and

  • clicking on "x+" ("x-") moves the shape to the left (right, respectively),
  • clicking on "y+" ("y-") moves the shape up (down, respectively) in the canvas.

3.1 SHORTCUTS FOR THE OUTPUT PAGE

  • Alt+l : Open file selector to load images from a file
  • Alt+s : Open file selector to save the current contents of the canvas to a file
  • Alt+b : Switch back to the Input page

4 CUSTOMIZATION

To customize user-defined settings, you have to open the "Preferences" window. You can do it by clicking first on the "Edit" menu and then on the "Preferences" entry. Alternatively, you can press the 'p' key while holding down the Control key (this is the shortcut Ctrl+P).

GTKMathplot uses several different colors to distinguish from each other the objects drawn in the canvas. In the "Preferences" window you can change the default color settings: for every two- and three-dimensional shape (mind that GTKMathplot allows you to display several mathematical shapes at a time, each one identified by a number) there is a combo which shows the color currently selected for that shape. If you click on the combo a menu opens and from there you can select another color by clicking on the entry with the color name. In the same way you can change the colors used to drawn tics, grid, and axes (x, y and z direction). Mind that the settings for two- and three-dimensional graphic mode are separate.

If you choose to display a mathematical object using the "dotted" style, the vertices forming the object are outlined using special symbols. For every two- and three-dimensional shape a specific symbol type is used: this can be plus, square, diamond, cross or bullet. In the "Preferences" window you can change also the default settings for the symbol types: if you click on the combo associated to a shape, a menu opens and you can choose a different symbol type by clicking on the corresponding entry. Mind that the settings for two- and three-dimensional graphic mode are separate.

When saving a graphic to a PDF or Postscript file GTKMathplot can choose between different paper formats. The paper format used by default is A4, but you can change it to A3, Letter or Legal by means of a menu which opens whenever you click on the combo in the "Paper format" frame.

In the "Preferences" window you can also change the default values of the following two options, both used when exporting a graphic to a PDF or Postscript file:

  • the addition of GTKMathplot copyright statement, and
  • the printing of the captions and equations of the objects appearing in the graphic.

By default both these options are active: to deactivate any of them, toggle the corresponding check button off by clicking on it. If later you want to activate an option again, it is sufficient to click on its check button another time: the button is toggled on.

After changing one or more settings, close the "Preferences" window by clicking on its "Close" button (or press the Esc[ape] key): the new settings will be applied at the current graphics and will be used later to display any new shapes, as long as you do not change settings again.

5 EXAMPLES

If you want to visualize the graphic of the function

y(x) = x2 -3x +2

(x2 is x squared) in the interval [-3, 4], i.e. for the values of x between -3 and 4, then, after starting the program, you should enter the text

x2 -3x +2

in the entry with the label "y(x) =". Type then the value -3 in the entry "Min:" and the value 4 in the entry with the label "Max:" inside the frame "Variation interval of x". You can leave the number of subintervals at its default value, i.e. 200. If you click on the "Display/Update graphic" button, the output page arises and shows the graphic of the given function. By default, grid, tics and axes are not visualized: you should toggle on the corresponding check buttons of the output page to display them. Mind that in two-dimensional graphic mode x- and y- axis are always drawn through the central point (x0, y0) of the graphic, which often does not coincide with the origin. You can read the values of its coordinates x0 and y0 on the top side of the canvas.

In this particular case x0 is 2 and y0 is 1.3; if you want to see the intersection of the graphic of the function with the x-axis going through the origin, you have to move the graphic upwards by clicking on the "y+" button, once with the left mouse button and three times with the right mouse button. Clicking on the left mouse button produces indeed a movement whose step is equal to the grid step, clicking on the right mouse button a movement with a step equal to 1/10 of the grid step.

Since in this case the grid step is 1 (as shown on the top side of the canvas) 1 left click + 3 right clicks corresponds to a step of 1.3. Observe that at each click on the "y+" button the graphic moves upwards while the value of y0 decreases.

We consider now an example in three dimensions. Assume you want to visualize the graphic of the function

z(x,y) = 3*sin(6*sqrt(x*x+y*y))

for both x and y in the interval [-2*pi, 2*pi]. * is the product operator (or multiplication sign, if you prefer), pi is the well known constant defined as ratio of a circle's circumference to its diameter, pi ~ 3.14159…, and sin is the sine function (see http://en.wikipedia.org/wiki/Trigonometric_functions). To visualize this graphic, leave the definition type set to cartesian but click on the "3D" radio button to select the three-dimensional graphic mode. Then enter the text

3*sin(6*sqrt(x*x+y*y))

in the entry with the label "z(x,y) =", type -2*pi or -2pi in the entries labeled with "Min:", and 2*pi or 2pi or +2pi in the entries with the label "Max:". Both for x and y you can leave the number of subintervals at its default value, i.e. 50. Finally, click on the "filled" radio button in the "Plot style" frame and on "Display/Update graphic" to switch to the output page and see the graphic of the function. The graphic looks like a wavy surface with many pleatings. If you look at it better, you realize that the waves are sharp cornered (increase the image to 120% to see it clearly). This is due to the fact that the default value for the number of subintervals is in this case too low to get a smooth surface. Go back to the input mask by clicking on the corresponding button of the output page, set the number of subintervals to 100 for both x and y and click again on "Display/Update graphic". The displayed surface looks now much smoother.

This example also shows that it is possible to use the constants pi and e in the definition of the minimum and maximum of a parameter. You can type actually any mathematical expressions containing these constants in the entries for minimum and maximum. GTKMathplot will first check each of them for its correctness, then will evaluate every expression and use the result as value for the corresponding minimum/maximum.

If you are interested in examples involving parametric equations read further.

5.1 PARAMETRIC EQUATIONS

We assume that in the plane is assigned a cartesian coordinate system (see http://en.wikipedia.org/wiki/Cartesian_coordinate_system). The parametric equations of a two-dimensional curve describe the curve as the set formed by the points (x(t),y(t)) when the 'time' parameter t goes from a value t1 to a value t2 > t1. Here x = x(t), y = y(t) are mathematical functions of the variable t. For example, the parametric equations of the circumference (circle) centered at the point (0,0) and having radius equal to 1 are

x(t) = cos(t)

y(t) = sin(t), with 0 <= t <= 2pi,

since the point (sin(t), cos(t)) draws exactly the unit circle centered at (0,0) while t goes from 0 to 2pi (cos is the cosine function, sin is the sine function, look at http://en.wikipedia.org/wiki/Trigonometric_functions if you do not know how they are defined).

The graphic of a function y = f(x) can always be seen as a 2D-curve described by parametric equations. If x varies in the interval [a, b] (a and b are two numbers with a < b), then the graphic of y = f(x) is the set of points with coordinates (x, f(x)) for x greather or equal than a and less or equal than b. Therefore, it can be represented through the parametric equations

x(t) = t

y(t) = f(t), with a <= t <= b.

To describe a surface (planar or three-dimensional) two parameters are needed. In GTKMathplot s and t are used as parameters. One simple example is the planar surface enclosed by the border of the circle of radius 2 centered at (0,0) and the border of the circle with the same center but radius equal to 1. This surface has parametric equations

x(s,t) = s*cos(t)

y(s,t) = s*sin(t), with 1 <= s <= 2, and 0 <= t <= 2pi.

Here s is the distance from (0,0) and t is the 'angle'.

In three dimensions three coordinates are needed to uniquely identify the position of a point (http://en.wikipedia.org/wiki/Cartesian_coordinate_system#Cartesian_coordinates_in_three_dimensions). The parametric equations of a three-dimensional curve describe the curve as the set formed by the points (x(t),y(t),z(t)) when the 'time' parameter t goes from a value t1 to a value t2 > t1. x = x(t), y = y(t), and z = z(t) are mathematical functions of the variable t. As an example,

x(t) = cos(t)

y(t) = 0

z(t) = sin(t)

are the parametric equations of the circle centered at the point (0,0,0) which lies on the plane defined by x- and z-axis and has radius equal to 1.

The parametric equations of a three-dimensional surface describe the surface as the subset of the space formed by the points (x(s,t),y(s,t),z(s,t)) when s and t vary from s1 to s2 and from t1 to t2 respectively, where s1 < s2 and t1 < t2. For example, the sphere centered at (0,0,0) with radius equal to 1 has

x(s,t) = cos(s) * cos(t)

y(s,t) = sin(s) * cos(t)

z(s,t) = sin(t), with 0 <= s <= 2pi and -pi/2 <= t <= pi/2

as its parametric equations, since the point (x(s,t),y(s,t),z(s,t)) describes exactly this sphere while s goes from 0 to 2pi and t goes from -pi/2 to pi/2. Mind that s and t are, respectively, the 'longitude' and the 'latitude' of the point (x(s,t),y(s,t),z(s,t)).

Given the function z=f(x,y), the parametric equations of its graphic over the rectangle { (x,y) | x in [a,b], y in [c,d] } are

x(s,t) = s

y(s,t) = t

z(s,t) = f(s,t), with a <= x <= b and c <= y <= d.

5.2 CAVEAT

If you set the definition type to parametric, the entries for the equations always get the labels "x(s,t) =", "y(s,t) =" and "z(s,t) =". Despite of this, if you want to draw a curve instead of a surface you can use only one parameter in the equations, and this parameter must be t.

If only the parameter t appears in the equations, then the minimum, the maximum and the number of subintervals eventually specified for the parameter s are ignored.

6 THE MATHEMATICS OF GTKMATHPLOT

Before evaluating the equations defining a mathematical object, GTKMathplot checks for their correctness. The rules according to which this check is done are the ones established in Mathematics. Refer to a high-school book if you have doubts about the right form an equation should be entered. But mind that:

  • a function should always be followed by an open round parenthesis and its argument by a corresponding closed round parenthesis (thus, log x is wrong, and log(x) is right),
  • GTKMathplot allows you to use only round parentheses, i.e. ( and ), to change the standard order according to which operators are evaluated, and
  • it allows you to omit the multiplication sign (*) between a number and a function, a number and a parameter, a number and a constant, but not in other cases. When omitting the multiplication sign, care not to leave any space between the number and the following function, parameter or constant, otherwise you will get a "Missing operator" error. Thus,

    3sin(2x+cos(5pi+3))

    is considered to be a valid expression (pi is the constant value 3.14159….) and it is evaluated like

    3*sin(2*x+cos(5*pi+3))

    but

    3 sin(x), cos(4 pi+x), (2 x +5)*(x+1), 3(x+1), (x-1)(x+1)

    will all be considered invalid expressions and cause the error "Missing operator" be issued.

When evaluating the equations defining a mathematical object, GTKMathplot recognizes the following constants:

  • pi : ratio of a circle's circumference to its diameter (= 3.14159…)
  • e : the base of the natural logarithm, also called Napier's constant (= 2.71828…)

operators:

  • + : SUM
  • - : DIFFERENCE
  • * : PRODUCT (TIMES)
  • / : DIVISION
  • % : PERCENTAGE
  • + : PLUS (UNARY OPERATOR)
  • - : MINUS (UNARY OPERATOR)
  • $ : MODULUS (THE REMAINDER OF THE DIVISION BETWEEN INTEGERS)
  • \ : DIVISION BETWEEN INTEGERS
  • ^ : POWER
  • < : LESS THAN
  • > : GREATER THAN
  • <= : LESS OR EQUAL
  • >= : GREATER OR EQUAL
  • == : EQUAL - != : NOT EQUAL
  • && : LOGICAL AND
  • || : LOGICAL OR
  • ^^ : LOGICAL XOR
  • <> : MAXIMUM(returns the value of the operand with the greatest real part)
  • >< : MINIMUM(returns the value of the operand with the smallest real part)

and functions:

  • abs : absolute value
  • neg : returns the opposite of its argument, i.e. the value of the argument with the sign changed
  • inv : inverse of a number x (= 1/x)
  • sqr : square
  • sqrt : square root
  • cbrt : cubic root
  • exp : exponential function
  • expx : returns 10 raised to its argument
  • log : logarithm
  • logx : base-10 logarithm
  • sin : sine
  • cos : cosine
  • tan : tangent
  • asin : arc sine
  • acos : arc cosine
  • atan : arc tangent
  • sinh : hyperbolic sine
  • cosh : hyperbolic cosine
  • tanh : hyperbolic tangent
  • asinh : hyperbolic arc sine
  • acosh : hyperbolic arc cosine
  • atanh : hyperbolic arc tangent
  • floor : largest integral value not greater than argument
  • ceil : smallest integral value not less than argument
  • round : rounding to nearest integer (halfway cases are rounded to 0)
  • fix : rounding to integer, towards zero (erase the decimal digits)
  • frac : frac (x) = x - fix (x)
  • Xcc : characteristic function of the segment {(x,0)| x in [0,1]}
  • Xco : characteristic function of the segment {(x,0)| x in [0,1)}
  • Xoc : characteristic function of the segment {(x,0)| x in (0,1]}
  • Xoo : characteristic function of the segment {(x,0)| x in (0,1)}
  • Xlc : characteristic function of the halfline {(x,0)| x in (-oo,0]}
  • Xlo : characteristic function of the halfline {(x,0)| x in (-oo,0)}
  • Xrc : characteristic function of the halfline {(x,0)| x in [0,+oo)}
  • step : same as above (Heaviside step function equal to 1 for x equal to 0)
  • Xro : characteristic function of the halfline {(x,0)| x in (0,+oo)}
  • erf : error function
  • erfc : complementary error function
  • dms : this function returns the measure of an angle in the form degrees, minutes and seconds (the angle is passed as argument)
  • deg : this function returns the measure of an angle in the form degrees and decimals (the angle is passed as argument)
  • rtod : radians to degrees conversion
  • dtor : degrees to radians conversion
  • fact : factorial function.

The priority order according to which operators are evaluated is the following one (from highest to lowest):

  1. + (UNARY PLUS), - (UNARY MINUS)
  2. <>, ><
  3. ^
  4. *, /, %, $, \
  5. +, -
  6. <, >, <=, >=, ==, !=
  7. &&, ||, ^^

Operators having the same priority are evaluated in the order they appear in the expression, from left to right. You can change the default order of evaluation by using parentheses, as you learned at school.

7 FORMAT OF GDAT FILES

To visualize curves and surfaces GTKMathplot has to calculate starting from their equations the coordinates of the points, segments or facets which form them. There are situations in which you could be interested to know the coordinates of the points forming a curve or surface. If this is the case, you can click on the button "Evaluate & Save" of the input page after defining a mathematical object. A file selector is shown, by means of which you can choose the file where to save the results of the computations done by GTKMathplot (see section THE INPUT PAGE). The file should have extension ".gdat", that's why I will call GTKMathplot data files also gdat files.

The data files of GTKMathplot are simple ASCII text-files: you can read and modify them using any editor (editor = program to process text-files, like emacs, vi, gedit, kate, jed, nano, nedit or the Notepad of Windoze). In addition, they are written in a GNUplot compatible format. Thus, the objects stored in a gdat file can also be visualized in GNUplot using either the `plot` command (for curves) or `splot` (for surfaces).

To understand the contents of a gdat file and eventually to modify it, you need to know how a gdat file should be formatted.

In general, a gdat file contains a list of points coordinates separated by empty lines. Every non empty line stores the coordinates of a single point. To mark the end of a set of points referring to the same object two empty lines are used. A gdat file can also contain comments: a line of comment starts with the '#' character, eventually preceded by one or more empty spaces. Comments starting with two '#' are special, since they can be used to activate specific drawing options or to set object captions.

The exact format of a gdat file depends on the type of the object(s) saved in it.

Every two-dimensional curve of a graphic corresponds to a list of couples of floating-point values. Each of these couples is placed on its own line. Within a couple, numbers are separated by empty spaces (tabs or blanks). Every couple of numbers represents a point of the curve trough its absolute coordinates x and y; thus, every list of couples of numbers is a list of points of a curve.

Since there is a one-to-one correspondance between the list of the points of a curve and the set of the values of the parameter at which the parametric equations of the curve are evaluated, every list of points is formed by a number of elements equal to the number of values assigned to the parameter (which in its turn is equal to the number of subintervals plus one). To be precise, if the parametric equations of a two-dimensional curve are given by ( 1 )

x = x(t)

y = y(t),

where the minimum of the parameter 't' is 'a', its maximum is 'b', and 'n' is the number of subintervals, then the curve is described by the list:

x(a)y(a)
x(a + (b-a)/n)y(a + (b-a)/n)
x(a+2*(b-a)/n)y(a+2*(b-a)/n)
x(a+3*(b-a)/n)y(a+3*(b-a)/n)
..
..
..
x(a+(n-1)*(b-a)/n)y(a+(n-1)*(b-a)/n)
x(b)y(b)

At the end of the list of points representing a curve two (mandatory) empty lines should come in order that GTKMathplot can establish where the description of the curve ends and the next object starts. The only exception to this rule is the case when no other object comes after the curve: then the list of points should be followed either by one empty line, or by nothing at all (the file ends).

What has been told for a two-dimensional curve can be repeated for a three-dimensional one, except that every non-empty line contains three floating-point values separated by empty spaces, instead of two. To be precise, if the parametric equations of a three-dimensional curve are given by

x = x(t)

y = y(t)

z = z(t),

where the minimum of the parameter 't' is 'a', its maximum is 'b', and 'n' is the number of subintervals, then the curve is described by the list:

x(a)y(a)z(a)
x(a + (b-a)/n)y(a + (b-a)/n)z(a + (b-a)/n)
x(a+2*(b-a)/n)y(a+2*(b-a)/n)z(a+2*(b-a)/n)
x(a+3*(b-a)/n)y(a+3*(b-a)/n)z(a+3*(b-a)/n)
...
...
...
x(a+(n-1)*(b-a)/n)y(a+(n-1)*(b-a)/n)z(a+(n-1)*(b-a)/n)
x(b)y(b)z(b)

Every two-dimensional surface of a graphic corresponds to a sequence of lists of couples of floating-point values. The couples of floating-point values forming a list are placed each on its own line. Within a couple, numbers are separated by empty spaces (tabs or blanks). Every couple of numbers represents a point of the surface trough its absolute coordinates x and y, and each list of couples of numbers represents a curve on the surface. To be more precise, given the surface with parametric equations ( 1 )

x = x(s,t)

y = y(s,t),

where 's' goes from 'a' to 'b', 't' varies from 'c' to 'd', and 'n' is the number of subintervals of 't', for every fixed value of

t = c, c + (d-c)/n, c + 2*(d-c)/n, …, c+(n-1)*(d-c)/n, d

there is in the data file a list of points corresponding to the curve with parametric equations

x = x(s,t)

y = y(s,t), with a <= s <= b.

Each of these lists is separated from the next one by one (mandatory) empty line. To mark the end of a surface the last list of points should be followed by two empty lines. The only exception to this rule is the case when no other object comes after the surface: then the last list should be followed either by one empty line, or by nothing at all (the file ends).

What has been told for a two-dimensional surface can be repeated for a three-dimensional one, except that every non-empty line contains three floating-point values separated by empty spaces, instead of two. A three-dimensional surface is described indeed by a set of three parametric equations:

x = x(s,t)

y = y(s,t)

z = z(s,t) .

Footnotes:

1 Mind that curves and surfaces defined by cartesian equations can always be redefined through parametric equations, see EXAMPLES, subsection PARAMETRIC EQUATIONS.

Author: Ivano Primi <ivprimi (at) libero (dot) it>

Date: 2013-05-25 14:51:38 CEST

HTML generated by org-mode 6.33x in emacs 23