FuncPlotter : manual
FuncPlotter is a Java application that can display 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).
FuncPlotter has the following features:
FuncPlotter is made available under two licences:
uk.blankaspect.funcplotter package (including
resources) may be used under the terms of version 3 of the GNU General Public License.
This section assumes that you have some experience of building and running a Java application.
A Java Development Kit (JDK) that supports Java 17, such as Eclipse Temurin from Adoptium, is required to build FuncPlotter.
The src directory of the repository contains all the source code and
resources that constitute the application; there are no external dependencies. The
directory conforms to the Maven standard directory layout: the source code is in
src/main/java and the resources are in src/main/resources.
The supplied Kotlin-DSL-based Gradle
build script, build.gradle.kts, modifies the compileJava and
jar tasks (provided by the java plug-in) to compile the
application and to create an executable JAR file for it.
The supplied Kotlin-DSL-based Gradle build script, build.gradle.kts,
defines two tasks that may be used to run FuncPlotter:
compileJava task.
jar task.
Both tasks extend the JavaExec task.
When it starts up, FuncPlotter is configured with configuration properties that are read from two sources: the command line of 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.
When FuncPlotter is run, configuration properties may be passed to the java
launcher on the command line as system properties; eg,
-Dapp.general.mainWindowLocation="100, 0". 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.
System properties can be added to the two supplied Gradle
tasks, runMain and runJar, with the
systemProperties(Map<String, ?>) method.
One particular property, app.configDir, is used to specify the directory that contains a configuration file, as described below.
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.
When it starts up, FuncPlotter is informed of the location of the configuration file with the app.configDir property. The value of the property may contain special constructs for system properties, environment variables and the user's home directory.
The app.configDir property may be set in two ways:
java launcher, or
funcPlotter-properties.xml that resides in the same
directory as the funcPlotter.jar JAR file.
The funcPlotter-properties.xml file is a legacy from the time when
FuncPlotter was distributed as a JAR file with an installer; the properties file was
written by the installer. If you create a properties file, 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 app.configDir property is set both on the command line and in the properties file, the value in the properties file takes precedence.
The existence and value of the app.configDir property determines the locations that are searched for a configuration file:
$PWD on Linux/UNIX systems, depends on the system and the way in
which FuncPlotter was run.
$HOME/.blankaspect/funcPlotter, where $HOME is the
environment variable that denotes the user's home directory. On Windows
systems, the default directory is
%APPDATA%\blankaspect\funcPlotter, where %APPDATA% is
an environment variable.
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.
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:
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.
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, (xn, yn) and (xn+1, yn+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−1, yn−1) and
(xn, yn) or between
(xn, yn) and
(xn+1, yn+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.)
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.
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.
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.
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.
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.
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.
The commands in the File menu are mostly standard and self-explanatory, but note the following:
The Open file command brings up a file-selection dialog in which you can choose the file that you want to open. FuncPlotter determines the document format — XML or text — by examining the first few bytes of the file.
The reporting of errors in a file differs according to the file's format: files in text format receive more detailed error reporting because it is assumed that they may have been edited manually. (Files in XML format are assumed to have been written by FuncPlotter.)
If a document in text format contains errors, a dialog box is displayed in which the errors are listed. (Documents that are saved by FuncPlotter should be free from errors, but there may be errors in a document that has been edited manually.) The first line of the error list is the pathname of the file that contains the errors; the remaining lines list the first 20 errors in the file, each prefaced by a line number. If the error is a syntax error in an expression, the line number is followed by a number in square brackets that denotes the position (ie, the character index) of the error in the expression.
The Revert file command is enabled when the current file has changed since it was last opened or saved. If you select the Revert file command, the current file will be read again from the file system, replacing the modified file in FuncPlotter's buffer.
When you save a document with the Save file command,
the document is written in the same format in which it was previously saved. If you
save a new document with the Save file
command, or if you save a document with the Save file
as command, a file-selection dialog is displayed in which you can choose not
only the file to which you want to save the document but also the document format — XML or text. The document format is
determined by the file type that you select in the file-selection dialog, and not by
the filename suffix that you specify. (For example, if you select a file named
a.txt and the file type "XML files", the file is written in
XML format.) If you select a file whose name has no suffix, the suffix
corresponding to the file type (.xml or .txt) is
automatically appended to the filename. If the file type in the file-selection
dialog is "All files", the default
file type is assumed.
If the general.saveFunctionColours configuration
property is set to Ask, you will be asked whether you want to save the
function colours in the document each time you select either the Save file or the Save file as
command.
The Export image file command writes an image file of the current plot panel in Portable Network Graphics (PNG) format. The command is enabled when a document is open and the implementation of Java supports the PNG image format. The colour resolution of the image is 24 bits per pixel. The PNG format offers a high level of compression for the sort of images that are exported by FuncPlotter.
In the exported image, the margin of the plot, which includes the scale markings, is drawn in the colour denoted by the plot.colour.imageMargin configuration property.
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.
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.
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.
This command reverses the order of the functions in the function list of the current document.
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.
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.
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.
XML.
Yes, a new (ie, empty) document will be displayed
when FuncPlotter starts up.
No.
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.
Yes.
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:
~.
\ on Windows systems) is replaced
by /.
No.
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.
Yes.
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.
No.
Yes, a document's history of edits (see Edit > Undo/Redo) is cleared when the document is saved.
No.
awt.useSystemAAFontSettings.
Default.
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.
Yes.
0 (zero) characters specified by
this property.
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.
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.)
Yes.
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.
Yes.
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.
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.
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.
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.
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.)
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.
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.
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.
This command brings up a small menu containing two check-box items: Highlight and Hide.
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.
This command toggles the visibility of the plot of the selected function. It operates independently of any highlighting.
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.
This command deletes all functions from the list.
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.
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:
E) is multiplied by 10 raised to the power of the
exponent (the integer after the E). If the first digit of the
significand is in the range 1..9 and is followed immediately
by the radix point, the number is said to be normalised. Thus, 6.24E−4
is normalised; 0.773E8 and 52.08E−6 are denormalised.
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.)
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.
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.
|
|
There are two types of operation: unary and binary. Unary operations take one operand; binary operations take two operands.
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 |
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 in section
15.17.3 of the Java language specification.
The IEEE 754 remainder operation, \, performs a remainder operation
according to the IEEE 754 standard. It is implemented in FuncPlotter by means of java.lang.Math.IEEEremainder(…).
The Java language specification explains the difference between the two remainder operations.
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 |
^
|
* / % \
|
+ −
|
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.
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 a file in the FuncPlotter repository. 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.
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:
# 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.
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
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
denotes the function y = 2x2 − 3x + 1, to be drawn in dark red, while the line
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.
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.
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.
${user.home}/projects
${HOME}/projects
sys. to it.
${sys.user.home}/projects
env. to it.
${env.HOME}/projects
~ 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.
~/projects
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 |
