FuncPlotter 4.1 : Manual

Table of contents

You must have JavaScript enabled in your browser to generate the table of contents.

1  Introduction

FuncPlotter is a Java application for displaying two-dimensional plots of explicit functions in one variable (ie, functions of the form y = f(x), where f(x) is an arbitrary function composed from a set of common mathematical operations). It is distributed under version 3 of the GNU General Public License; for details, see the file license.txt that is included in the FuncPlotter distribution.

FuncPlotter has the following features:

The website of the FuncPlotter project is at http://funcplotter.sourceforge.net/ .

1.1  End of support for FuncPlotter as an applet

Previous versions of FuncPlotter could be run as both an application and an applet. From version 4.0, FuncPlotter can no longer be run as an applet.

2  Requirements

FuncPlotter requires a Java runtime environment that supports Java SE 8 (Java 1.8), such as Oracle's Java Runtime Environment (JRE), version 8 or later.

3  Contents of the distribution

The following files are included in the distribution:

funcPlotter.jar The executable JAR (Java archive) file of the FuncPlotter application.
funcPlotter-config.xml The configuration file for FuncPlotter, which contains the default values for the configuration properties.
license.txt A copy of the licence under which FuncPlotter is distributed (GNU General Public License, version 3).
dtd/functionList.dtd The DTD (document type definition) of a FuncPlotter document in XML format. (FuncPlotter does not use the DTD; it is provided only for reference.)
example/example.xml
example/example.txt
Examples of a FuncPlotter document in the two formats supported by the application. The examples both contain the same set of arbitrarily chosen functions.
images/funcPlotter.png
images/funcPlotter.ico
A 48×48-pixel PNG image and a 48×48-pixel Windows-format icon that can be used to customise a desktop icon for the FuncPlotter application.
manual/manual.html
manual/images/*.png
manual/scripts/*.js
manual/style/*.css
This manual, its image files, scripts and stylesheets. Any modifications to the manual for the latest version of FuncPlotter will appear in the online version of the document, to which there is a link on the FuncPlotter website.

4  Installing and running FuncPlotter

FuncPlotter consists of a single JAR (executable Java archive) file, funcPlotter.jar and a configuration file, funcPlotter-config.xml, which contains user preferences. The use of the configuration file is optional but recommended. The application can be installed in two ways: with the FuncPlotterInstaller program or by copying files from the .zip or .tar.gz archive of the FuncPlotter executable distribution.

4.1  Executing a JAR file

Both the FuncPlotter application and the installer are executable JAR (Java archive) files that require a Java runtime environment, which includes a program named java for running JAR files — a Java launcher. When you install a Java runtime environment, it may create an association on your system between JAR files and its Java launcher. (Oracle's Java runtime environment on Windows associates JAR files with an additional Java launcher named javaw that runs without a console window.) If so, or if you have created the association yourself, you will be able to run a JAR file directly (eg, by double-clicking on an icon of the JAR file in a file manager). If not, you can run a JAR file by invoking the java launcher tool from a command line and supplying the location of the JAR file as an argument. There are examples below of command lines for running the JAR file of the FuncPlotter application under Linux/UNIX and Windows.

4.2  Installing FuncPlotter

4.2.1  Installation with the installer program

The installer is an executable JAR (Java archive) file that requires the same Java runtime environment as the FuncPlotter application itself. It can be run directly or indirectly in the ways described above.

In the opening display of the installer, you can choose the components that you want to install and the directories in which they will be installed. It is recommended that you install the configuration file in its default directory; the default directories of the other components should also be suitable for most users. If you install the executable file and the configuration file, a file named funcPlotter-properties.xml will be generated and written to the same directory as the executable file to inform the FuncPlotter application of the location of the configuration file. This file is required only if the configuration file was not installed in the default directory.

Any existing file that has the same name as an installed file will be overwritten without warning except for a configuration file, whose properties will be preserved if they conflict with the properties of the new file.

The final display of the installer has a Show files command that displays a list of files that were installed. If the installation was successful, you might want to keep a list of the files so that you will know where to find them when you uninstall FuncPlotter, which does not have an automated means of uninstallation. If the installation failed, you might want to remove any files that were installed.

4.2.2  Direct installation

The direct installation of FuncPlotter consists simply of copying the JAR file and, optionally, the default configuration file to suitable locations on your system. If the configuration file is not installed in its default directory, you will need to inform the FuncPlotter application of the location of the configuration file, which can be done either on the command line or in a properties file.

4.3  Running FuncPlotter

The FuncPlotter application is an executable JAR (Java archive) file that requires a Java runtime environment. The JAR file can be run directly or indirectly in the ways described above.

If you run the FuncPlotter application from a command line, the command line may contain configuration properties, including the location of a configuration file. The following subsections describe how to run FuncPlotter from a command line.

4.3.1  Running under Linux/UNIX

Assuming that your PATH environment variable includes the path to the java tool and that you have copied funcPlotter.jar to the directory /home/slothrop/bin/funcplotter/, the command

java -jar /home/slothrop/bin/funcplotter/funcPlotter.jar

will run the FuncPlotter application.

The file funcPlotter.png can be used as the icon for the FuncPlotter application.

4.3.2  Running under Windows

The FuncPlotter application does not require a console window, so you can use the javaw launcher rather than the java launcher unless you particularly want a console window. Assuming that your PATH environment variable includes the path to the javaw tool and that you have copied funcPlotter.jar to the directory C:\Program Files\FuncPlotter\, the command

javaw -jar "C:\Program Files\FuncPlotter\funcPlotter.jar"

will run the FuncPlotter application.

The file funcPlotter.ico can be used as the icon for the FuncPlotter application.

4.5  Uninstalling FuncPlotter

FuncPlotter does not have an automated means of uninstallation. To remove it from your system, delete the file funcPlotter.jar from the location to which it was written when you installed FuncPlotter. If you want to remove FuncPlotter completely, you should also delete the configuration file, funcPlotter-config.xml, which may be at its default location, and any other files that were installed (eg, the manual).

5  Configuration

When it starts up, FuncPlotter is configured with configuration properties that are read from two sources: the command line that is used to run the Java launcher and a configuration file whose location may be explicitly specified. If the same property is specified on the command line and in a configuration file, the value from the configuration file takes precedence.

The recommended method of setting the properties in a configuration file is with the Options > Preferences command. For command-line properties, which must be edited manually, the form of the property values is given in an appendix, and it can also be inferred by generating a configuration file with the desired values and inspecting the contents of the file.

5.1  Command-line properties

When FuncPlotter is run by means of the java launcher, configuration properties may be specified on the command line using the standard Java form -Dname="value"; eg, -Dapp.plot.size="480, 480". (The quotation marks around the value aren't necessary if the value doesn't contain spaces.) FuncPlotter's command-line configuration properties all have the prefix app. . A list of all the properties that are recognised by FuncPlotter is given in an appendix.

One particular property, app.configDir, is used to specify the directory that contains a configuration file, as described below. The value of the app.configDir property may contain special constructs for system properties, environment variables and the user's home directory.

5.2  Configuration file

The configuration file is named funcPlotter-config.xml. FuncPlotter doesn't require a configuration file: it uses a default value for any configuration property that is missing from the source(s) of configuration. Similarly, if it finds a property value to be invalid, FuncPlotter will display a message to this effect and use the default value of the property. If the configuration file contains a property that was specified on the command line, the value from the configuration file is used.

If the configuration has changed when you exit the application normally (ie, using the File > Exit command or an equivalent), FuncPlotter will save its configuration to a configuration file. If a configuration file was read on startup, it will overwrite that file; otherwise, it will write a configuration file to the default directory described above, unless the value of the app.configDir property was an empty string.

A configuration file can be written explicitly with the Save configuration command within the Preferences dialog.

5.2.1  Location of the configuration file

When it starts up, the FuncPlotter application is informed of the location of the configuration file with the app.configDir property, which may be set in two ways:

If the app.configDir property is set both in the properties file and on the command line, the value in the properties file takes precedence.

The funcPlotter-properties.xml file is normally written by the installer. If you create the file manually, it should have the following form, with the example pathname replaced by the actual pathname:

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties>
<entry key="app.configDir">/home/slothrop/.blankaspect/funcPlotter</entry>
</properties>

If the configuration file were located in a directory named config in the user's home directory, the sample command lines given above would become:

Linux/UNIX: java -Dapp.configDir="~/config" -jar /home/slothrop/bin/funcplotter/funcPlotter.jar
Windows: javaw -Dapp.configDir="~/config" -jar "C:\Program Files\FuncPlotter\funcPlotter.jar"

The existence and value of the app.configDir property determines the locations that are searched for a configuration file:

6  The display

6.1  Document windows

FuncPlotter uses a tabbed document interface to display multiple documents. This kind of interface has a single tabbed window in which only one document — referred to as the current document — is visible at any one time. You can select a document by clicking on its tab, or you can select a document from the alphabetically ordered list that is displayed by clicking on the down-arrow button at the right of the tab bar. You can move between documents by pressing Ctrl+PageUp and Ctrl+PageDown.

You can copy x and y intervals between documents using the command Edit > Copy intervals to other documents.

The size of the main window cannot be changed directly, but it can be changed indirectly by modifying the dimensions of the plot and the dimensions of the list of functions. Changes to these properties will not take effect until the next time that FuncPlotter is run. Some of the other configuration properties (eg, the fonts) may also affect the size of the main window.

6.2  Plot panel

FuncPlotter's display consists of a main window divided into several panels. On the left side of the main window is the plot panel, which contains plots of the current set of functions. By default, the functions are drawn over a grid of horizontal and vertical lines, but the grid can be hidden from view. The scales of the horizontal dimension (the x scale) and the vertical dimension (the y scale) are always linear.

Like the other numeric values that are displayed by FuncPlotter, the scale markings are subject to rounding. The most important consequence of rounding is that, while the displayed value of the scale marking is always the nearest value (after rounding) for the x or y pixel coordinate of the scale marking, there may be another pixel coordinate that is nearer to the displayed value of the scale marking. If, as a result of rounding, two or more consecutive scale markings have the same value, the duplicate values are not displayed. The text of an x-scale marking is either omitted or truncated according to the plot.truncateXScaleText configuration property if it would overlap the text of the previous marking. The text of a y-scale marking is truncated if it is too wide to be displayed in full. If the text of a scale marking is truncated or omitted, the full text is displayed when the mouse cursor is moved over the region of the truncated or omitted text.

In addition, the following aspects of the plot panel are configurable:

Although the plot panel has no scroll bars, the plot can be scrolled by four methods:

  1. Click on the scroll buttons in the scroll/zoom panel.
  2. Rotate the mouse wheel when the mouse cursor is over the plot panel.
    The normal (forwards–backwards) rotation of the mouse wheel scrolls the plot in the vertical direction. If the Ctrl key is pressed while the mouse wheel is rotated, the plot is scrolled in the horizontal direction.
  3. Hold down the left mouse button and drag the mouse.
  4. Press the arrow keys when the plot panel has keyboard focus.
    If the plot panel has focus, its border is two pixels wide, in the colour denoted by the plot.colour.focusedBorder configuration property; otherwise, its border is grey and one pixel wide.

The unit of scrolling is half a grid division in each direction.

To maintain consistency between actual and displayed interval values when the plot panel is scrolled or zoomed, the actual x and y intervals are updated to values that are as close as possible to the intervals that are displayed in the interval fields (see below). The plot.numFractionDigits configuration property determines the granularity of an interval and affects the ability to scroll or to zoom: the more fraction digits, the further you are able to zoom in. As you zoom in, the scrolling increment (half a grid division) approaches the difference between distinct values in the interval. Near the limit, scrolling behaviour becomes irregular, and the ability to scroll eventually disappears.

6.2.1  How functions are plotted

FuncPlotter plots a function y = f(x) by evaluating y for the values of x that correspond to pixel divisions on the current x interval, and drawing line segments between successive points, (xnyn) and (xn+1yn+1).

FuncPlotter uses the mathematical operations and methods of the Java language to evaluate f(x). The Java operations and methods, which are based on the IEEE 754 standard, sometimes result in an infinity (positive or negative) or a Not-a-Number (NaN) value. For example, division of a finite number by zero results in a signed infinity, whereas taking the natural logarithm of a negative number with the method java.lang.Math.log() results in NaN. When evaluating an expression, an NaN that appears as an intermediate result is transmitted to the final result. If the value of yn = f(xn) is an NaN, FuncPlotter does not draw a line segment between (xn−1yn−1) and (xnyn) or between (xnyn) and (xn+1yn+1). This behaviour is usually what you would expect; for instance, the plot of the function y = ln x is confined to the right of the y axis.

Expressions for f(x) that involve operations such as acos or sqrt are plotted only for the principal values of f(x) that are returned by the underlying Java methods. (In the case of y = acos x, y is confined to the range [0, π], whereas for y = sqrt x, y is confined to the positive root of x.)

6.2.2  Problems inherent in the method of plotting functions

Two significant problems in the way in which FuncPlotter plots functions have come to light so far. These problems are not bugs but artifacts — unwanted consequences of the design of the software. The join-the-dots approach works adequately for most functions, but periodic functions and functions with an infinite discontinuity each have a problem associated with them.

When plotting periodic functions, FuncPlotter exhibits the problem of aliasing, which occurs when the sample period — the difference between successive x values at which the function is evaluated — is greater than or equal to twice the period of the function. This effect can be observed by plotting a simple periodic function, such as y = sin x, and repeatedly reducing the magnification. The problem of aliasing could be mitigated by oversampling, but it would still occur eventually, and the oversampling would increase the computational burden of plotting a function.

Functions that have an infinite discontinuity — eg, y = (x + 1) / (x − 1), which has a vertical asymptote at x = 1 — suffer from a "cropped tail": the plot of the function stops some way short of its (unattainable) goal of positive or negative infinity. If xd is a value of x in the x interval of the plot at which there is an infinite discontinuity, {xn} is the set of values of x for which f(x) is evaluated by FuncPlotter when plotting y = f(x), and xnd is the member of {xn} that is nearest to xd, then the "cropped tail" artifact occurs when f(xnd) lies within the y interval of the plot or when f(xnd) is NaN. The severity of the problem is determined by how close xnd is to xd; hence, the problem is sensitive to changes in the x interval. (For instance, a "tail" may appear and disappear as a plot is scrolled horizontally.) Like the problem of aliasing, the problem of infinite discontinuities could be mitigated by oversampling.

Functions that are periodic and have infinite discontinuities (eg, y = sec x) don't look too good when drawn by FuncPlotter at low magnification.

6.3  Function panel

At the top right of the display is a panel containing a list of the functions that comprise the current document, and a group of buttons that relate to the list of functions.

Each row of the function list contains an expression for f(x) next to a sample of the colour in which the function is plotted; details of the syntax and semantics of expressions are given in the section on expressions. An expression is truncated with an ellipsis if it is too long to fit within the width of the function list. If an expression is truncated, the full expression can be displayed in a pop-up window by holding down the Ctrl key and pressing the left mouse button while the mouse cursor is over the expression.

If the function is hidden with the Hide command, the colour sample is absent. If the function is obscured because another function has been highlighted with the Highlight command, the colour-sample box is empty (ie, only the border of the box is drawn.) The colour of each function can be edited. The default function colours are configurable.

Functions are plotted in reverse order from the order in which they appear in the list. This means that the function at the top of the list will be drawn on top of all the functions that are below it in the list. The position of a function in the list can be changed by dragging the function up or down the list with the mouse, or by pressing Ctrl+Shift+Up or Ctrl+Shift+Down when the list has keyboard focus. The order of functions in the list can be reversed with the Edit > Reverse order of functions command.

Only one function in the list can be selected at a time. Double-clicking on a function in the list will bring up an Edit function dialog for that function.

The size of the list of functions — the number of columns and rows in the viewable region of the list — is specified as a configuration property, function.listSize.

Immediately below the list of functions is a group of buttons that can be used to issue function-related commands.

6.4  Mouse cursor coordinates

Below the function panel is a panel containing a single field labelled Cursor. When the mouse cursor is over the plot panel, this field displays the x and y coordinates at the mouse cursor. To conserve horizontal space, the coordinates are displayed in two rows. The coordinates are formatted according to the scheme for numeric values.

6.5  Controls

Below the cursor panel is a panel in which the x and y intervals of the plot panel are displayed. The intervals, which are set implicitly by scrolling and zooming the plot panel, can also be set explicitly by entering values in the interval fields. To update an interval after editing a value in an interval field, press the Return key while one of the interval fields has keyboard focus (ie, the text cursor is within an interval field). The minimum and maximum values of the endpoints of both the x and y intervals are 1.0E−100 (10−100) and 1.0E100 (10100) respectively.

Below the intervals panel is a panel containing scroll buttons, zoom buttons and drop-down lists for selecting the zoom factor. The arrow buttons scroll the plot in the direction of the arrow; the circle button centres the plot around the origin, (0, 0). The zoom buttons for each dimension have a zoom factor associated with them, which can be selected from a list of preset values using the drop-down list beside each pair of zoom buttons.

6.6  Minus sign

In components of the main window and the function dialog that is displayed in response to the Add and Edit function commands, a minus sign in numerical values and expressions is displayed with (in order of preference) a minus sign (U+2212) or en dash (U+2013) character if one of those characters can be displayed in the component's font. If neither character can be displayed, a hyphen-minus (U+002D) character is used.

6.7  Function dialog

The Add and Edit function commands bring up a dialog box in which you can edit the expression for f(x) and select the colour in which the function is plotted.

In the dialog, the colour-selection button invokes a colour-selection dialog. If the function list is not empty, the colours of the current functions are displayed in small buttons beside the colour selection button, to allow you to set a function's colour to the same colour as another function.

The Copy, Paste and Clear commands perform copy, paste and delete operations on the entire contents of the expression field. The Copy command copies the contents of the Expression field to the clipboard; the Paste command replaces the contents of the Expression field with text from the clipboard; the Clear command deletes the contents of the Expression field.

7  Commands

7.1  File menu

The commands in the File menu are mostly standard and self-explanatory, but note the following:

7.2  Edit menu

7.2.1  Undo/Redo

The edits that you make to a document — the changes that you make to a document's functions, intervals or comment — can be undone and redone. The edits to a document are stored in a list called the document's history. The size of this list is limited by the general.maxEditListLength configuration property. The following edits are stored in a document's history:

Changes to an interval in one dimension (eg, scrolling or zooming) are merged if they occur within 0.5 seconds of each other.

The Undo command reverses the last change to the current document.

If an edit is undone with the Undo command, it can subsequently be restored with the Redo command provided that no other edits have been made since it was undone. If general.clearEditListOnSave configuration property is true, the history of edits is cleared when a document is saved.

7.2.2  Clear edit history

The Clear edit history command clears the history of edits to the current document. The command may be used to make more memory available if a "Not enough memory" error occurs.

7.2.3  Comment

A document may contain a single document comment, which is saved with the document. The Comment command brings up a dialog box in which the document comment can be viewed and edited. Any leading and trailing space is removed from text that is entered in the dialog.

For documents that are saved in XML format, the document comment is distinct from XML comments, which are not preserved in a document that is opened and subsequently written by FuncPlotter. For documents that are saved in text format, a document comment uses the general convention for comments in that format, but in a particular way; see Text format for details.

7.2.4  Reverse order of functions

This command reverses the order of the functions in the function list of the current document.

7.2.5  Copy intervals to other documents

The Copy intervals to other documents command is enabled only when more than one document is open. The purpose of this command is to copy the x and y intervals of the current document to some or all of the other open documents. A dialog box is displayed in which the target documents — the documents whose intervals you wish to set to those of the current document — can be selected.

7.3  View menu

7.3.1  Grid

The Grid option controls whether a grid is drawn in the plot panel. The command to toggle the grid also appears in the pop-up menu.

7.4  Options menu

7.4.1  Preferences

The Preferences command brings up a tabbed dialog box in which the configuration properties of FuncPlotter can be edited. The configuration properties are global; that is, they apply to all documents. The properties on the various tabbed pages are described below.

Some of the configuration properties in the Preferences dialog are edited with a spinner — a graphical component that consists of a text field adjacent to a pair of small buttons. The value in the text field may be edited manually, or it may be incremented and decremented by one of the following methods:

Using the last two methods, the amount by which the value is incremented or decremented can be modified by holding down the Ctrl, Shift or Ctrl+Shift keys, which correspond respectively to increments of 10, 100 and 1000.

General
Default file type
The value of this property is used when the type of a document — XML or text — is unknown (ie, when opening a document or saving a new document): the file type in the file-selection dialog box is set to the default value. The file type may be changed in the file-selection dialog box each time a document is saved.
The default value is XML.
New document on startup
If you select Yes, a new (ie, empty) document will be displayed when FuncPlotter starts up.
The default value is No.
Save function colours in document
If you select Yes, the colour of each function will be included in the function definition when you save a document. If you select No, the colour of each function will be omitted from the function definition when you save a document, and the functions will be assigned their default colours when the document is opened. If you select Ask, you will be asked whether you want to save the function colours each time you save the document.
The default value is Yes.
Display UNIX-style pathnames
If you select Yes, pathnames are displayed in a reduced "UNIX style" in some parts of the GUI. A pathname is converted from its platform-specific form in two steps:
  1. If the pathname starts with the user's home directory, the latter is replaced by '~'.
  2. The file-separator character ('\' on Windows systems) is replaced by '/'.
The default value is No.
Select text when focus is gained
If you select Yes, all the text in a text field will be automatically selected when the field gains keyboard focus, regardless of how the focus is transferred.
The default value is Yes.
Save location of main window
If you select Yes, the location of the main window on the screen will be saved to the configuration file when you exit the application. The next time that FuncPlotter is run, its main window will be positioned at the previously saved location.
The default value is Yes.
Maximum size of edit history
This is the maximum number of edits that can be stored in a document's history for use by the Edit > Undo and Edit > Redo commands. The history of edits can be explicitly cleared with the Edit > Clear edit history command.
The default value is 200.
Clear edit history on save
If you select Yes, a document's history of edits (see Edit > Undo/Redo) is cleared when the document is saved.
The default value is No.
Appearance
Look-and-feel
The look-and-feel (LAF) can be selected from a list of the LAFs that are available on the current system.
The default value is the cross-platform LAF, currently called Metal.
Text antialiasing
This determines the kind of antialiasing that is performed when text is drawn in custom or partially customised user-interface components (eg, in drop-down lists). Note that antialiasing is only a hint in Java; the implementation is not required to perform the chosen antialiasing.
This property has no effect on the antialiasing of text in standard UI components, such as labels and menus, which is determined by the Java implementation and the desktop setting for text antialiasing (often referred to as "font smoothing"). You can override the desktop setting with the unsupported system property awt.useSystemAAFontSettings.
The text antialiasing property can have the following values:
Default
The desktop setting for text antialiasing (font smoothing) is used, if the Java implementation recognises one; otherwise, no antialiasing is performed.
None
No antialiasing is performed.
Standard
This selects pixel-oriented antialiasing rather than subpixel antialiasing. It is suitable for non-LCD displays.
Subpixel, horizontal RGB
Subpixel, horizontal BGR
Subpixel, vertical RGB
Subpixel, vertical BGR
These four options are intended to optimise the rendering of text for LCD displays using subpixel antialiasing with subpixels in the chosen arrangement. Selecting an option that does not correspond to the actual arrangement of subpixels in your LCD display may result in blurred text. The most common arrangement of subpixels is horizontal RGB.
The default value is Default.
Plot
Plot size
These are the dimensions of the plot (width × height) in pixels.
The range of each dimension is 128 to 2048; the default dimensions are 480 × 480.
Show grid
If you select Yes, a grid is displayed by default in the plot panel. (The x and y axes are always displayed.) The grid can be toggled on and off for each document using the View > Grid command, which is also available from the pop-up menu.
The default value is Yes.
Maximum number of fraction digits
This is the maximum number digits in the fractional part of displayed numeric values — scale markings, cursor coordinates and the endpoints of x and y intervals. Values that have more than the maximum number of digits in the fractional part are rounded away from zero; that is, the digit immediately before any discarded digits is incremented if the first discarded digit is greater than or equal to 5. Thus, for example, if the maximum number of fractional digits were 3, the value −3.6385 would be rounded to −3.639, and 0.4475 would be rounded to 0.448.
The range of the value is 1 to 12; the default value is 5.
Number of y-scale digits
This property determines the width of the left margin of the plot in which the y scale is displayed. The width allowed for the y-scale text is the total width of the number of '0' (zero) characters specified by this property.
The range of the value is 4 to 20; the default value is 8.
Fixed-point exponent range
Numeric values — scale markings, cursor coordinates and the endpoints of x and y intervals — whose exponent lies between the (inclusive) bounds of this property are displayed in fixed-point format (eg, −0.0123 and 279936.45). Values whose exponent lies outside the bounds are displayed in scientific notation (eg, −1.23E−4 and 2.799364E7).
The range of each bound is −12 to 12; the default bounds are −3 and 6.
Normalise scientific notation
This property determines whether numeric values — scale markings, cursor coordinates and interval endpoints — are normalised or denormalised when they are displayed in scientific notation.
If you select Yes, numeric values that are displayed in scientific notation (ie, values whose exponent lies outside the fixed-point exponent range) are normalised: the radix point and exponent are adjusted so that there is only one digit in the range 1..9 before the radix point.
If you select No, numeric values that are displayed in scientific notation are denormalised: the values are displayed with a fixed exponent, which is the exponent of the minimum of the absolute endpoints of the interval. For example, if the x interval were [−5.0E8, 1.25E9], all x values would be displayed with the exponent 8. (The upper endpoint would be displayed as 12.5E8.)
The default value is Yes.
Truncate x-scale text
If you select Yes, the text of an x-scale marking of the plot is truncated if it would overlap the text of the previous marking. If you select No, the text of an x-scale marking is omitted if it is too wide. In either case, the full text is displayed when the mouse cursor is moved over the region of the truncated or omitted text.
The default value is Yes.
Plot colours
These are the colours of various elements of the plot panel.
Function
Document directory
This is the directory that is initially displayed by the file-selection dialog when opening or saving a document.
The default value is the directory denoted by the Java system property user.home. If your system supports it, you can drag and drop a directory object (eg, from a file browser) on to the Directory field, or copy a directory object from a file browser to the clipboard, and paste it into the field. The pathname specified in the Directory field can contain special constructs for system properties, environment variables and the user's home directory.
Function list size
These are the dimensions of the viewable region of the list of functions (columns × rows). The width of a column is the width of a '0' (zero) in the main font. If the number of viewable rows is less than the maximum (20), the list has a vertical scroll bar.
The range of the number of columns is 8 to 80; the default value is 32.
The range of the number of rows is 1 to 20; the default value is 12.
Obscured colour
This is the colour that is used to plot the functions that are obscured when a function is highlighted with the Highlight function command. If the colour is enabled with the Obscured colour check box, a highlighted function is emphasised by plotting the other functions in a document in the colour set with the button adjacent to the check box. If the colour is disabled, functions are obscured by hiding their plots.
Default function colours
These are the default colours of functions in the function list.
Fonts
These are the fonts that are used in FuncPlotter's display. The Plot font is the font that is used for the scale markings of the plot panel. Remember that font names may be platform-dependent, so that a configuration that specifies font names may not work across platforms.
The main font is used for various components including labels (static text), menus, buttons and list boxes.
The text field font is used for text fields, spinners and some other text components.
The combo box font is used for drop-down lists and related components.
The plot font is used for the text in the plot panel.
The default values of all the font properties except for the size of the plot font (10-point) are those of the default fonts for the platform and look-and-feel. A default font size is specified by leaving the Size field empty (the minimum position on the spinner). A default font is used if no font name is specified in FuncPlotter's configuration or if the named font is not available.

Some of the configuration properties will take effect when the Preferences dialog is accepted (by closing it with OK); other properties (eg, the look-and-feel and fonts) will not take effect until the next time that FuncPlotter is run.

The configuration file is normally saved automatically when FuncPlotter exits, if the configuration has changed. The Save configuration command in the Preferences dialog can be used to save a configuration file explicitly.

7.4.2  Show full pathnames

The Show full pathnames option controls whether the full pathname of the current document or only its filename is displayed in the title bar of the main window.

7.5  Function-related commands

The function panel, below the list of functions, contains six buttons. The buttons issue commands that relate to the list of functions. The commands are also available from a pop-up menu, which is activated in a system-dependent manner. (For example, on Windows systems, the pop-up menu is displayed when the right mouse button is released.)

7.5.1  Add

This command brings up a dialog box in which a new function can be defined. The new function is added to the end of the function list.

7.5.2  Edit

This command brings up a dialog box in which the selected function can be edited. When the function list has keyboard focus, this command can be issued by pressing the Return key.

7.5.3  Copy

This command copies the expression of the currently selected function to the system clipboard. When the function list has keyboard focus, this command can be issued by pressing Ctrl+C.

7.5.4  View

This command brings up a small menu containing two check-box items: Highlight and Hide.

7.5.4.1  Highlight

This command toggles the highlighting of the selected function. The highlighting leaves the plot of the selected function unchanged but obscures the plots of all the other functions in the document. The way in which the plots are obscured depends on the function.obscuredColour configuration property: if the obscured colour is enabled, the plots are drawn in that colour, otherwise the plots are hidden. Only one function can be highlighted at a time; highlighting a function while another function is highlighted will switch off the highlighting of the first function. The command is enabled only if the document contains more than one function. It can also be issued by pressing Ctrl+Space when the function list has keyboard focus.

7.5.4.2  Hide

This command toggles the visibility of the plot of the selected function. It operates independently of any highlighting.

7.5.5  Delete

This command deletes the selected function. When the function list has keyboard focus, the selected function can be deleted by pressing Delete, which requires that you confirm the deletion, or Shift+Delete, which deletes the function immediately.

7.5.6  Clear

This command deletes all functions from the list.

7.6  Opening files with drag-and-drop

If your system supports the feature, you can open files by dragging them and dropping them onto the area of FuncPlotter's main window below the menu bar. This is equivalent to opening the files with the File > Open file command. Multiple files can be opened in this way, subject to the constraint that a maximum of 64 documents can be open simultaneously in FuncPlotter.

8  Numeric values

FuncPlotter uses the double floating-point type of the Java language for the numbers that are involved in evaluating and plotting functions. The Java double type is based on the double-precision (64-bit) floating-point format of the IEEE 754 standard, which has 53 bits of precision in the significand. This precision is adequate for the purpose for which FuncPlotter is intended, and operations on double-type numbers are relatively fast on processors with a floating-point unit that implements the IEEE 754 double-precision format.

Even with the precision of a Java double, many of the numeric values that are displayed by FuncPlotter will be approximations. (Remember that the binary representation of decimal fractions is usually inexact: the decimal fraction 0.1, for example, cannot be represented by a binary fraction of finite length just as the fraction 1/3 cannot be represented by a decimal fraction of finite length.)

Real numbers — or, more correctly, approximations to real numbers — appear in three places in FuncPlotter's display:

For consistency, all three uses are subject to the same constraints and are displayed in the same format, which can be controlled to a limited extent by configuration properties.

The maximum precision (aka the number of "significant figures") of displayed numbers is limited to 12 digits.

The maximum number of fraction digits (aka "decimal places") in displayed numbers is determined by the plot.numFractionDigits configuration property.

Numbers are displayed in one of two formats:

The format — fixed-point format or scientific notation — is determined by the exponent of the number and the plot.fixedPointExponentRange configuration property: if the exponent of the number lies within the inclusive fixed-point exponent range, the number is displayed in fixed-point format. (The exponent that is used in this determination is the exponent of the number in scientific notation, normalised or denormalised according to the plot.normaliseScientificNotation configuration property.)

9  Expressions

An expression consists of operands and operations, optionally separated by spaces. Subexpressions can be placed within parentheses, '(' and ')', to override the precedence of operations or to make an expression easier to read.

9.1  Operands

Simple operands are of three types:

variable x The independent variable.
symbolic constant e The base of natural logarithms.
pi The ratio of the circumference of a circle to its diameter, π.
numeric constant A string that is a valid representation of a decimal number in the approximate range 10−308 to 10308, and composed only of the digits '0'..'9' and the characters '+', '', '.', 'E', 'e'. Numbers can be in exponential form; for example, 1.602 × 10−19 would be 1.602E−19 or 1.602e−19.

9.2  Operations

There are two types of operation: unary and binary. Unary operations take one operand; binary operations take two operands.

9.2.1  Unary operations

Unary operations use prefix notation: they always appear before the operand in expressions, and they are right-associative. As well as unary + and -, the unary operations include several common mathematical functions. Because the unary operations have a higher precedence than binary operations when evaluating expressions, there is no need to enclose a simple operand of a mathematical function in parentheses. For example, the expression sin2x can be written sin x^2, though sin(x)^2 and (sin x)^2 are less ambiguous equivalents.

Operation Description
+ Unary plus
Unary minus
abs Absolute value
acos Inverse cosine, in the range [0, π]
acosh Inverse hyperbolic cosine, in the range [0, ∞]
acot Inverse cotangent, in the range [−π/2, π/2]
acsc Inverse cosecant, in the range [−π/2, π/2]
asec Inverse secant, in the range [0, π]
asin Inverse sine, in the range [−π/2, π/2]
asinh Inverse hyperbolic sine
atan Inverse tangent, in the range ]−π/2, π/2[
atanh Inverse hyperbolic tangent
ceil Smallest integer value that is greater than or equal to the operand
cos Cosine
cosh Hyperbolic cosine
cot Cotangent
csc Cosecant
exp e (base of natural logarithms) raised to the power of the operand
floor Largest integer value that is less than or equal to the operand
lg Logarithm, base 10
ln Logarithm, base e (ie, natural logarithm)
round Closest integer to the operand (1/2 is rounded up)
sec Secant
sin Sine
sinh Hyperbolic sine
sqrt Positive square root
tan Tangent
tanh Hyperbolic tangent

9.2.2  Binary operations

Binary operations use infix notation: they always appear between their operands in expressions, and they are left-associative (eg, 1 − x − ln x is evaluated as (1 − x) − ln x). The binary operations are the common arithmetic operations along with two types of remainder operation and the exponentiation ("raised to the power of") operation. Different precedence levels exist within the set of binary operations.

Operation Description
+ Addition
Subtraction
* Multiplication
/ Division
% Remainder (see below)
\ IEEE 754 remainder (see below)
^ operand1 raised to the power of operand2

The remainder operation, '%', is implemented in FuncPlotter by means of the floating-point '%' operation of the Java language. The operation, which is analogous to the integer remainder operation, is defined by the Java language specification (Java SE 8 edition) thus:

[W]here neither an infinity, nor a zero, nor NaN is involved, the floating-point remainder r from the division of a dividend n by a divisor d is defined by the mathematical relation r = n − (d · q) where q is an integer that is negative only if n/d is negative and positive only if n/d is positive, and whose magnitude is as large as possible without exceeding the magnitude of the true mathematical quotient of n and d.

The IEEE 754 remainder operation, '\', performs a remainder operation according to the IEEE 754 standard. It is implemented in FuncPlotter by means of the java.lang.Math.IEEEremainder() method. The Java API documentation describes the operation thus (with variables and operations renamed to be consistent with the definition of '%' above):

The remainder value is mathematically equal to n − (d · q), where q is the mathematical integer closest to the exact mathematical value of the quotient n/d, and if two mathematical integers are equally close to n/d, then q is the integer that is even.

The Java language specification (Java SE 8 edition) explains the difference between the two remainder operations.

9.2.3  Operation precedence

The following table lists the precedence of operations in an expression, with precedence decreasing from the top to the bottom of the table. Operations on the same row have equal precedence. Parentheses override operation precedence.

Unary operations
^
* / % \
+ −

10  Document formats

FuncPlotter supports two document formats, referred to as XML and text, although they are both text (as opposed to binary) formats. A document's format is also referred to as its file type. Files of both types are expected to be encoded as UTF-8. When a file is opened in FuncPlotter, the file type is determined by examining the first five bytes of the file: if they are the UTF-8 character sequence <?xml, the file is parsed as XML; otherwise, it is parsed as though it were in text format.

If you don't intend to edit a document manually, it is recommended that you save it in XML format.

10.1  XML format

The XML format was introduced in version 1.2 in order to provide a standard, interoperable format for FuncPlotter's documents. Although it is possible to edit XML documents manually, it is assumed that such documents were written by FuncPlotter, so the reporting of any errors that are encountered on opening a document in XML format is less detailed than the reporting of errors in a document in text format.

The structure of the XML format is simple: the x and y intervals are optional attributes of the <functionList> root element, and the function definitions are contained in zero or more <function> elements that are children of the root element. Each <function> element has an expression attribute (required) and a colour attribute (optional) whose forms correspond to the equivalent parts of a function definition in documents in text format — see below. The root element may contain a single <comment> element for the document comment.

The DTD of documents in XML format can be found in the file functionList.dtd, which is included in the FuncPlotter distribution. The DTD is provided only for reference; it is not used by FuncPlotter. Documents written by FuncPlotter in XML format do not contain a document type declaration.

10.2  Text format

The original document format, now referred to as text format, was designed to make it easy to create and edit sets of functions with a text editor. A document consists of a series of statements. There are two types of statement: an interval definition and a function definition. Each statement must be on a separate line. Blank lines are ignored. A document must contain no more than 20 function definitions.

If a line contains a '#' character, any text from the '#' to the end of the line is ignored. This can be used to include comments in a document. There are two types of comment:

  1. All comments that precede interval definitions and function definitions are merged into a single document comment, which can be edited from within FuncPlotter and will be saved with the document. The number of spaces between the '#' and the first non-space character of the first line of a document comment is taken to be the indent for the comment as a whole. Leading spaces up to the size of the indent are removed from subsequent lines of the comment.
  2. Comments that appear after the first interval definition or function definition are termed line comments. They must be included in a file by hand, and they are not preserved when FuncPlotter saves the document. Line comments should therefore be used only to annotate documents that will not be subsequently saved by FuncPlotter.

An interval definition must begin with an interval identifier: the '@' character followed by 'x' or 'y' (lower or upper case). The interval identifier is followed by the comma-separated lower and upper endpoints of the interval. Whitespace is allowed on either side of the endpoint values. For example, the line

@x -4.5, 3.2

denotes an x interval of [-4.5, 3.2].

An interval definition in a document is subject to the constraints described in the section on numeric values. For example, if the plot.numFractionDigits configuration property has the value 3 and a document contains an interval of [0.4521, 0.4523], the endpoints of the interval will be deemed to be equal (ie, both are rounded to 0.452), which will result in an error when the document is opened.

A function definition consists of two parts: an expression (required), followed by a colour definition (optional). The expression is an expression for f(x) as it would be entered in the Add function or Edit function dialog. If a colour is specified in the function definition, it consists either of the RGB components of the colour in the range 0..255, separated by commas, or of a '#' followed by six hexadecimal-digit characters (HTML notation). The colour definition is separated from the expression by a semi-colon. If the colour definition is absent, the default colour for that function is used instead. For example, the line

2*x^2 − 3*x + 1; 144, 0, 0

denotes the function y = 2x2 − 3x + 1, to be drawn in dark red, while the line

exp( 2*x ) − 3*x

denotes the function y = e2x − 3x, to be drawn in the default colour for the function at that particular index.

When you save a document with the File > Save file or File > Save file as commands, you are given the option of saving the colour definition with each of the function definitions in the document according to the policy outlined in the description of the Save file and Save file as commands.

Appendix A:  Special constructs in pathnames

Where indicated elsewhere in this document, pathname properties in FuncPlotter can contain special constructs for system properties, environment variables and the user's home directory. The special constructs are expanded when the pathname is used.

System properties and environment variables
Java system properties (eg, the user's home directory, user.home) and environment variables (eg, PATH) are referenced by enclosing them between '${' and '}'; that is, they must have the form ${<name>}. A Java system property takes precedence over an environment variable with the same name.
• Example: ${user.home}/projects
• Example: ${HOME}/projects
A Java system property can be specified by prefixing sys. to it.
• Example: ${sys.user.home}/projects
An environment variable can be specified by prefixing env. to it.
• Example: ${env.HOME}/projects
User's home directory
A leading '~' in a pathname is expanded into the user's home directory using the user.home system property, which is usually equivalent to the environment variable $HOME on Linux/UNIX systems or %USERPROFILE% on Windows systems.
• Example: ~/projects

Appendix B:  Configuration properties

The table below lists the configuration properties of FuncPlotter. Apart from the app.configDir property, which, for obvious reasons, cannot be used within a configuration file, all properties can be used in the two configuration locations: command-line properties and configuration file

When used in a -D command-line property, app. must be prefixed to the property key (eg, app.general.mainWindowLocation).

The <index> of an indexed property key (eg, function.colour) is a three-digit decimal-string representation of the zero-based index of the property (eg, the colour of the third function is function.colour.002).

Any commas (',') or backslash characters ('\') in the name of a font must be escaped by prefixing a '\' character to them.

In the table below, the initial character of an italicised component of a property value denotes its data type according to the following convention:

c colour: either r, g, b (decimal) or #rrggbb (hex)
f floating-point number
i integer
p platform-specific pathname, which may contain special constructs
s string
Property key Property value
configDir pPathname
appearance.lookAndFeel sName
appearance.textAntialiasing default | none | normal | subpixelHRgb | subpixelHBgr | subpixelVRgb | subpixelVBgr
font.comboBox sName, plain | bold | italic | boldItalic, iSize
font.main sName, plain | bold | italic | boldItalic, iSize
font.plot sName, plain | bold | italic | boldItalic, iSize
font.textField sName, plain | bold | italic | boldItalic, iSize
function.colour.<index> cColour
function.directory pPathname
function.listSize iNumColumns, iNumRows
function.obscuredColour cColour
general.clearEditListOnSave false | true
general.defaultFileType xml | text
general.mainWindowLocation iX, iY
general.maxEditListLength iLength
general.newDocumentOnStartup false | true
general.saveFunctionColours no | yes | ask
general.selectTextOnFocusGained false | true
general.showFullPathnames false | true
general.showUnixPathnames false | true
plot.colour.axis cColour
plot.colour.background cColour
plot.colour.focusedBorder cColour
plot.colour.grid cColour
plot.colour.imageMargin cColour
plot.colour.scale cColour
plot.fixedPointExponentRange iLowerBound, iUpperBound
plot.normaliseScientificNotation false | true
plot.numFractionDigits iNumDigits
plot.numYScaleDigits iNumDigits
plot.showGrid false | true
plot.size iWidth, iHeight
plot.truncateXScaleText false | true

Appendix C:  Providing feedback about FuncPlotter

The FuncPlotter project is hosted by SourceForge. You can submit bug reports, feature requests and suggestions for improvement through the SourceForge website, but the mechanism for doing so may change depending on the facilities that SourceForge provides. For current information, please see the feedback page for Blank Aspect projects.

When reporting a problem with FuncPlotter, please try to include enough relevant information to enable the problem to be reproduced. You should include at least the following information:

A Java stack trace, if one is available, would be helpful.

Last modified: 2017-11-04