# The Kpl Handbook

## Introduction

&kpl; is a program for two- and three-dimensional graphical presentation of data sets and functions. Moreover multidimensional nonlinear parameter fits of functions to data sets can be performed using the Levenberg-Marquardt algorithm. Also general linear least square parameter fits are possible. A DCOP interface can be used to control &kpl; by other applications and scripts.

All settings necessary for a complete description of the presentation can be saved in plot files. These files as well as data files may be chosen by command line parameters, using the File menu, or by drag and drop.

Automatic scaling and normalization allow the easy graphical presentation of data. Also parameter fits can be performed automatically.

The settings of a presentation may be changed using the Edit menu. Here also additional data sets and functions can be included which can be displayed in the same as well as in different data windows.

### &kpl; Revision History

- Version 3.3 (December 28, 2005)

  - Multiple spline items can be fitted simultaneously to the same array item

  - x and y values of array, function, and spline items can be shifted

  - Square checkbox in rectangle dialog, circle checkbox in ellipse dialog, circular arc checkbox in arc dialog

  - Colored symbol pixmaps are displayed in item list

  - Text of legend and text items is displayed in item list

  - Buttons of items dialog are disabled when action cannot be applied

  - Relative symbol size can be preset in Autoplot settings

  - Notifications about completed plots and parameter fits can be set

  - Needs KDE 3.x

- Version 3.2 (February 7, 2004)

  - Pattern filled areas given by arrays, functions, splines, rectangles and ellipses

  - New item for embedding of EPS image files

  - New scale bar item

  - New DCOP functions for image and scale bar items

  - PostScript preview

  - Option to print PostScript output files

  - Frame items can be kept closed in tree view

  - Error model function argument for parameter fits or smoothing spline fits can be chosen to be x or y column

  - Decimal symbol of data files can be chosen to be point or comma (needs KDE 3.1)

  - Context menu for visible items

  - NaN (not a number) and inf (infinity) in data files are ignored in plots

  - K menu entry moved to category Office

- Version 3.1 (April 2, 2003)

  - Root finding for functions and cubic splines

  - Items can be moved by drag and drop within the item list

  - New or copied items can be inserted before the current item

  - Middle mouse button can be used to rescale a frame

  - Format and precision settings now affect function range values

- Version 3.0 (September 30, 2002)

  - Version for KDE 3

  - New items for 3D surface plots of arrays and functions

  - New item for smoothing spline interpolation

  - New decoration item: arc

  - Rectangle and ellipse items can be rotated

  - New DCOP functions for 3D, spline, and arc items

  - Autoscaling reflects only the ranges of active items

  - Symbol size can be set individually for each array, function, or legend item

  - Combobox for several standard page formats

  - x-axis and y-axis can be placed on both sides

  - First numbers on x- and y-axis dont have to be at left or bottom end, respectively

  - Parameter fits for huge and tiny data values improved

- Version 2.3.0 (October 12, 2001)

  - Needs KDE 2.2

  - Residuals of parameter fits can be displayed

  - Arrays optionally can be saved within plot files

  - Separator for exported files can be set

  - Parameters of function items can be applied directly

  - New DCOP function: activateItem()

  - Improved selection and activation in dialog Items

  - Dialogs improved for KDE standard compliance

  - Return type of boolean DCOP functions changed to int to avoid problems

- Version 2.2 (May 22, 2001)

  - Data and plot files optionally can be added to the current plot

  - New decoration items: text, line, arrow, rectangle, ellipse

  - Position of items can be changed by dragging with the mouse

  - Reload button in Array dialog

  - Empty lines in data files are ignored

  - x-axis and y-axis can optionally be placed on top side or on right side, respectively

  - Japanese translation

- Version 2.1.1 (January 27, 2001)

  - Bug fixes

- Version 2.1 (January 22, 2001)

  - DCOP interface

  - Logarithmic scales

  - Only modified files are reloaded periodically

  - Position of toolbar saved in configuration file

  - Improved New Item dialog

  - New array or function items inherit the normalization factors of preceeding items

- Version 2.0 (November 21, 2000)

  - Needs KDE 2.0, optimized for KDE 2

  - Toolbar configuration item in Settings menu

  - Save absolute paths item in Settings menu

  - Improved double value input validation

  - Spinboxes in array dialog are updated

  - Unicode text in .plo files (recode your old .plo files to UTF8 when they contain non-ASCII characters)

  - Size of dialog windows can be changed

  - Polish translation

- Version 1.2 (August 10, 2000)

  - Undo/Redo Actions

  - Package for KDE 2 beta available

- Version 1.1 (May 5, 2000)

  - Multidimensional parameter fits

  - Improved parameter fit dialog

  - Increased printing resolution

  - Both portrait and landscape PostScript output

  - More examples

- Version 1.0 (February 21, 2000)

  - Buttons to open symbol selection dialog show actual symbol

  - Improved internationalization

  - Extended help

  - More examples

- Version 0.4 (January 14, 2000)

  - General linear least square parameter fit

  - Long parameter fit runs can be terminated by user

  - Output format for parameter files and dialogs can be changed

  - Output format for status bar is set according to screen resolution

  - Item dialog is modeless now

  - Multiple input files at commandline and at Drag and Drop

  - Both KDE and Qt Drag and Drop protocols supported

  - Session management

  - Function value buffers for faster redrawing

  - More example functions

- Version 0.3 (September 28, 1999)

  - Plot items can be deactivated to hide them (temporarily)

  - Sequence of plot items can be changed easily

  - Improved reading of plot files by use of KSimpleConfig

  - New plot files save the (de)activation state of items

  - Improved recognition of .plo files by file name

  - No multiselection necessary for parameter fitting when only one function and one array item are present

- Version 0.2 (July 29, 1999)

  - Needs KDE 1.1

  - Powered by KDevelop

  - Nonlinear parameter fit

  - Positions of menu bar and toolbar saved in configuration file

  - Popup menus with icons

  - Statusbar includes short help

  - Close item in File menu

  - Open Recent item in File menu

  - (De)activation of unsaved changes warning

  - Menu and toolbar items for magnification increasing/decreasing

  - Configure Key Bindings item in Options menu

  - Context menu

  - Improved painting by use of pixmap buffer

  - Function parameters may be saved separately in ASCII files

  - Function values may be exported in ASCII files

  - Optional display of function source in parameter dialogs

  - Optional calculation of bounding box for PostScript files (using Ghostscript)

  - MimeType for kpl plot files

- Version 0.1 (April 13, 1999, first release)

## Using &kpl;

### Command Line Options

#### Specify Files

When starting &kpl; from the command prompt, you can supply the names of one or more plot or data files (either local filenames or URLs):

    kpl
    file

In case of more than one entered file and activated setting Add Files all files are shown in one window, otherwise new windows are opened for each file.

In case of activated setting Autoplot, the graphical presentation is displayed immediately.

When in addition Autofit is activated, in case of a data file also a parameter fit to a function is automatically performed and the function is displayed, too.

#### Other Command Line Options

The following command line help options are available

`kpl `--help``

- This lists the most basic options available at the command line.

`kpl `--help-qt``

- This lists the options available for changing the way &kpl; interacts with Qt.

`kpl `--help-kde``

- This lists the options available for changing the way &kpl; interacts with KDE.

`kpl `--help-all``

- This lists all of the command line options.

`kpl `--author``

- Lists &kpl;'s author in the terminal window.

`kpl `--version``

- Lists version information for Qt, KDE, and &kpl;. Also available through `kpl `-v``

`kpl `--license``

- Lists license information for &kpl;.

### Start from Konqueror

&kpl; can be started to display a plot file by clicking its symbol in a &konqueror; file manager window or by selecting this action from its context menu.

### Drag and Drop

&kpl; supports the Drag and Drop protocol of KDE and Qt. This means that you can open one or more plot or data files by dragging their symbols onto the &kpl; window. Data files will be recognized by the extension `.dat`, plot files by the extension `.plo`. In addition to local files also URLs may be passed in this way.

In case of more than one dropped file and activated setting Add Files all files are shown in one window, otherwise new windows are opened for each file.

### Positioning with the Mouse

In addition to change the position of items by use of the dialogs, &kpl; supports dragging of frame, 3D array, 3D function, legend, text, line, arrow, arc, rectangle, ellipse, scale bar, and image items with the mouse.

To move an item, its area has to be clicked with the &LMB;. When the mouse is moved with the &LMB; pressed, a dashed rectangle shows the current position, displayed also on the status bar. The plot will be updated corresponding to the new position after releasing of the mouse button.

Moving of a frame item will update also the position of all its child items.

More than one item can be selected for simultaneous moving by clicking their areas with the Ctrl key pressed.

### Scaling with the Mouse

In addition to change the scaling of a 2D plot using the Frame dialog, a displayed plot containing a frame item can be rescaled conveniently with the help of the mouse. For this, one corner of a rectangle has to be defined by pressing the middle mouse button. Then, by moving the mouse diagonally, a dashed rectangle is drawn. Its final size will be defined by the point where the mouse button is released. At least one of the rectangle's corners has to be within the frame. The data space coordinates of the corners then are rounded using &kpl;'s autoscale feature to corresponding scaling values of the frameitem and the display is updated.

The ranges for the x axes of function and spline child items of the frame are updated correspondingly; the x step widths are set to 0 (resulting in automatically dividing the ranges into 100 intervals).

### Status Bar

The horizontal and vertical positions of the mouse pointer are displayed in cm on the right side of the status bar at the bottom of the &kpl; window, for positions inside the data frame of a 2D plot in data units, too. When the position of items is changed by dragging with the mouse, the current item position will be displayed.

Left to these position fields the state of the Add Files option is displayed.

On the left side the short help for the different actions appears.

## Command Reference

### The File Menu

Ctrl N File New

- Creates a new empty plot to insert items using the dialog Items.

Ctrl O File Open Plot File

- Opens one or more existing plot files.

  In a plot file all settings of a graphical presentation are stored as text.

  In case of activated setting Autoplot the graphical presentation is displayed immediately.

  In case of more than one selected file and activated setting Add Files all files are shown in one window, otherwise new windows are opened for each file.

File Open Data File

- Opens one or more existing data files.

  The numeric values have to be arranged in rows and columns in an ASCII file. Within a row the values may be separated by commas, tabs, or spaces.

  Point or comma can be selected as the decimal symbol in the dialog.

  The first character of comment lines has to be #.

  The number of rows and columns is detected by &kpl;. Empty lines are ignored.

  In case of activated setting Autoplot the 2D graphical presentation is displayed immediately according to the Autoplot Settings.

  In case of more than one selected file and activated setting Add Files all files are shown in one window, otherwise new windows are opened for each file.

  Loading of data files overwrites an eventually displayed presentation in case of deactivated setting Add Files. When a data file is to be inserted in an existing graphical presentation, this has to be done by creating a new item using the dialog Items or by activating Add Files.

File Open Recent

