<chapter id="reference">
<title>&kmplot; Reference</title>
<!--
<mediaobject>
<imageobject>
<imagedata fileref="kfkt.png" format="PNG"/>
</imageobject>
</mediaobject>
<para>This menu entry or toolbar button opens the Functions Editor. Here
you can enter up to 10 functions or
function groups. The parser knows <firstterm>explicit</firstterm> and
<firstterm>parametric</firstterm> form. With specific extensions it
is possible to add first and second derivatives and to choose values
for the function group parameter.</para>
-->
<sect1 id="func-syntax">
<title>Function Syntax</title>
<para>Some syntax rules must be complied with:</para>
<screen>
<userinput>name(var1[, var2])=term [;extensions]</userinput>
</screen>
<variablelist>
<varlistentry>
<term>name</term>
<listitem>
<para>The function name. If the first character is <quote>r</quote>
the parser assumes that you are using polar coordinates. If the first
character is <quote>x</quote> (for instance <quote>xfunc</quote>) the
parser expects a second function with a leading <quote>y</quote> (here
<quote>yfunc</quote>) to define the function in parametric form.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>var1</term>
<listitem><para>The function's variable</para></listitem>
</varlistentry>
<varlistentry>
<term>var2</term>
<listitem><para> The function <quote>group parameter</quote>. It must be
separated from the function's variable by a comma. You can use the group
parameter to, for example, plot a number of graphs from one function. The parameter values can be selected manually or you can choose to have a slider bar that controls one parameter. By changing the value of the slider the value parameter will be changed. The slider can be set to an integer between 0 and 100.</para></listitem>
</varlistentry>
<varlistentry>
<term>term</term>
<listitem><para>The expression defining the function.</para></listitem>
</varlistentry>
</variablelist>
</sect1>
<sect1 id="func-predefined">
<title>Predefined Function Names and Constants</title>
<para>
All the predefined functions and constants that &kmplot; knows can be shown by
selecting <menuchoice><guimenu>Help</guimenu><guimenuitem>Predefined Math Functions</guimenuitem>
</menuchoice>, which displays this page of &kmplot;'s handbook.
</para>
<para>
These functions and constants and even all user defined functions can
be used to determine the axes settings as well. See <xref linkend="axes-config"/>.
</para>
<sect2 id="trigonometric-functions">
<title>Trigonometric Functions</title>
<para>
By default, the trigonometric functions work in radians. However, this can be changed via <menuchoice><guimenu>Settings</guimenu><guimenuitem>Configure &kmplot;</guimenuitem></menuchoice>.
</para>
<variablelist>
<varlistentry>
<term>sin(x)</term>
<term>arcsin(x)</term>
<term>cosec(x)</term>
<term>arccosec(x)</term>
<listitem><para>The sine, inverse sine, cosecant and inverse cosecant respectively.</para></listitem>
</varlistentry>
<varlistentry>
<term>cos(x)</term>
<term>arccos(x)</term>
<term>sec(x)</term>
<term>arcsec(x)</term>
<listitem><para>The cosine, inverse cosine, secant and inverse secant respectively.</para></listitem>
</varlistentry>
<varlistentry>
<term>tan(x)</term>
<term>arctan(x)</term>
<term>cot(x)</term>
<term>arccot(x)</term>
<listitem><para>The tangent, inverse tangent, cotangent and inverse cotangent respectively.</para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="hyperbolic-functions">
<title>Hyperbolic Functions</title>
<para>The Hyperbolic Functions.</para>
<variablelist>
<varlistentry>
<term>sinh(x)</term>
<term>arcsinh(x)</term>
<term>cosech(x)</term>
<term>arccosech(x)</term>
<listitem><para>The hyperbolic sine, inverse sine, cosecant and inverse cosecant respectively.</para></listitem>
</varlistentry>
<varlistentry>
<term>cosh(x)</term>
<term>arccosh(x)</term>
<term>sech(x)</term>
<term>arcsech(x)</term>
<listitem><para>The hyperbolic cosine, inverse cosine, secant and inverse secant respectively.</para></listitem>
</varlistentry>
<varlistentry>
<term>tanh(x)</term>
<term>arctanh(x)</term>
<term>coth(x)</term>
<term>arccoth(x)</term>
<listitem><para>The hyperbolic tangent, inverse tangent, cotangent and inverse cotangent respectively.</para></listitem>
</varlistentry>
</variablelist>
</sect2>
<sect2 id="other-functions">
<title>Other Functions</title>
<variablelist>
<varlistentry>
<term>sqr(x)</term>
<listitem><para>The square x^2 of x.</para></listitem>
</varlistentry>
<varlistentry>
<term>sqrt(x)</term>
<listitem><para>The square root of x.</para></listitem>
</varlistentry>
<varlistentry>
<term>sign(x)</term>
<listitem><para>The sign of x. Returns 1 if x is positive, 0 if x is zero, or −1 if x is negative.</para></listitem>
</varlistentry>
<varlistentry>
<term>H(x)</term>
<listitem><para>The Heaviside Step Function. Returns 1 if x is positive, 0.5 if x is zero, or 0 if x is negative.</para></listitem>
</varlistentry>
<varlistentry>
<term>exp(x)</term>
<listitem><para>The exponent e^x of x.</para></listitem>
</varlistentry>
<varlistentry>
<term>ln(x)</term>
<listitem><para>The natural logarithm (inverse exponent) of x.</para></listitem>
</varlistentry>
<varlistentry>
<term>log(x)</term>
<listitem><para>The logarithm of x to base 10.</para></listitem>
</varlistentry>
<varlistentry>
<term>abs(x)</term>
<listitem><para>The absolute value of x.</para></listitem>
</varlistentry>
<varlistentry>
<term>floor(x)</term>
<listitem><para>Rounds x to closest integer less than or equal to x.</para></listitem>
</varlistentry>
<varlistentry>
<term>ceil(x)</term>
<listitem><para>Rounds x to the closest integer greater than or equal to x.</para></listitem>
</varlistentry>
<varlistentry>
<term>round(x)</term>
<listitem><para>Rounds x to the closest integer.</para></listitem>
</varlistentry>
<varlistentry>
<term>gamma(x)</term>
<listitem><para>The gamma function.</para></listitem>
</varlistentry>
<varlistentry>
<term>factorial(x)</term>
<listitem><para>The factorial of x.</para></listitem>
</varlistentry>
<varlistentry>
<term>min(x<subscript>1</subscript>,x<subscript>2</subscript>,...,x<subscript>n</subscript>)</term>
<listitem><para>Returns the minimum of the set of numbers {x<subscript>1</subscript>,x<subscript>2</subscript>,...,x<subscript>n</subscript>}.</para></listitem>
</varlistentry>
<varlistentry>
<term>max(x<subscript>1</subscript>,x<subscript>2</subscript>,...,x<subscript>n</subscript>)</term>
<listitem><para>Returns the maximum of the set of numbers {x<subscript>1</subscript>,x<subscript>2</subscript>,...,x<subscript>n</subscript>}.</para></listitem>
</varlistentry>
<varlistentry>
<term>mod(x<subscript>1</subscript>,x<subscript>2</subscript>,...,x<subscript>n</subscript>)</term>
<listitem><para>Returns the modulus (Euclidean length) of the set of numbers {x<subscript>1</subscript>,x<subscript>2</subscript>,...,x<subscript>n</subscript>}.</para></listitem>
</varlistentry>
<!-- TODO: Legendre polynomials -->
</variablelist>
</sect2>
<sect2>
<title>Predefined Constants</title>
<variablelist>
<varlistentry>
<term>pi</term>
<term>&pgr;</term>
<listitem>
<para>Constants representing &pgr; (3.14159...).</para>
</listitem>
</varlistentry>
<varlistentry>
<term>e</term>
<listitem>
<para>Constant representing Euler's Number e (2.71828...).</para>
</listitem>
</varlistentry>
</variablelist>
</sect2>
</sect1>
<sect1 id="func-extension">
<title>Extensions</title>
<para>An extension for a function is specified by entering a semicolon,
followed by the extension, after the function definition. The extension can be entered by using the &DBus; method parser addFunction. None of the extensions are available
for parametric functions but N and D[a,b] work for polar functions too. For example:
<screen>
<userinput>
f(x)=x^2; A1
</userinput>
</screen>
will show the graph y=x<superscript>2</superscript> with its first
derivative. Supported extensions are described below:
<variablelist>
<varlistentry>
<term>N</term>
<listitem>
<para>
The function will be stored but not be drawn.
It can be used like any other user-defined or predefined function.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A1</term>
<listitem>
<para>
The graph of the derivative of the function will be drawn
additionally with the same color but less line width.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>A2</term>
<listitem>
<para>
The graph of the second derivative of the function will be
drawn additionally with the same color but less line width.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>D[a,b]</term>
<listitem>
<para>
Sets the domain for which the function will be displayed.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term>P[a{,b...}]</term>
<listitem>
<para>
Give a set of values of a group parameter for which the function should be
displayed. For example: <userinput>f(x,k)=k*x;P[1,2,3]</userinput> will plot
the functions f(x)=x, f(x)=2*x and f(x)=3*x. You can also use functions as the
arguments to the P option.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Please note that you can do all of these operations by editing the items in the <guilabel>Derivates</guilabel> tab, the <guilabel>Custom plot range</guilabel> section and the <guilabel>Parameters</guilabel> section in the <guilabel>Functions</guilabel> sidebar too.
</para>
</sect1>
<sect1 id="math-syntax">
<title>Mathematical Syntax</title>
<para>&kmplot; uses a common way of expressing mathematical functions, so you
should have no trouble working it out. The operators &kmplot; understands are,
in order of decreasing precedence:
<variablelist>
<varlistentry>
<term>^</term>
<listitem><para>The caret symbol performs exponentiation. ⪚,
<userinput>2^4</userinput> returns 16.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>*</term>
<term>/</term>
<listitem>
<para>The asterisk and slash symbols perform multiplication and
division . ⪚,
<userinput>3*4/2</userinput> returns 6.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>+</term>
<term>−</term>
<listitem><para>The plus and minus symbols perform addition and
subtraction. ⪚, <userinput>1+3−2</userinput> returns 2.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><</term>
<term>></term>
<term>≤</term>
<term>≥</term>
<listitem><para>Comparison operators. They return 1 if the expression is true, otherwise they return 0.
⪚, <userinput>1 ≤ 2</userinput> returns 1.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>√</term>
<listitem><para>The square root of a number.
⪚, <userinput>√4</userinput> returns 2.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>|x|</term>
<listitem><para>The absolute value of x. ⪚,
<userinput>|−4|</userinput> returns 4.</para>
</listitem>
</varlistentry>
<varlistentry>
<term>±</term>
<term></term>
<listitem><para>Each plus-minus sign gives two sets of plots: one in which the plus is taken, and one in which the minus is taken.⪚.
<userinput>y = ±sqrt(1−x^2)</userinput> will draw a circle.
These, therefore, cannot be used in constants. </para>
</listitem>
</varlistentry>
</variablelist>
</para>
<para>
Note the precedence, which means that if parentheses are not used,
exponentiation is performed before multiplication/division, which is performed
before addition/subtraction. So <userinput>1+2*4^2</userinput> returns 33, and
not, say 144. To override this, use parentheses. To use the above example,
<userinput>((1+2)*4)^2</userinput> <emphasis>will</emphasis> return 144.
</para>
</sect1>
<!--
<sect1 id="coord-system">
<title>Coordinate Systems</title>
<para><inlinemediaobject>
<imageobject>
<imagedata fileref="ksys1.png" format="PNG"/>
</imageobject>
</inlinemediaobject></para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="ksys2.png" format="PNG"/>
</imageobject>
</inlinemediaobject></para>
<para>
<inlinemediaobject>
<imageobject>
<imagedata fileref="ksys3.png" format="PNG"/>
</imageobject>
</inlinemediaobject></para>
-->
<sect1 id="coord-area"><title>Plotting Area</title>
<para>
By default, explicitly given functions are plotted for the whole of the visible part of the
x-axis. You can specify an other range in the edit-dialog for the function.
If the plotting area contains the resulting point it is connected to the last
drawn point by a line.
</para>
<para>
Parametric and polar functions have a default plotting range of 0 to 2&pgr;.
This plotting range can also be changed in the <guilabel>Functions</guilabel> sidebar.
</para>
</sect1>
<sect1 id="coord-cross">
<title>Crosshair Cursor</title>
<para>
While the mouse cursor is over the plotting area the cursor changes to a crosshair. The current coordinates can be seen at the intersections with the coordinate axes and also in the status bar at the bottom of the main window.
</para>
<para>
You can trace a function's values more precisely by clicking onto or next to a graph. The selected function is shown in the status bar in the right column. The crosshair then will be caught and be colored in the same color as the graph. If the graph has the same color as the background color, the crosshair will have the inverted color of the background. When moving the mouse or pressing the keys Left or Right the crosshair will follow the function and you see the current x- and y-value. If the crosshair is close to y-axis, the root-value is shown in the statusbar. You can switch function with the Up and Down keys. A second click anywhere in the window or pressing any non-navigating key will leave this trace mode.
</para>
<para>
For more advanced tracing, open up the configuration dialog, and select <guilabel>Draw tangent and normal when tracing</guilabel> from the <guilabel>General Settings</guilabel> page. This option will draw the tangent, normal and oscillating circle of the plot currently being traced.
</para>
</sect1>
<sect1 id="coords-config">
<title><guimenuitem>Coordinate System</guimenuitem> Configuration</title>
<para>To open this dialog select <menuchoice><guimenu>View</guimenu><guimenuitem>Coordinate System..</guimenuitem></menuchoice> from the menubar.</para>
<screenshot>
<screeninfo>Screenshot of the Coordinate System dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="settings-coords.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Screenshot of the Coordinate System dialog</phrase>
</textobject>
</mediaobject>
</screenshot>
<sect2 id="axes-config">
<title><guilabel>Axes</guilabel> Configuration</title>
<para>
<variablelist>
<varlistentry>
<term><guilabel>X-axis Range</guilabel></term>
<listitem>
<para>Sets the range for the x-axis scale.
Note that you can use the
predefined functions and constants (see <xref linkend="func-predefined"/>) as
the extremes of the range (⪚, set <guilabel>Min:</guilabel> to
<userinput>2*pi</userinput>). You can even use functions you have defined to
set the extremes of the axis range. For example, if you have defined a function
<userinput>f(x) = x^2</userinput>, you could set <guilabel>Min:</guilabel> to
<userinput>f(3)</userinput>, which would make the lower end of the range equal
to 9.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Y-axis Range</guilabel></term>
<listitem>
<para>Sets the range for the y-axis. See <quote>X-axis Range</quote> above.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>X-axis Grid Spacing</guilabel></term>
<listitem>
<para>This controls the spacing between grid lines in the horizontal direction.
If <guilabel>Automatic</guilabel> is selected, then &kmplot; will try to find a grid line spacing of about two centimeters that is also numerically nice.
If <guilabel>Custom</guilabel> is selected, then you can enter the horizontal grid spacing. This value will be used regardless of the zoom. For example, if a value of 0.5 is entered, and the x range is 0 to 8, then 16 grid lines will be shown.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Y-axis Grid Spacing</guilabel></term>
<listitem>
<para>This controls the spacing between grid lines in the vertical direction.
See <quote>X-axis Grid Spacing</quote> above.
</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect2>
</sect1>
<sect1 id="constants-config">
<title><guimenuitem>Constants</guimenuitem> Configuration</title>
<para>To open this dialog select <menuchoice><guimenu>Edit</guimenu><guimenuitem>Constants..</guimenuitem></menuchoice> from the menubar.</para>
<screenshot>
<screeninfo>Screenshot of the Constants dialog</screeninfo>
<mediaobject>
<imageobject>
<imagedata fileref="settings-constants.png" format="PNG"/>
</imageobject>
<textobject>
<phrase>Screenshot of the Constants dialog</phrase>
</textobject>
</mediaobject>
</screenshot>
<para>
Constants can be used as part of an expression anywhere inside of &kmplot;. Each constant must have a name and a value. Some names are invalid, however, such as existing function names or existing constants.
</para>
<para>
There are two options that control the scope of a constant:
<variablelist>
<varlistentry>
<term><guilabel>Document</guilabel></term>
<listitem>
<para>If you select the <guilabel>Document</guilabel> checkbox, then the Constant will be saved along with the current diagram when you save it to file. However, unless you have also selected the <guilabel>Global</guilabel> option, the constant will not be available between instances of &kmplot;.</para>
</listitem>
</varlistentry>
<varlistentry>
<term><guilabel>Global</guilabel></term>
<listitem>
<para>If you select the <guilabel>Global</guilabel> checkbox, then the Constant's name and value will be written to &kde; settings (where it can
also be used by &kcalc;). The constant will not be lost when &kmplot; is closed, and will be available again for use when &kmplot; is started again.</para>
</listitem>
</varlistentry>
</variablelist>
</para>
</sect1>
</chapter>
<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
sgml-parent-document:("index.docbook" "BOOK" "CHAPTER")
End:
-->
distrib
>
Fedora
>
17
>
i386
>
media
>
updates
>
by-pkgid
>
6778515ef63448f70de1a7529c03dd5e
>
files
>
29