- Opens a submenu for selecting one of up to ten recently opened plot or data files.

  In case of activated setting Add Files the file is appended to a current plot, otherwise it will replace a current plot.

Ctrl S File Save

- Saves created or edited plot files.

File Save As

- Allows to save the current graphical presentation in a new plot file.

Ctrl W File Close

- Closes the current plot file.

Ctrl P File Print

- Prints the graphical presentation to a printer chosen from a list or to a file.

File Display Plot

- Displays the graphical presentation or refreshes after changes.

  In case of activated setting Autoplot the graphical presentation is displayed immediately after loading of plot or data files and after changes.

File PostScript Output

- Saves the graphical presentation as a PostScript file in Portrait or Landscape orientation.

  In comparison with the output obtained with Print and Print to File, these files may be edited easily. For example, the coordinates of 2D data points are stored without scaling, according to the values from data files or function evaluations.

  If Print PS Output is checked in the Settings menu, a print dialog is opened after writing the PostScript file to send it to a printer.

  The output can be used as Encapsulated PostScript (EPS) to import graphics in other applications. The bounding box is calculated exactly when Calculate PS Bounding Box is checked in the Settings menu.

File PostScript Preview

- Creates a temporary PostScript file in Portrait or Landscape orientation and displays it by invoking of KGhostView. This allows to print the PostScript output without permanently saving a PostScript file.

File New Window

- Opens a new instance of &kpl;.

File Close Window

- Close the window. If the closed window was the last instance open, &kpl; will exit.

Ctrl Q File Quit

- Exits &kpl;.

### The Edit Menu

Ctrl Z Edit Undo

- This is used to eliminate or reverse the most recent change of the plot. The maximum number of saved states is 20.

Ctrl Shft Z Edit Redo

- This will reverse the most recent change made using Undo.

Edit Items

- Opens the dialog Items (if not already open), where items of the presentation may be added, edited, deleted, and copied. Also parameter fits of functions to data sets can be performed here. The dialog can be left open during work with &kpl;.

### The View Menu

Ctrl+ View Zoom In

- Increases the magnification by 20 %.

Ctrl- View Zoom Out

- Decreases the magnification by 20 %.

View Zoom

- Here the magnification factor of the graphical presentation can be set.

F5 View Redisplay

- By this the current data or plot file will be reloaded and presented. Autoplot will be activated.

View Reload periodically

- Here periodically refreshing of the presentation of plot or data files may be activated. Also the time interval may be set. Autoplot will be activated by refreshing.

### The Settings Menu

Settings Show Tool Bar

- This toggles the display of the tool bar.

Settings Show Status Bar

- This toggles the display of the status bar.

Settings Show Function Source

- This toggles the display of the functions source files in the dialogs for function parameters

Settings Autoplot

- This toggles the automatic display of the presentation after loading of data or plot files

Insert Settings Add Files

- This toggles the adding of plot and data files to existing plots and overwriting, respectively. The current state of this setting is displayed on the status bar.

Settings Calculate PS Bounding Box

- This toggles the automatic calculation of the bounding box for generated PostScript files. The calculation needs Ghostscript to be installed and assumes that the Page format on the page Basic Settings of &kpl;'s settings dialog is set sufficiently large to contain all parts of the plot. Without calculation the bounding box is set according to that page format.

Settings Print PS Output

- This toggles the display of a print dialog to print PostScript files after their generation.

Settings Save Absolute Paths

- Tis toggles the saving of absolute or relative paths of data and library files in plot files. When this option is set on, the paths always saved as absolute. This is the default setting, compatible with older versions of &kpl;. When the option is set off, the paths are saved as relative paths to that of the plot file, if possible. This allows to move directory branches containing the plot file and all files it depends on.

Settings Unsaved Changes Warning

- This toggles the display of warnings at unsaved changes.

Settings Save Settings At End

- This toggles the saving of the current window size, the visibility of the dialog Items, and the settings of the Settings menu at the program's ending.

  This setting itself also will be saved.

Settings Save Settings

- This saves the current window size, the visibility of the dialog Items, and the settings of the Settings menu.

Settings Configure Key Bindings

- Opens the dialog Configure key bindings, where the shortcuts for the &kpl; actions may be changed.

Settings Configure Toolbars

- Opens the dialog Configure Toolbars, where the actions of the toolbar may be changed.

Settings Configure Notifications

- Opens the dialog Notification Settings, where notifications about completed plots and parameter fits can be set.

Settings Configure Kpl

- Opens the dialog Kpl Settings. On the page Basic Settings the size of the presentation and the colors as well as the output format for function parameters may be preset. Also the toggle options of the Settings menu can be set at once.

  On the page Autoplot Settings the settings for the automatic scaling of 2D data files loaded by command line parameter, by the file menu, or by drag and drop, are done.

  On the page Autofit Settings the settings for the automatic parameter fittings of functions to 2D data sets from files are performed.

### The Help Menu

Help Kpl Handbook

- Here the help for &kpl; is available.

Help Report Bug

- Opens a dialog for submitting a bug report to the author of &kpl;.

Help About Kpl

- Displays essential information about &kpl;.

Help About KDE

- Displays essential information about KDE.

### Context Menus

#### Item

Clicking the rectangular area of an item which can be positioned (frame, 3D array, 3D function, image, legend, text, line, arrow, arc, rectangle, ellipse, or scale bar) with the right mouse button brings up a context menu with actions corresponding to that item (also available in the dialog Items):

Edit

- Opens the dialog for the settings of the corresponding item.

Delete

- Deletes the item.

Copy

- Duplicates the item. The copy is placed at the end of the list if Append item is checked in the dialog Items, otherwise it will be inserted before the selected item.

Active

- Changes the activation state of the item. Activated items are shown in the plot, deactivated items are hidden.

#### Plot

Clicking the plot area with the right mouse button outside of the rectangles of the items brings up a context menu with the most important actions:

New

- Opens a new plot file.

Open Plot File

- Opens one or more existing plot files.

Open Data File

- Opens one or more existing data files.

Save

- Saves the current plot file.

Save As

- Saves the current graphical presentation in a new plot file.

Print

- Prints the graphical presentation.

PostScript Output

- Saves the graphical presentation as a PostScript file.

Items

- Opens the dialog Items.

Zoom In

- Increases magnification by 20 %.

Zoom Out

- Decreases magnification by 20 %.

Redisplay

- Reloads the current file and refreshes the plot.

### Key Bindings

Many of the key bindings (shortcuts) are configurable by way of the Settings menu. By default &kpl; honors the following key bindings:

Key Binding | Action
Ctrl N | Opens a new plot file.
Ctrl O | Opens an existing plot file.
Ctrl S | Saves the current plot file.
Ctrl W | Closes the current plot file.
Ctrl P | Prints the graphical presentation.
Ctrl Q | Quits &kpl;.
Ctrl Z | Reverses the last change of the plot.
Ctrl Shft Z | Reverses the last change of the plot made using Undo.
Ctrl+ | Increases magnification by 20 %.
Ctrl- | Decreases magnification by 20 %.
F5 | Reloads the current file and refreshes the plot.
Insert | Toggles the adding of plot and data files to existing plots and overwriting, respectively.
Left Arrow | Scrolls left.
Right Arrow | Scrolls left.
Down Arrow | Scrolls down.
Up Arrow | Scrolls up.
Page Up | Scrolls page up.
Page Down | Scrolls page down.
Ctrl Page Up | Scrolls page left.
Ctrl Page Down | Scrolls page right.
Home | Scrolls to bottom margin.
End | Scrolls to top margin.
Ctrl Home | Scrolls to left margin.
Ctrl End | Scrolls to right margin.

### Tool Bar

The toolbar is are configurable by way of the Settings menu. By default the &kpl; toolbar contains the following buttons:

| Text | Action
| New | Opens a new plot file.
| Open Plot File | Opens an existing plot file.
| Open Data File | Opens an existing data file.
| Save | Saves the current plot file.
| Print | Prints the graphical presentation.
| Undo | Reverses the last change of the plot.
| Redo | Reverses the last change of the plot made using Undo.
| Zoom In | Increases magnification by 20 %.
| Zoom Out | Decreases magnification by 20 %.
| Reload | Reloads the current file and refreshes the plot.
| Kpl Handbook | Displays the &kpl; help pages.

## The Dialogs

### Items

When items of the presentation already exist, they are listed in the dialog window. In case of a frame, an arc, a rectangle, or an ellipse its position and size is shown; in case of an array the name of the data file as well as the column indices of x and y values, in case of a 3D array the name of the data file, in case of a function or a 3D function the names of the shared library and the function, in case of a parametric function the names of the shared libraries and the functions for x(t) and y(t), in case of a spline the order of the polynomial, in case of a legend or a text the text and the position, in case of an image the name of the EPS file and the position, in case of a scale bar its orientation and position, and in case of a line or an arrow its position and direction. In case of an array, a function or parametric function or a legend in addition the plot symbol is shown in the selected color. Colors are also indicated for arc, rectangle, ellipse, line, arrow, and scale bar items. When the dialog is left open, it will reflect changes in the item list.

In the tree view frames are displayed one hierarchical level higher than the other item types. Other items following a frame are to be plotted in that frame. The sequence of items belonging to a frame ends when another frame item follows. Items not belonging to a frame, that is, items not following a frame item, will be plotted without a frame. Function and data set values then will be interpreted as cms. 3D arrays and 3D functions contain the function of frames and therefore do not need an additional frame item; also other items can belong to them. The position of the selected item can be changed using the up and down arrow buttons left to the tree view. The position of an item can also be changed by drag and drop within the list using the mouse.

Each item is preceeded by a checkbox field, displaying its activation state. Activated items are shown in the plot, deactivated items are hidden. The state can be toggled by clicking the checkbox field with the left mouse button or by the item's context menu, which pops up when an item is clicked with the right mouse button. An item can be selected without changing its activation state by clicking it right of the checkbox field or by use of the cursor keys.

For adding a new item to the list, the button New opens the dialog New Item, where the type of the item is to be chosen.

The button Edit opens the according dialog for the setting of the item selected from the list. Editing can also be selected from a context menu, which pops up when an item is clicked with the right mouse button. Finally the dialog for a selected item can be opened by use of the Enter key.

By using the button Fit functions and splines can be fitted to data sets. When one ore more functions and one or more arrays are selected, the button opens the dialog Parameter fit for performing a (multidimensional) parameter fit of the function(s) to the data set(s) of the array item(s). When the item list contains exactly one function and one array item, no multiselection is necessary and the dialog is just opened by clicking the button to perform a parameter fit in one dimension. Otherwise you first have to select an equal number of function items and array items. This can be done by holding down the Ctrl key when clicking the items to be selected. In case of multidimensional fits the first selected function item in the list corresponds to the first selected array item in the list and so on. When one spline and one array are selected, the button opens the dialog Smoothing spline fit for performing a fit of a (smoothing) spline to the data set of the array item.

By using the button Delete the selected item(s) may be deleted. Deleting of an item can also be selected from its context menu.

By using the button Copy the selected item(s) may be duplicated. Copying of an item can also be selected from its context menu.

New or copied items will be appended to the list if Append item is checked, otherwise they will be inserted before the selected item(s).

In the tree view, frame items may closed to hide their children for clearness by clicking the - icon. Reopening to show their children is done by clicking the + icon. The state of the frame items will be saved in the plot files.

The dialog is closed by using the button Close. The dialog can be left open during work with &kpl;.

### New item

The type of the new item may be chosen using the buttons Frame, Array, Function, Parametric Function, Spline, 3D Array, 3D Function, Image, Legend, Text, Line, Arrow, Arc, Rectangle, Ellipse, and Scale Bar.

Scalable items like array or function items will inherit the normalization factors of the last preceeding scalable item belonging to the same frame, if existing.

When the type is chosen, the according dialog for the settings of the new item is displayed.

The dialog may be canceled without selection by use of the button Cancel.

### Frame

Here the settings for frame and labels may be performed.

In the group Axis mode one can choose between only a frame around the data window or additional tick marks on the left and lower sides of the frame or a grid. Tick marks and grid may be labeled with numeric values.

In the group Colors the colors for frame and ticks or grid are selected with the dialog Select Color, displayed by using the color buttons.

The group Automatic allows convenient scaling of the presentation by using the button Autoscale, when arrays or functions are already set in subsequent items of the presentation. When Normalization is checked, at this time also powers of ten are evaluated to be multiplied with the numeric data values in case of huge or tiny numbers. If not equal to 1, these normalization factors are included in the axis labels.

In the group Window position and size of the data window may be set.

The group Scaling allows manual scaling of the presentation by specifying data values for the lower left and the upper right corner of the data window. The settings also may be performed by using the button Autoscale. The scaling can be set to logarithmic individually for the axes by checking log.

The group Axes allows to specify the distances xtic and ytic of major tick marks or grid lines. With xoff and yoff offsets for the first labeled ticks from the respective axis start may be set. In case of tick marks minor ticks may be drawn between the (labeled) major ticks. The number of intervals dividing the distance between the major ticks can be specified by mticx and mticy. For axes with numeric labels the number of digits behind the decimal point may be selected by ndigx and ndigy. Here values of -1 are used to suppress the output of the decimal point. The settings also may be performed by using the button Autoscale.

For logarithmic scales the controls have a different meaning. ndigx and ndigy are disabled, the number of digits is determined automatically. The values of xtic and ytic give the factor between first and second major tick mark and will be rounded to 2, 5, or 10. Always ten minor tick marks per decade will be drawn when mticx and mticy are set larger than 1. In contrast to linear scales minor ticks will be shown as grid lines in case of grid axis modes. The normalization option for autoscaling will be deselected in case of logarithmic scales.

In the group Labels text for the axis labels and a heading may be entered. Text with special characters is entered more conveniently in the dialog Edit text which shows up when using the buttons right to the entry fields. Powers of ten for normalization factors to be included in the axis labels may be specified manually by iex and iey. The placement of the x axis labels can be set by checking Bottom and Top, that of the y axis labels by checking Left and Right.

With Symbol size the relative size of characters and markers as well as the relative line widths (proportional to the width of the data window) may be specified. A setting of 100 % corresponds to the default. Additional individual size factors may be set in the dialogs of the corresponding items.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Array

The dialog Array is used to perform the settings for a data set from a data file.

The button File is used to open a file selection dialog for selecting a data file. The decimal symbol for reading the file can be selected in this dialog. The path of the file is displayed right to the button. The button right to this field is used to reload a data file after changes of its contents. Selecting a file results in automatic determination of suitable values for the following settings.

By checking Internal Data the array data can be saved within the plot file. For reasons of performance this should only done with data sets not to large. Only the columns selected for plotting will be stored. Internal data can be entered or changed by use of Edit. After unchecking of Internal Data a file selection dialog will be opened to select a separate data file for (re)exporting.

In x column and y column the file columns for abscissa and ordinate values may be chosen. 0 corresponds to the first column.

When Error bar is checked the column chosen in Error column is used for displaying error bars. This column is also used in case of parameter fits of functions to the data sets for weighing the data points.

The Start index is the row index for the first data point to be displayed. 0 corresponds to the first row of the data file, not counting comment lines. Together with the Number of points the displayed portion of the file is selected.

The x and y values can be shifted in the presentation by entering x shift and y shift values.

Factors for x normalization and y normalization may be entered manually. These factors also may be determined automatically using Autoscale with checked Normalization in the dialog Frame.

Markers (Symbol <= 0) or lines (Symbol > 0) may be chosen to present the data points. This is done most convenient using the dialog Lines and Markers, to be opened with the button right to the spin box, which shows the actual line or marker.

The Size of lines or markers may be chosen as an additional individual factor to the global setting of the corresponding frame item.

The Color of lines or markers may be chosen using the dialog Select Color, opened with the colored button.

By choosing a Fill pattern the polygon given by the points of the array can be filled with a solid color or a pattern instead of being represented by lines or markers.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Function

The dialog Function is used to perform the settings for function plots.

In the field Library in the group y(x) the path of the shared library containing the function to be chosen may be entered. The button right to the entry field opens a file selection dialog for this purpose.

The name of the Function is entered in another field. When in the same directory as for the shared library a module definition file with the same name but the extension `.def` is present, the function may be chosen from a list in the dialog Functions, opened with the button right to the entry field.

With the button Edit a dialog Parameter may be opened, which allows to enter the values of up to 20 parameters of the function. When the option Show Function Source is activated in the Settings menu and a C or C++ language source file with the same name as the shared library with the extension `.c` or `.cpp`, respectively, is present in the same directory, its contents is displayed right to the parameter fields, too. The button Load opens a file selection dialog for loading the parameters from an ASCII file (one parameter each line). The button Save opens a file selection dialog for saving the parameters in an ASCII file.

The limits for the function's argument are entered using the fields xmin and xmax. With Delta x the step length for the argument is set. A value of 0 results in automatically dividing the range from xmin to xmax into 100 intervals.

The x and y values can be shifted in the presentation by entering x shift and y shift values.

Factors for x normalization and y normalization may be entered manually. These factors also may be determined automatically using Autoscale with checked Normalization in the dialog Frame.

Markers (Symbol <= 0) or lines (Symbol > 0) may be chosen to present the function. This is done most convenient using the dialog Lines and Markers, to be opened with the button right to the spin box, which shows the actual line or marker.

The Size of lines or markers may be chosen as an additional individual factor to the global setting of the corresponding frame item.

The Color of lines or markers may be chosen using the dialog Select Color, opened with the colored button.

By choosing a Fill pattern the polygon given by the points of the function can be filled with a solid color or a pattern instead of being represented by lines or markers.

The dialog Roots for finding roots of the function or of its derivatives is opened by use of the button Roots.

A function value table may be exported as a data file by use of the button Export. A file selection dialog will be opened for this purpose.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Parametric function

The dialog Parametric function is used to perform the settings for plots of parametric functions.

In the groups x(t) and y(t) the setting for the abscissa an the ordinate function may be performed in the same way.

In the fields Library the paths of the shared libraries containing the functions to be chosen may be entered. The buttons right to the entry fields open file selection dialogs for this purpose.

The names of the Functions for x(t) and y(t) are entered in the corresponding fields. When in the same directories as for the shared libraries module definition files with the same names but the extension `.def` are present, the functions may be chosen from a list in the dialog Functions, opened with the buttons right to the entry fields.

With the buttons Edit a dialog Parameter may be opened, which allows to enter the values of up to 20 parameters of the functions. When the option Show Function Source is activated in the Settings menu and a C or C++ language source file with the same name as the shared library with the extension `.c` or `.cpp`, respectively, is present in the same directory, its contents is displayed right to the parameter fields, too. The buttons Load open a file selection dialog for loading the parameters from an ASCII file (one parameter each line). The buttons Save open a file selection dialog for saving the parameters in an ASCII file.

The limits for the function's common argument t are entered using the fields tmin and tmax. With Delta t the step length for the argument is set. A value of 0 results in automatically dividing the range from tmin to tmax into 100 intervals.

The x and y values can be shifted in the presentation by entering x shift and y shift values.

Factors for x normalization and y normalization may be entered manually. These factors also may be determined automatically using Autoscale with checked Normalization in the dialog Frame.

Markers (Symbol <= 0) or lines (Symbol > 0) may be chosen to present thefunctions. This is done most convenient using the dialog Lines and Markers, to be opened with the button right to the spin box, which shows the actual line or marker.

The Size of lines or markers may be chosen as an additional individual factor to the global setting of the corresponding frame item.

The Color of lines or markers may be chosen using the dialog Select Color, opened with the colored button.

By choosing a Fill pattern the polygon given by the points of the function can be filled with a solid color or a pattern instead of being represented by lines or markers.

A function value table may be exported as a data file by use of the button Export. A file selection dialog will be opened for this purpose.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Smoothing spline

The dialog Smoothing spline is used to perform the settings for plots of smoothing spline functions. Setting of the spline's degree and calculation of its coefficients corresponding to a fit to a data set of an array is done using the dialog Smoothing spline fit, which can be opened by Fit in the dialog Items.

In the group Output it can be selected by a combobox whether the spline function itself, one of its derivatives, or its integral should be plotted. In case of an integral in addition a Lower boundary can be set, i.e. the x value at which the integral is zero.

The limits for the function's argument are entered using the fields xmin and xmax. With Delta x the step length for the argument is set. A value of 0 results in automatically dividing the range from xmin to xmax into 100 intervals.

The x and y values can be shifted in the presentation by entering x shift and y shift values.

Factors for x normalization and y normalization may be entered manually. These factors also may be determined automatically using Autoscale with checked Normalization in the dialog Frame.

Markers (Symbol <= 0) or lines (Symbol > 0) may be chosen to present the function. This is done most convenient using the dialog Lines and Markers, to be opened with the button right to the spin box, which shows the actual line or marker.

The Size of lines or markers may be chosen as an additional individual factor to the global setting of the corresponding frame item.

The Color of lines or markers may be chosen using the dialog Select Color, opened with the colored button.

By choosing a Fill pattern the polygon given by the points of the spline function can be filled with a solid color or a pattern instead of being represented by lines or markers.

The dialog Roots for finding roots of a cubic spline or of its derivatives is opened by use of the button Roots.

A table containing the represented values may be exported as a data file by use of the button Export. A file selection dialog will be opened for this purpose.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### 3D array

The dialog 3D array is used to perform the settings for the three-dimensional representation of a data set from a file. The data are represented as a surface y(x,z) described by a smoothing spline interpolation. The dialog is divided into three pages.

#### Array

On the page Array in the group Data using the button ... a dialog can be opened to select a data file. The decimal symbol for reading the file can be selected in this dialog. The actual path is displayed left to the button. The button on the right hand side can be used to reload a data file after changing its contents.

By checking Internal Data the array data can be saved within the plot file. For reasons of performance this should only done with data sets not to large. Only the columns selected for plotting will be stored. Internal data can be entered or changed by use of Edit. After unchecking of Internal Data a file selection dialog will be opened to select a separate data file for (re)exporting.

In x column, y column, and z column the file columns for the cordinates of the three-dimensional plot may be chosen. 0 corresponds to the first column. Data are represented as a surface y(x,z). When Error bar is checked the column chosen in Error column is used as the standard deviation of the y values for weighing the data points when the smoothing spline is calculated. The Smoothing factor affects the average deviation between the spine function and the y values of the data set, and in this case it determines the factor, by which in the average the deviation should be different to the error of the data points. A value of 0 leads to a non-smoothing spline. In this case the x and z coordinates of the array have to fall on a grid. In case of a smoothing spline the coordinates may be placed randomly in the x,z plane. When Error column is not checked, the value of the smoothing factor is taken as the constant standard deviation of the y values.

The Start index is the row index for the first data point to be taken to calculate the surface y(x,z). 0 corresponds to the first row of the data file, not counting comment lines. Together with the Number of points the portion of the file used for calculating the spline is selected. With xmin, xmax, zmin, and zmax the limits for the displayed region of the surface y(x,z) and for the x and z axis are set. The step sizes Delta x and Delta z determine the intervals of the grid which represents the surface. Values of 0 result in automatically dividing the respective range into 40 intervals. With ymin and ymax the limits of the y axis are set. The scaling can be set to logarithmic individually for the axes by checking log.

#### Scaling

On the page Scaling in the group Window the rectangular range where the three-dimensional plot is shown can be set in cms. A frame around this rectangle is drawn optionally.

In the group Reference Point the distances from the center of the plane spread by the x and z axes at ymin to the left and bottom sides of the window may be set in cms.

In the group 3D box the lenghts of the x, y, and z axis of the three-dimensional plot can be set in cms.

The Rotation of the coordinate frame can be set by the angles phi and theta. The value of phi determines the rotation around the y axis, the value of theta determines the tilt of the y axis.

The group Axes allows to specify the distances xtic, ytic, and ztic of major (labeled) tick marks. The number of intervals dividing the distance between the major ticks can be specified by mticx, mticy, and mticz. For axes with numeric labels the number of digits behind the decimal point may be selected by ndigx and ndigy. Here values of -1 are used to suppress the output of the decimal point.

Factors for Normalization of the x, y, and z axis may be entered manually. These factors also may be determined automatically using Autoscale with checked Normalization. Autoscaling also sets the limits of the axes, the distances between major tick marks, the number of intervals between major tick marks, the number of digits for numeric labels, the Reference Point, and the lengths of the axes.

#### Representation

On the page Representation in the group Axis mode it can be selected to plot tick marks with and without numeric labels.

In the group 3D mode it can be selected if the surface y(x,z) should be represented by lines in x or z direction or by a grid of lines in x and z direction.

In the group Colors the colors for frame, tick marks, and the surface representing the data may be chosen using the dialog Select Color, opened with the colored buttons.

By Show frame the display of a frame around the rectangular window of the plot can be selected. The relative Line width of the surface grid (proportional to the width of the data window) may be specified. A setting of 100 % corresponds to the default.

A table with values of the plotted surfaces can be exported as a data file using the button Export. A file selection dialog will be opened for this purpose.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### 3D function

The dialog 3D function is used to perform the settings for the three-dimensional representation of a function y(x,z) of two independent variables. The dialog is divided into three pages.

#### Function

On the page Function in the group y(x,z) the path of the shared library containing the function to be chosen may be entered in the field Library. The button right to the entry field opens a file selection dialog for this purpose.

The name of the Function is entered in another field. When in the same directory as for the shared library a module definition file with the same name but the extension `.def` is present, the function may be chosen from a list in the dialog Functions, opened with the button right to the entry field.

With the button Edit a dialog Parameter may be opened, which allows to enter the values of up to 20 parameters of the function. When the option Show Function Source is activated in the Settings menu and a C or C++ language source file with the same name as the shared library with the extension `.c` or `.cpp`, respectively, is present in the same directory, its contents is displayed right to the parameter fields, too. The button Load opens a file selection dialog for loading the parameters from an ASCII file (one parameter each line). The button Save opens a file selection dialog for saving the parameters in an ASCII file.

In the group y(x,z) the limits for the function's arguments and the x and z axes are entered using the fields xmin, xmax, zmin, and zmax. With Delta x and Delta z the step sizes for the arguments are set. A value of 0 results in automatically dividing the respective range into 40 intervals. With ymin and ymax the limits of the y axis are set. The scaling can be set to logarithmic individually for the axes by checking log.

#### Scaling

On the page Scaling in the group Window the rectangular range where the three-dimensional plot is shown can be set in cms. A frame around this rectangle is drawn optionally.

In the group Reference Point the distances from the center of the plane spread by the x and z axes at ymin to the left and bottom sides of the window may be set in cms.

In the group 3D box the lenghts of the x, y, and z axis of the three-dimensional plot can be set in cms.

The Rotation of the coordinate frame can be set by the angles phi and theta. The value of phi determines the rotation around the y axis, the value of theta determines the tilt of the y axis.

The group Axes allows to specify the distances xtic, ytic, and ztic of major (labeled) tick marks. The number of intervals dividing the distance between the major ticks can be specified by mticx, mticy, and mticz. For axes with numeric labels the number of digits behind the decimal point may be selected by ndigx and ndigy. Here values of -1 are used to suppress the output of the decimal point.

Factors for Normalization of the x, y, and z axis may be entered manually. These factors also may be determined automatically using Autoscale with checked Normalization. Autoscaling also sets the limits of the axes, the distances between major tick marks, the number of intervals between major tick marks, the number of digits for numeric labels, the Reference Point, and the lengths of the axes.

#### Representation

On the page Representation in the group Axis mode it can be selected to plot tick marks with and without numeric labels.

In the group 3D mode it can be selected if the surface y(x,z) should be represented by lines in x or z direction or by a grid of lines in x and z direction.

In the group Colors the colors for frame, tick marks, and the surface representing the data may be chosen using the dialog Select Color, opened with the colored buttons.

By Show frame the display of a frame around the rectangular window of the plot can be selected. The relative Line width of the surface grid (proportional to the width of the data window) may be specified. A setting of 100 % corresponds to the default.

A table with values of the plotted surfaces can be exported as a data file using the button Export. A file selection dialog will be opened for this purpose.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Image

The dialog Image allows to embed an EPS (Encapsulated PostScript) figure in a plot.

A file selection dialog is used to select the EPS File. With x0 and y0 the position of the left bottom corner may be set.

x Scaling and y Scaling allow to set horizontal and vertical scaling factors. Values of 100 % correspond to the original size of the figure. The same scaling factor for x and y direction is used when Maintain aspect ratio is checked.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Legend

The dialog Legend is used to perform the settings for the explanation of line types and symbols as well as for additional labels.

In the group Data a Symbol to be explained is selected. This is done most convenient using the dialog Lines and Markers, opened using the button right to the spin box, which shows the actual line or marker. The symbol number -17 may be chosen to draw labels without markers or lines. The Size of lines or markers may be chosen as an additional individual factor to the global setting of the corresponding frame item. The Color of lines and markers is selected in the dialog Select Color, opened with the colored button. With x and y the position with respect to the lower left corner of the window may be set.

In the group Label the Text may be entered. Text with special characters is entered most conveniently using the dialog Edit text, opened using the button right to the entry field. With Size the relative size of the characters may be set. A setting of 100 % corresponds to a normal value. The Color of the text label is selected in the dialog Select Color, opened with the colored button. With xoff and yoff the position of the text with respect to that of the symbol may be entered.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Text

The dialog Text is used to perform the settings for a text to decorate the plot.

The Text may be entered in the corresponding entry field. Text with special characters is entered most conveniently using the dialog Edit text, opened using the button right to the entry field. The Direction of the text can be entered in degrees. The Alignment of the text with respect to the position may be chosen to be left, centered, or right. With x0 and y0 the position of the text may be set in cm.

With Size the relative size of the characters may be set. A setting of 100 % corresponds to a normal value. The Color of the line is selected in the dialog Select Color, opened with the colored button.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Line

The dialog Line is used to perform the settings for a line to decorate the plot.

The Direction of the line can be entered in degrees. With Length the length is set in cm. With x0 and y0 the start position of the line may be set.

With Width the relative width of the line may be set. A setting of 100 % corresponds to a normal value. The Color of the line is selected in the dialog Select Color, opened with the colored button.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Arrow

The dialog Arrow is used to perform the settings for an arrow to decorate the plot.

The Direction of the arrow can be entered in degrees. With Length the total length is set in cm. With x0 and y0 the position of the arrow head may be set.

With Size the relative size of the arrow head may be set. A setting of 100 % corresponds to a normal value. The Color of the arrow is selected in the dialog Select Color, opened with the colored button.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Arc

The dialog Arc is used to perform the settings for an elliptic arc to decorate the plot.

The Width and Height of the ellipse can be entered in cm. The height is set equal to the width when Circular arc is checked. With Start and Length the arc's start angle and length can be set in degrees. The Rotation of the ellipse around the left bottom corner can be entered in degrees. With x0 and y0 the position of the center may be set.

With Line width the relative width of the line to draw the arc may be set. A setting of 100 % corresponds to a normal value. The Color of the arc is selected in the dialog Select Color, opened with the colored button.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Rectangle

The dialog Rectangle is used to perform the settings for a rectangle to decorate the plot.

The Width and Height of the rectangle can be entered in cm. The height is set equal to the width when Square is checked. The Rotation of the rectangle around the left bottom corner can be entered in degrees. With x0 and y0 the position of the left bottom corner may be set.

With Line width the relative width of the line to draw the rectangle may be set. A setting of 100 % corresponds to a normal value. The Color of the rectangle is selected in the dialog Select Color, opened with the colored button.

By choosing a Fill pattern the rectangle can be filled with a solid color or a pattern instead of being represented by a line.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Ellipse

The dialog Ellipse is used to perform the settings for a ellipse to decorate the plot.

The Width and Height of the ellipse can be entered in cm. The height is set equal to the width when Circle is checked. The Rotation of the ellipse can be entered in degrees. With x0 and y0 the position of the center may be set.

With Line width the relative width of the line to draw the ellipse may be set. A setting of 100 % corresponds to a normal value. The Color of the ellipse is selected in the dialog Select Color, opened with the colored button.

By choosing a Fill pattern the ellipse can be filled with a solid color or a pattern instead of being represented by a line.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Scale Bar

The dialog Scale Bar is used to perform the settings for a bar showing a length scale. Horizontal or Vertical orientation of the bar may be chosen. A Text (usually a length the bar should represent) can be entered. The actual Length of the bar in the plot has to be supplied in cm. With x0 and y0 the position of the left bottom corner may be set.

With Size the relative size of the text and the relative linewidth may be set. A setting of 100 % corresponds to a normal value. The Color of the scale bar is selected in the dialog Select Color, opened with the colored button.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

### Parameter fit

The dialog Parameter fit is used to perform parameter fits of one function (or more functions depending on the same set of parameters in case of multidimensional fits) to the same number of data sets. The dialog is shown either when Fit is selected in the dialog Items, or when a data file is loaded and the options Autofit in the Autoplot settings and Show dialog in the Autofit settings both are activated.

Initial values for the parameters may be entered in the corresponding fields. When the dialog is opened, the fields are initialized with the current parameter set of the function (in case of multidimensional fits with that of the first function in the list of selected functions). By checking the boxes left to the entry fields the parameters are chosen to be fitted, otherwise their values are kept constant. In case of general linear least square fits no initial values need to be entered for the parameters chosen to be fitted. The estimated standard deviations of the parameter are displayed right to the corresponding entry fields.

The buttons Load and Save are used to load and save the current parameter set from or to text files, respectively. Differing to the format used in the other parameter setting dialogs, here a second column containing the estimated standard deviations of the parameters is saved, too.

When the box Nonlinear fit is checked, nonlinear parameter fits by employing the iterative Levenberg-Marquardt method will be performed. Otherwise noniterative general linear least square parameter fits are selected. In this case the function must depend linearly on all parameters chosen to be fitted.

In the group Data errors the settings for weighing the data points may be formed. The selected Array for which the settings are performed is shown by its filename and the column indices for x, y, and errors. In case of multidimensional fits the array can be selected with a spin box showing its index within the list of arrays. Then the settings can be performed individually for each array.

When the box Error column is checked, the corresponding column of the data set, selected in the dialog Array, is used as the standard deviation of the y values for calculation of chi-square. Otherwise the standard deviation will be estimated by an error model function taking the x or the y value as its argument. This function and their parameters may be selected in a dialog which is displayed by clicking Model. A simple error model might be selected by choosing a polynomial with p1 = 0.01, resulting in standard deviations of 1 %.

Termination of the iterative nonlinear parameter fit algorithm may be controlled by setting a Maximum iterations number and a Tolerance value. Fitting is terminated when either the maximum number of iterations is reached or the relative errors of chi-square or of the parameters have decreased down to the tolerance value.

The fit is started by clicking the Start button. Progress of the chi-square values during the iterations is displayed in the listbox in the lower part of the dialog. Fitting can be terminated by use of the button Cancel. At the end the termination reason is displayed as well as the average deviation of the y values, the number of the degrees of freedom ny, and the significance Q, giving the probability that chi-square should exceed the achieved value. The matrix of the resulting parameter correlation coefficients is displayed by use of the button Correlations.

The residuals of the fit (the differences between data and function values) can be plotted graphically by use of the button Residuals. The plot displayed in a new window then can be printed and saved as a new plot file with the residual data stored internally.

The dialog may be canceled without saving the parameters by use of the button Cancel. By using Apply the parameters are saved without closing the dialog. With OK the parameters are saved and the dialog is closed. In case of multidimensional fits then the parameters of each selected function will be actualized.

### Smoothing spline fit

The dialog Smoothing spline fit is used to perform a fit of a smoothing spline to a data set. The dialog is opened by selecting Fit in the dialog Items.

In the group Spline the Degree of the spline function as well as the boundaries xmin and xmax of the approximation interval may be set. They give the limits of the range for which the spline can be represented and cover at least the x values of the data set's range selected in the dialog Feld. The Smoothing factor affects the averaged deviation of the spline function from the y values of the data set and is equal to the factor, by which the deviations should differ in the average from the error of the data points. A value of 0 leads to a non-smoothing spline.

In the group Data errors the settings for weighing the data points may be formed. The Array for which the settings are performed is shown by its filename and the column indices for x, y, and errors. When the box Error column is checked, the corresponding column of the data set, selected in the dialog Array, is used as the standard deviation of the y values for performing of the fit. Otherwise the standard deviation will be estimated by an error model function taking the x or the y value as its argument. This function and their parameters may be selected in a dialog which is displayed by clicking Model. A simple error model might be selected by choosing a polynomial with p1 = 0.01, resulting in standard deviations of 1 %.

The fit is performed by clicking the Start button. The obtained number of knots of the spline, the resulting chi-square value as well as the average deviation of the y values are displayed in the listbox in the lower part of the dialog.

The residuals of the fit (the differences between data and spline function values) can be plotted graphically by use of the button Residuals. The plot displayed in a new window then can be printed and saved as a new plot file with the residual data stored internally.

The dialog Roots for finding roots of a cubic spline or of its derivatives is opened by use of the button Roots.

The dialog may be canceled without saving the spline coefficients by use of the button Cancel. By using Apply the coefficients are saved and the plot is updated without closing the dialog. With OK the coefficients are saved and the dialog is closed.

### Roots

The dialog Roots can be opened using the button Roots of the dialogs Function, Smoothing spline, and Smoothing spline fit. It is used to find roots of the function or spline, respectively, or of its derivatives. In case of a function an interpolating (non-smoothing) cubic spline representation is employed, in case of a smoothing spline the current spline is used; its degree has to be cubic.

The Condition for roots to be searched and displayed can be selected. A constant c may be used to find points with nonzero values of the spline or its derivatives. The button Update is used to update the displayed list of points after changing the constant c. The Condition can also be set to Minimum or Maximum. Then points with a vanishing first derivative and a positive (minimum) or negative (maximum) second derivative are listed.

The list of points, consisting of columns with their x, y, y', and y" values, can be exported to a text file using the button Export. A file selection dialog will be opened for this purpose.

The dialog is closed by using the button Close.

### Edit text

The dialog Edit text is used to enter a text containing superscripts, subscripts, and characters of different fonts.

The selection of a Font and a Position is determined by a control sequence starting with the character # and containing two additional characters in the field located right to the button with the symbol <. Using this button inserts the control sequence (or another string, entered manually) at the cursor position to the current text in the field left to the button. Text may be inserted manually at any position in the field. The resulting view is shown immediately in a window above the input field.

The dialog may be canceled without saving by use of the button Cancel. With OK changes are saved and the dialog is closed.

### Kpl settings

The dialog Kpl settings is used to perform basic presettings and the setting for the Autoplot and Autofit features. The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are applied without closing the dialog. With Save Settings changes are applied and saved permanently without closing the dialog. With OK changes are applied and the dialog is closed.

The dialog consists of three pages.

#### Basic settings

The page Basic settings is used to perform the presettings for size and colors of the graphical presentation.

In the group Page format the size of the plot page may be selected. The setting Custom allows to set user defined Width and Height values.

In the group Default colors the preselections of the colors for Frame, Grid, and Data may be performed. Selection is done in the dialog Select Color, opened with the colored buttons.

The Decimal symbol for reading data files can be chosen to be point or comma.

In the group Output format the double value Presentation and the Precision for function parameters and ranges in output files and dialogs may be set, corresponding to the format identifier of the C function `printf()`. The separator char used to separate columns in exported data files can be selected using the combobox Separator. Space, tab or comma characters may be selected.

Also the toggle options of the Settings menu can be set here at once.

When Autofit and Autoplot are checked, an automatic parameter fit will be performed after loading the data file, corresponding to the settings performed on the Autofit settings page.

#### Autoplot settings

The page Autoplot settings is used to perform the settings for automatic scaling of data files loaded by command line parameters, file menu, or by drag and drop.

In the group Axis mode one can choose between only a frame around the data window or additional tick marks on the left and lower sides of the frame or a grid. tick marks and grid may be labeled with numeric values.

In the group Window position and size of the data window may be set.

In the group Labels text for the axis labels and a heading may be entered. Text with special characters is entered most conveniently in the dialog Edit text which shows up when using the buttons right to the entry fields. By checking = path the path of the data files is used as the heading label.

In the group Data the file columns for abscissa and ordinate values may be chosen by x column and y column. 0 corresponds to the first column. Logarithmic scaling can be selected individually by checking log. When Error bar is checked, the column chosen in Error column is used for displaying error bars. Data may be presented by markers (Symbol <= 0) or lines (Symbol > 0). Most conveniently this is selected in the dialog Lines and Markers, opened by the button right to the spin box, which shows the actual line or marker. With Symbol size the relative size of characters and markers as well as the relative line widths (proportional to the width of the data window) may be specified. A setting of 100 % corresponds to the default. When Normalization is checked, powers of ten are evaluated to be multiplied with the numeric data values in case of huge or tiny numbers. If not equal to 1, these normalization factors are included in the axis labels.

The dialog may be canceled without saving by use of the button Cancel. By using Apply changes are saved without closing the dialog. With OK changes are saved and the dialog is closed.

#### Autofit settings

The page Autofit settings is used to perform the settings for automatic parameter fits of functions to data sets, which are combined with the autoplot feature when the option Autofit is activated in the Basic settings.

In the Library field in the group y(x) the path of the shared library containing the function to be fitted may be entered. The button right to the entry field opens a file selection dialog for this purpose.

The name of the Function is entered in another field. When in the same directory as for the shared library a module definition file with the same name but the extension `.def` is present, the function may be chosen from a list in the dialog Functions, opened with the button right to the entry field.

With the button Edit a dialog Parameter may be opened, which allows to enter the values of up to 20 initial parameters of the function. Also the parameters which should be fitted and not kept constant may be selected by checkboxes. When the option Show Function Source is activated in the Settings menu and a C or C++ language source file with the same name as the shared library but the extension `.c` or `.cpp`, respectively, is present in the same directory, its contents is displayed right to the parameter fields, too. The button Load opens a file selection dialog for loading the parameters from an ASCII file (one parameter each line). The button Save opens a file selection dialog for saving the parameters in an ASCII file.

When the box Nonlinear fit is checked, nonlinear parameter fits by employing the iterative Levenberg-Marquardt method will be performed. Otherwise noniterative general linear least square parameter fits are selected. In this case the function must depend linearly on all parameters chosen to be fitted.

When the box Error column is checked, the corresponding column of the data set, selected in the dialog Array, will be used as the standard deviation of the y values for calculation of chi-square. Otherwise the standard deviation will be estimated by an error model function taking the x or the y value as its argument. This function and their parameters may be selected in a dialog which is displayed by clicking Model. A simple error model might be selected by choosing a polynomial with p1 = 0.01, resulting in standard deviations of 1 %.

Termination of the iterative nonlinear parameter fit algorithm may be controlled by setting a Maximum iterations number and a Tolerance value. Fitting will be terminated when either the maximum number of iterations is reached or the relative errors of chi-square or of the parameters have decreased down to the tolerance value.

Markers (Symbol <= 0) or lines (Symbol > 0) may be chosen to present the fitted function. This is done most convenient using the dialog Lines and Markers, to be opened with the button right to the spin box, which shows the actual line or marker.

The Color of lines or markers may be chosen using the dialog Select Color, opened with the colored button.

When Show dialog is active, the dialog Parameter fit is shown when performing the fit, allowing monitoring and interaction.

The resulting parameter settings will be saved automatically on disk, when the option Save parameters is active. The filename is derived from the name of the data file. The extension is set to `.par`.

When Follow parameters is active, the set of initial parameters will not be reset before starting a fit to the next data set of a series of data files.

The dialog may be canceled without saving by use of the button Cancel. With OK changes are saved and the dialog is closed.

## Developer's Guide to Kpl

### Functions

User defined C or C++ functions for graphical presentations of ordinary and parametric functions and for parameter fits are used by &kpl; as shared libraries. These functions return a `double` value and expect a `double` function argument and a pointer to a `double` array of up to 20 parameters:

    double myfunction(double x, const double *p);

Functions for three-dimensional presentations of surfaces return a `double` value and expect two `double` function arguments and a pointer to a `double` array of up to 20 parameters:

    double my3Dfunction(double x, double z, const double *p);

Module definition files (of the type `.def` and the same name as source and library files) are used as a lookup table by &kpl;. They correspond to the output of the program `nm`.

In the directory $`KDEDIR``/share/apps/kpl` a shared library `fkt.so` as well as the source file `fkt.c`, the module definition file `fkt.def`, and a make file `Makefile.fkt` are already installed. The files `fkt.c` and `Makefile.fkt` may be used as examples and have to be customized in this case.

As an example for multidimensional parameter fits, a C++ source file `fcompl.cpp` as well as the corresponding files `fcompl.so`, `fcompl.def`, and `Makefile.fcompl` are provided in the same directory. Here two `double` valued functions make use of the real and imaginary part of a complex function, implemented with the class `complex`.

### DCOP Interface

The DCOP interface allows to control &kpl; by other KDE applications and scripts.

For a KDE application which should make use of the DCOP interface of &kpl; you should include the header file `kpl_stub.h`, which is installed in the directory $`KDEDIR``/include`. You also need to compile the file `kpl_stub.cpp` in $`KDEDIR``/share/apps/kpl` and link it to your application. These two files provide the DCOP interface functions of &kpl; as methods of the class `KplApp_stub`. A C++ example `demo1.cpp` which makes use of them is installed in $`KDEDIR``/share/apps/kpl`.

Beginning with KDE version 3.2 the KDE XmlRpc Daemon (see below) is not longer available. An alternative to use the DCOP interface of &kpl; from scripts written in Python (at least on the local computer) is the use of the DCOP bindings for Python, a part of the KDE package kdebindings, which has to be installed therefore. An example script `demo2.py` is installed in $`KDEDIR``/share/apps/kpl`. It essentially does the same as the C++ example.

The KDE XmlRpc Daemon (`kxmlrpcd`) provides a way to use (with KDE versions < 3.2) the DCOP interface of &kpl; from scripts written in Python by remote procedure calls (RPC) with XML and HTTP, even running on another platform. An example script `demo1.py` is installed in $`KDEDIR``/share/apps/kpl`. It essentially does the same as the C++ example. For Python versions < 2.2 you also need the Python XML-RPC library (available at http://www.pythonware.com/products/xmlrpc/). Note that the authentification mechanism of `kxmlrpcd` needsthe authentification string as the very first parameter of each interface function call.

Unfortunately on several installations the XmlRpc Daemon of KDE fails resulting in errors due to uncomplete remote procedure calls, when more than 1 Kbytes have to be transferred. This will happen when using functions with very long parameter lists like `newFrameItem()` (see below). For KDE 3.1.4 you can apply a patch to the source code of kxmlrpcd. The patch file named kxmlrpcserver-patch is installed in $`KDEDIR``/share/apps/kpl`. You will have to unpack the source package of kdenetwork-3.1.4 (available on ftp://ftp.kde.org/pub/kde/) and to apply the patch in the directory `kdenetwork-3.1.4/kxmlrpc` by running

    % patch -p0 < kxmlrpcserver-patch

After that you should run

    % ./configure

in the directory `kdenetwork-3.1.4` and (at least in the directory `kdenetwork-3.1.4/kxmlrpc`)

    % make

and (as root)

    % make install

The patched version of kxmlrpc then will be active when you login next time.

To test the DCOP interface of &kpl; you also can use the KDE DCOP utilities `dcop` (command line) and `kdcop` (GUI).

The DCOP interface of &kpl; provides the following functions:

#### newPlot

    void newPlot();

Erases the current plot.

#### openPlot

    int openPlot(const QString& url);

Opens a plot file.

Parameters:

`url`

- URL of the file.

Returns: true when succeeded.

#### openData

    int openData(const QString& url);

Opens a data file.

Parameters:

`url`

- URL of the file.

Returns: true when succeeded.

#### doPlot

    void doPlot();

Performs plot.

#### savePlot

    int savePlot(const QString& url);

Saves a plot file.

Parameters:

`url`

- URL of the file.

Returns: true when succeeded.

#### savePS

    int savePS(const QString& url,
                int landscape);

Generates a PostScript file.

Parameters:

`url`

- URL of the file.

`landscape`

- true for landscape orientation.

Returns: true when succeeded.

#### printPlot

    int printPlot(const QString& printerName,
                  const QString& fileName,
                  int landscape,
                  int numCopies);

Prints current plot.

Parameters:

`printerName`

- name of the printer.

`fileName`

- name of the output file (empty for output to printer).

`landscape`

- true for landscape orientation.

`numCopies`

- number of copies.

Returns: true when succeeded.

#### setAutoplotOption

    void setAutoplotOption(int setting);

Sets autoplot option.

Parameters:

`setting`

- true to plot automatically after changes.

#### setAddFilesOption

    void setAddFilesOption(int setting);

Sets add files option.

Parameters:

`setting`

- true to add plot and data files to existing plots.

#### setPathOption

    void setPathOption(int setting);

Sets path saving option.

Parameters:

`setting`

- true to save absolute paths.

#### setBoundingBoxOption

    void setBoundingBoxOption(int setting);

Sets calculate PS bounding box option.

Parameters:

`setting`

- true to calculate automatically the box.

#### setPageFormat

    void setPageFormat(double w,
                       double h);

Sets page size.

Parameters:

`w`

- width in cm.

`h`

- height in cm.

#### setColors

    void setColors(const QString& colFrame,
                   const QString& colGrid,
                   const QString& colData);

Sets default colors (hex-encoded RGB strings, example: "ff" for red).

Parameters:

`colFrame`

- color for frame and labels.

`colGrid`

- color for ticks and grid lines.

`colData`

- color for lines and markers.

#### setOutputFormat

    void setOutputFormat(const QString& pres,
                         int prec);

Sets format for numeric output.

Parameters:

`pres`

- `printf()` presentation character.

`prec`

- precision.

#### setAutoplot

    void setAutoplot(double x0,
                     double w,
                     double y0,
                     double h,
                     int gridmode,
                     const QString& sx,
                     const QString& sy,
                     const QString& sh,
                     int pathHeading,
                     int ix,
                     int iy,
                     int ie,
                     int logx,
                     int logy,
                     int errbars,
                     int symb,
                     int autoNorm,
                     int autoFit);

Sets Autoplot options.

Parameters:

`x0`

- left page margin in centimeters.

`w`

- width of the data window in centimeters.

`y0`

- bottom page margin in centimeters.

`h`

- height of the data window in centimeters.

`gridmode`

- 0 for frame only, 1 for axes with tics, 2 for axes with tics and labels, 3 for grid, 4 for grid with labels.

`sx`

- x axis text.

`sy`

- y axis text.

`sh`

- heading text.

`pathHeading`

- true for heading = path.

`ix`

- x column index.

`iy`

- y column index.

`ie`

- y error column index.

`logx`

- true for logarithmic scaling of x axis.

`logy`

- true for logarithmic scaling of y axis.

`errbars`

- true to plot error bars.

`symb`

- 0 for circles, < 0 for different markers, > 0 for different line types.

`autoNorm`

- true for automatic normalization.

`autoFit`

- true for automatic parameter fit.

#### setAutofit

    void setAutofit(const QString& path,
                    const QString& name,
                    int nonLin,
                    int errCol,
                    const QString& errModPath,
                    const QString& errModName,
                    int itMax,
                    double tol,
                    int symb,
                    const QString& color,
                    int showDlg,
                    int savePar,
                    int follow);

Sets Autofit parameters.

Parameters:

`path`

- absolute path of the library for the fit function.

`name`

- fit function name.

`nonLin`

- true for nonlinear parameter fits.

`errCol`

- true for data weighing by error column, false for weighing by error model function.

`errModPath`

- absolute path of the library for the error model function.

`errModName`

- error model function name.

`itMax`

- maximum number of iterations (nonlinear fits only).

`tol`

- tolerance level (nonlinear fits only).

`symb`

- function plot: 0 for circles, < 0 for different markers, > 0 for different line types.

`color`

- color for function plot.

`showDlg`

- true to display parameter fit dialog.

`savePar`

- true to save resulting parameter files.

`follow`

- true to follow parameter sets in fit series.

#### loadAutofitPar

    int loadAutofitPar(const QString& url);

Loads Autofit function parameters from file.

Parameters:

`url`

- URL of the file.

Returns: true when succeeded.

#### setAutofitPar

    int setAutofitPar(int iPar,
                      double value);

Sets Autofit function parameter value.

Parameters:

`iPar`

- parameter index.

`value`

- parameter value.

Returns: true when succeeded.

#### enableFitPar

    int enableFitPar(int iPar,
                     int fit);

Enables/disables (Auto)fit function parameter.

Parameters:

`iPar`

- parameter index.

`fit`

- true enables parameter fitting.

Returns: true when succeeded.

#### loadErrModPar

    int loadErrModPar(const QString& url,
                      int iArr);

Loads error model function parameters from file.

Parameters:

`url`

- URL of the file.

`iArr`

- array list index.

Returns: true when succeeded.

#### setErrModPar

    int setErrModPar(int iPar,
                     double value,
                     int iArr);

Sets error model function parameter value.

Parameters:

`iPar`

- parameter index.

`value`

- parameter value.

`iArr`

- array list index.

Returns: true when succeeded.

#### deleteItem

    int deleteItem(int iItem);

Deletes plot item.

Parameters:

`iItem`

- item index.

Returns: true when succeeded.

#### moveItem

    int moveItem(int is,
                 int id);

Moves plot item.

Parameters:

`is`

- source item index.

`id`

- destination item index.

Returns: true when succeeded.

#### activateItem

    int activateItem(int iItem,
                     int active);

Sets activation state of plot item.

Parameters:

`iItem`

- item index.

`active`

- true for visible item.

Returns: true when succeeded.

#### newFrameItem

    void newFrameItem(double x0,
                      double w,
                      double y0,
                      double h,
                      double xmin,
                      double xmax,
                      double ymin,
                      double ymax,
                      int logx,
                      int logy,
                      int ndigx,
                      int ndigy,
                      const QString& colFrame,
                      const QString& colGrid,
                      double xtic,
                      double ytic,
                      int mticx,
                      int mticy,
                      int gridmode,
                      int iex,
                      int iey,
                      const QString& sx,
                      const QString& sy,
                      const QString& sh,
                      double relSize,
                      int active);

Appends new frame item.

Parameters:

`x0`

- left page margin in centimeters.

`w`

- width in centimeters.

`y0`

- bottom page margin in centimeters.

`h`

- height in centimeters.

`xmin`

- x value of left data window margin in user units.

`xmax`

- x value of right data window margin in user units.

`ymin`

- y value of bottom data window margin in user units.

`ymax`

- y value of top window data margin in user units.

`logx`

- true for logarithmic scaling of x axis.

`logy`

- true for logarithmic scaling of y axis.

`ndigx`

- number of digits for x axis.

`ndigy`

- number of digits for y axis.

`colFrame`

- color for frame and labels.

`colGrid`

- color for grids and tics.

`xtic`

- distance between major tics of x axis.

`ytic`

- distance between major tics of y axis.

`mticx`

- number of intervals between major tics of x axis.

`mticy`

- number of intervals between major tics of y axis.

`gridmode`

- 0 for frame only, 1 for axes with tics, 2 for axes with tics and labels, 3 for grid, 4 for grid with labels.

`iex`

- logarithm of normalization factor for x axis.

`iey`

- logarithm of normalization factor for y axis.

`sx`

- x axis text.

`sy`

- y axis text.

`sh`

- heading text.

`relSize`

- relative size of text, markers and lines.

`active`

- true for visible item.

#### newAutoFrameItem

    void newAutoFrameItem();

Appends new frame item corresponding to the autoplot settings.

#### newArrayItem

    int newArrayItem(const QString& path,
                     int ix,
                     int iy,
                     int ie,
                     int istart,
                     int n,
                     int errbars,
                     int symb,
                     const QString& color,
                     double fx,
                     double fy,
                     int active);

Appends new array item.

Parameters:

`path`

- absolute path of the data file.

`ix`

- x column index.

`iy`

- y column index.

`ie`

- y error column index.

`istart`

- start row index.

`n`

- number of data points.

`errbars`

- true to plot error bars.

`symb`

- 0 for circles, < 0 for different markers, > 0 for different line types.

`color`

- color for data plot.

`fx`

- normalization factor for x values.

`fy`

- normalization factor for y values.

`active`

- true for visible item.

Returns: true when succeeded.

#### newFunItem

    int newFunItem(const QString& path,
                   const QString& name,
                   double xmin,
                   double xmax,
                   double dx,
                   int symb,
                   const QString& color,
                   double fx,
                   double fy,
                   int active);

Appends new function item.

Parameters:

`path`

- absolute path of the function library.

`name`

- function name.

`xmin`

- minimum argument value.

`xmax`

- maximum argument value.

`dx`

- argument stepsize.

`symb`

- 0 for circles, < 0 for different markers, > 0 for different line types.

`color`

- color for function plot.

`fx`

- normalization factor for x values.

`fy`

- normalization factor for y values.

`active`

- true for visible item.

Returns: true when succeeded.

#### newParFunItem

    int newParFunItem(const QString& pathx,
                      const QString& namex,
                      const QString& pathy,
                      const QString& namey,
                      double tmin,
                      double tmax,
                      double dt,
                      int symb,
                      const QString& color,
                      double fx,
                      double fy,
                      int active);

Appends new parametric function item.

Parameters:

`pathx`

- absolute path of the x function library.

`namex`

- x function name.

`pathy`

- absolute path of the y function library.

`namey`

- y function name.

`tmin`

- minimum argument value.

`tmax`

- maximum argument value.

`dt`

- argument stepsize.

`symb`

- 0 for circles, < 0 for different markers, > 0 for different line types.

`color`

- color for function plot.

`fx`

- normalization factor for x values.

`fy`

- normalization factor for y values.

`active`

- true for visible item.

Returns: true when succeeded.

#### newSplineItem

    void newSplineItem(int deriv,
                       double low,
                       double xmin,
                       double xmax,
                       double dx,
                       int symb,
                       const QString& color,
                       double relSize,
                       double fx,
                       double fy,
                       int active);

Appends new spline item.

Parameters:

`deriv`

- order of the derivative, 0 for function itself, -1 for integral.

`low`

- lower limit for spline integral.

`xmin`

- minimum argument value.

`xmax`

- maximum argument value.

`dx`

- argument step size.

`symb`

- 0 for circles, < 0 for different markers, > 0 for different line types.

`color`

- color for spline function plot.

`relSize`

- relative size of text, markers and lines.

`fx`

- normalization factor for x values.

`fy`

- normalization factor for y values.

`active`

- true for visible item.

#### newArray3DItem

    int newArray3DItem(double x0,
                       double w,
                       double y0,
                       double h,
                       double xmin,
                       double xmax,
                       double ymin,
                       double ymax,
                       double zmin,
                       double zmax,
                       int logx,
                       int logy,
                       int logz,
                       int ndigx,
                       int ndigy,
                       int ndigz,
                       const QString& colFrame,
                       const QString& colGrid,
                       const QString& colData,
                       double xtic,
                       double ytic,
                       double ztic,
                       int mticx,
                       int mticy,
                       int mticz,
                       int frame,
                       int gridmode,
                       int gridmode3D,
                       double xBox,
                       double yBox,
                       double zBox,
                       double xRef,
                       double yRef,
                       double phi,
                       double theta,
                       int iex,
                       int iey,
                       int iez,
                       const QString& sx,
                       const QString& sy,
                       const QString& sz,
                       const QString& sh,
                       double relSize,
                       const QString& path,
                       int ix,
                       int iy,
                       int iz,
                       int ie,
                       int istart,
                       int n,
                       int errbars,
                       double smf,
                       double dx,
                       double dz,
                       double fx,
                       double fy,
                       double fz,
                       int active);

Appends new 3D array item.

Parameters:

`x0`

- left page margin in centimeters.

`w`

- width in centimeters.

`y0`

- bottom page margin in centimeters.

`h`

- height in centimeters.

`xmin`

- minimum x value.

`xmax`

- maximum x value.

`ymin`

- minimum y value.

`ymax`

- maximum y value.

`zmin`

- minimum z value.

`zmax`

- maximum z value.

`logx`

- true for logarithmic scaling of x axis.

`logy`

- true for logarithmic scaling of y axis.

`logz`

- true for logarithmic scaling of z axis.

`ndigx`

- number of digits for x axis.

`ndigy`

- number of digits for y axis.

`ndigz`

- number of digits for z axis.

`colFrame`

- color for frame and labels.

`colGrid`

- color for tics.

`colData`

- color for surface.

`xtic`

- distance between major tics of x axis.

`ytic`

- distance between major tics of y axis.

`ztic`

- distance between major tics of z axis.

`mticx`

- number of intervals between major tics of x axis.

`mticy`

- number of intervals between major tics of y axis.

`mticz`

- number of intervals between major tics of z axis.

`frame`

- true to show frame.

`gridmode`

- 0 for frame only, 1 for axes with tics, 2 for axes with tics and labels.

`gridmode3D`

- 0 for lines parallel to x, 1 for lines parallel to z, 2 for grid.

`xBox`

- x box width in cm.

`yBox`

- y box width in cm.

`zBox`

- z box width in cm.

`xRef`

- x position of center of box bottom plane.

`yRef`

- y position of center of box bottom plane.

`phi`

- angle of rotation about y axis in deg.

`theta`

- tilt angle of y axis in deg.

`iex`

- logarithm of normalization factor for x axis.

`iey`

- logarithm of normalization factor for y axis.

`iez`

- logarithm of normalization factor for z axis.

`sx`

- x axis text.

`sy`

- y axis text.

`sz`

- z axis text.

`sh`

- heading text.

`relSize`

- relative size of text and lines.

`path`

- absolute path of the data file.

`ix`

- x column index.

`iy`

- y column index.

`iz`

- z column index.

`ie`

- y error column index.

`istart`

- start row index.

`n`

- number of data points.

`errbars`

- true to use error bars for weighing y values.

`smf`

- smoothing factor.

`dx`

- x grid stepsize.

`dz`

- z grid stepsize.

`fx`

- normalization factor for x values.

`fy`

- normalization factor for y values.

`fz`

- normalization factor for z values.

`active`

- true for visible item.

Returns: true when succeeded.

#### newFun3DItem

    int newFun3DItem(double x0,
                     double w,
                     double y0,
                     double h,
                     double xmin,
                     double xmax,
                     double ymin,
                     double ymax,
                     double zmin,
                     double zmax,
                     int logx,
                     int logy,
                     int logz,
                     int ndigx,
                     int ndigy,
                     int ndigz,
                     const QString& colFrame,
                     const QString& colGrid,
                     const QString& colData,
                     double xtic,
                     double ytic,
                     double ztic,
                     int mticx,
                     int mticy,
                     int mticz,
                     int frame,
                     int gridmode,
                     int gridmode3D,
                     double xBox,
                     double yBox,
                     double zBox,
                     double xRef,
                     double yRef,
                     double phi,
                     double theta,
                     int iex,
                     int iey,
                     int iez,
                     const QString& sx,
                     const QString& sy,
                     const QString& sz,
                     const QString& sh,
                     double relSize,
                     const QString& path,
                     const QString& name,
                     double dx,
                     double dz,
                     double fx,
                     double fy,
                     double fz,
                     int active);

Appends new 3D function item.

Parameters:

`x0`

- left page margin in centimeters.

`w`

- width in centimeters.

`y0`

- bottom page margin in centimeters.

`h`

- height in centimeters.

`xmin`

- minimum x value.

`xmax`

- maximum x value.

`ymin`

- minimum y value.

`ymax`

- maximum y value.

`zmin`

- minimum z value.

`zmax`

- maximum z value.

`logx`

- true for logarithmic scaling of x axis.

`logy`

- true for logarithmic scaling of y axis.

`logz`

- true for logarithmic scaling of z axis.

`ndigx`

- number of digits for x axis.

`ndigy`

- number of digits for y axis.

`ndigz`

- number of digits for z axis.

`colFrame`

- color for frame and labels.

`colGrid`

- color for tics.

`colData`

- color for surface.

`xtic`

- distance between major tics of x axis.

`ytic`

- distance between major tics of y axis.

`ztic`

- distance between major tics of z axis.

`mticx`

- number of intervals between major tics of x axis.

`mticy`

- number of intervals between major tics of y axis.

`mticz`

- number of intervals between major tics of z axis.

`frame`

- true to show frame.

`gridmode`

- 0 for frame only, 1 for axes with tics, 2 for axes with tics and labels.

`gridmode3D`

- 0 for lines parallel to x, 1 for lines parallel to z, 2 for grid.

`xBox`

- x box width in cm.

`yBox`

- y box width in cm.

`zBox`

- z box width in cm.

`xRef`

- x position of center of box bottom plane.

`yRef`

- y position of center of box bottom plane.

`phi`

- angle of rotation about y axis in deg.

`theta`

- tilt angle of y axis in deg.

`iex`

- logarithm of normalization factor for x axis.

`iey`

- logarithm of normalization factor for y axis.

`iez`

- logarithm of normalization factor for z axis.

`sx`

- x axis text.

`sy`

- y axis text.

`sz`

- z axis text.

`sh`

- heading text.

`relSize`

- relative size of text and lines.

`path`

- absolute path of the function library.

`name`

- function name.

`dx`

- x argument stepsize.

`dz`

- z argument stepsize.

`fx`

- normalization factor for x values.

`fy`

- normalization factor for y values.

`fz`

- normalization factor for z values.

`active`

- true for visible item.

Returns: true when succeeded.

#### newImageItem

    void newImageItem(const QString& path,
                      double x,
                      double y,
                      double fx,
                      double fy,
                      int active);

Appends new image item.

Parameters:

`path`

- absolute path of the EPS file.

`x`

- x position in cm.

`y`

- y position in cm.

`fx`

- horizontal scaling factor.

`fy`

- vertical scaling factor.

`active`

- true for visible item.

#### newLegendItem

    void newLegendItem(int symb,
                       const QString& colSymb,
                       double x,
                       double y,
                       const QString& text,
                       const QString& colText,
                       double xoff,
                       double yoff,
                       double relSize,
                       int active);

Appends new legend item.

Parameters:

`symb`

- 0 for circles, < 0 for different markers, > 0 for different line types.

`colSymb`

- color for marker or line.

`x`

- x position in cm.

`y`

- y position in cm.

`text`

- legend text.

`colText`

- color for text.

`xoff`

- x offset for text in cm.

`yoff`

- y offset for text in cm.

`relSize`

- relative size of text.

`active`

- true for visible item.

#### newTextItem

    void newTextItem(const QString& text,
                     const QString& color,
                     int align,
                     double x,
                     double y,
                     double dir,
                     double relSize,
                     int active);

Appends new text item.

Parameters:

`text`

- text.

`color`

- color for text.

`align`

- 1: left aligned, 2: centered, 3: right aligned.

`x`

- x position in cm.

`y`

- y position in cm.

`dir`

- direction in degree.

`relSize`

- relative size of text.

`active`

- true for visible item.

#### newLineItem

    void newLineItem(int symb,
                     const QString& color,
                     double x,
                     double y,
                     double dir,
                     double len,
                     double relSize,
                     int active);

Appends new line item.

Parameters:

`symb`

- 1 to 9 for different line types.

`color`

- color for line.

`x`

- x start position in cm.

`y`

- y start position in cm.

`dir`

- direction in degree.

`len`

- length in cm.

`relSize`

- relative width.

`active`

- true for visible item.

#### newArrowItem

    void newArrowItem(const QString& color,
                      double x,
                      double y,
                      double dir,
                      double len,
                      double relSize,
                      int active);

Appends new arrow item.

Parameters:

`color`

- color for arrow.

`x`

- x position of head in cm.

`y`

- y position of head in cm.

`dir`

- direction in degree.

`len`

- length in cm.

`relSize`

- relative width.

`active`

- true for visible item.

Returns: true when succeeded.

#### newArcItem

    void newArcItem(const QString& color,
                    double x,
                    double y,
                    double w,
                    double h,
                    double a,
                    double alen,
                    double relSize,
                    double ang,
                    int active);

Appends new elliptic arc item.

Parameters:

`color`

- color of the arc.

`x`

- x position of center in cm.

`y`

- y position of center in cm.

`w`

- width of ellipse in cm.

`h`

- height of ellipse in cm.

`a`

- start angle in degree.

`alen`

- length in degree.

`relSize`

- relative line width.

`ang`

- rotation angle in degree.

`active`

- true for visible item.

#### newRectangleItem

    void newRectangleItem(const QString& color,
                          double x,
                          double y,
                          double w,
                          double h,
                          double relSize,
                          int fill,
                          int active);

Appends new rectangle item.

Parameters:

`color`

- color of the rectangle.

`x`

- x position of left side in cm.

`y`

- y position of bottom side in cm.

`w`

- width in cm.

`h`

- height in cm.

`relSize`

- relative line width.

`fill`

- true for rectangle filled with color.

`active`

- true for visible item.

#### newEllipseItem

    void newEllipseItem(const QString& color,
                        double x,
                        double y,
                        double w,
                        double h,
                        double relSize,
                        int fill,
                        int active);

Appends new ellipse item.

Parameters:

`color`

- color of the ellipse.

`x`

- x position of center in cm.

`y`

- y position of center in cm.

`w`

- width in cm.

`h`

- height in cm.

`relSize`

- relative line width.

`fill`

- true ellipse filled with color.

`active`

- true for visible item.

#### newScaleBarItem

    void newScaleBarItem(const QString& str,
                         const QString& color,
                         double x,
                         double y,
                         double len,
                         double relSize,
                         int orientation,
                         int active);

Appends new scale bar item.

Parameters:

`str`

- Text.

`color`

- color of the scale bar.

`x`

- x position in cm.

`y`

- y position in cm.

`len`

- length in cm.

`relSize`

- relative line width.

`orientation`

- 0 for horizontal, 1 for vertical.

`active`

- true for visible item.

#### autoScaleFrame

    int autoScaleFrame(int iItem,
                       int autoNorm);

Scales frame automatically according to all items belonging to it.

Parameters:

`iItem`

- index of frame item.

`autoNorm`

- true for additional automatic normalization.

Returns: true when succeeded.

#### loadPar

    int loadPar(const QString& url,
                int iItem,
                int yFun);

Loads set of function parameters from file.

Parameter:

`url`

- URL of file.

`iItem`

- Index of function item.

`yFun`

- true for y function parameters, false for x function parameters (only for parametric functions).

Returns: true when succeeded.

#### setPar

    int setPar(int iItem,
               int iPar,
               double value,
               int yFun);

Sets value of a function parameter.

Parameter:

`iItem`

- index of function item.

`iPar`

- index of parameter.

`value`

- value of parameter.

`yFun`

- true for y function parameters, false for x function parameters (only for parametric functions).

Returns: true when succeeded.

#### setArrayRange

    int setArrayRange(int iItem,
                      int iStart,
                      int n);

Sets range of rows of an array.

Parameter:

`iItem`

- Index of array item.

`iStart`

- start index of rows.

`n`

- number of data points.

Returns: true when succeeded.

#### addFitItems

    int addFitItems(int erase,
                    int iArr,
                    int iFun,
                    int errCol,
                    const QString& errModPath,
                    const QString& errModName);

Adds array and function items to a list for (multidimensional) parameter fits.

Parameter:

`erase`

- true: clears list first.

`iArr`

- index of array item.

`iFun`

- index of function item.

`errCol`

- true for weighing of data points by error column, false for weighing by error model function.

`errModPath`

- absolute path of library containing the error model function.

`errModName`

- name of the error model function.

Returns: true when succeeded.

#### fit

    int fit(int nonLin,
            int savePar,
            int follow);

Performs parameter fit.

Parameters:

`nonLin`

- true for nonlinear parameter fits.

`savePar`

- true to save resulting parameter files.

`follow`

- true to follow parameter sets in fit series.

Returns: true when succeeded.

#### splineFit

    int splineFit(int iArr,
                  int iSpl,
                  int deg,
                  double smf,
                  double xmin,
                  double xmax,
                  int errCol,
                  const QString& errModPath,
                  const QString& errModName);

Performs smoothing spline fit.

Parameters:

`iArr`

- array item index.

`iSpl`

- spline item index.

`deg`

- degree of spline.

`smf`

- smoothing factor.

`xmin`

- lower boundary of approximation interval.

`xmax`

- upper boundary of approximation interval.

`errCol`

- true for data weighing by error column, false for weighing by error model function.

`errModPath`

- absolute path of the library for the error model function.

`errModName`

- error model function name.

Returns: true when succeeded.

#### chiSquare

    double chiSquare();

Returns chi-square of last fit.

Returns: chi-square.

#### saveFitPar

    int saveFitPar(const QString& url);

Saves parameters and their errors resulting from a fit to a file.

Parameters:

`url`

- URL of the file.

Returns: true when succeeded.

#### exportValues

    int exportValues(const QString& url,
                     int iItem);

Exports function value table to file.

Parameters:

`url`

- URL of the file.

`iItem`

- item index.

Returns: true when succeeded.

## Questions and Answers

The automatic calculation of the Bounding Box for PostScript files does not work correctly. The calculated values cut off parts of the plot. What's wrong?

To work correctly, the Page format must be set sufficiently large on the page Basic Settings of the Kpl Settings dialog, because &kpl; uses this area to look for the smallest rectangle containing all plotted items.

Why does my plot of a data file end with a line to the origin, when the last point of the file does not have the coordinates (0,0)?

Your data file seems to end with some invisible but interfering bytes. Delete them!

Why does the dash pattern of subsequent curves not start at the same point?

This allows you to plot a curve consisting of several pieces (e.g. with different function stepwidth) without "jumps" in the dash pattern. You can reset the dash pattern position by placing legends (invisible by choosing symbol -17 and empty text) before the corresponding items.

## Credits and License

&kpl;

Program copyright 2005 Werner Stille stille@uni-freiburg.de

Thanks to

- the KDevelop Team for making KDE programming much more easy

- Dimi Shahbaz dshahbaz@ucla.edu for suggestions and patches

- Jürgen Siepmann siepmann@kanzlei-siepmann.de for testing and criticism

- Wojciech Migda migda@chemia.uj.edu.pl for the polish translation

- Taiki Komoda kom@kde.gr.jp for the japanese translation

- Alan Mizrahi alan@ldc.usb.ve for the spanish translation

- Paul Dierckx Paul.Dierckx@cs.kuleuven.ac.be for FITPACK, the FORTRAN program collection described in his book "Curve and Surface Fitting with Splines", Oxford University Press, 1993 (C++ versions of several FITPACK functions are used in &kpl;)

Documentation copyright 2005 Werner Stille stille@uni-freiburg.de

&underFDL; &underGPL;

## Installation

### How to Obtain &kpl;

&kpl; can be found on its homepage http://frsl06.physik.uni-freiburg.de/privat/stille/kpl/ and on ftp://ftp.kde.org/pub/kde/, the main ftp site of the KDE project.

### Requirements

In order to successfully use &kpl;, you need KDE. The PostScript interpreter Ghostscript is required for the automatic calculation of bounding boxes for generated PostScript files.

### Compilation and Installation

In order to compile and install &kpl; on your system, type the following in the base directory of &kpl; distribution:

    % ./configure
    % make
    % make install

Since &kpl; uses autoconf and automake you should have not trouble compiling it. Should you run into problems please report them to the author of &kpl;.