doc/kmplot/reference.docbook

   1 <chapter id="reference">
   2 <title>&kmplot; Reference</title>
   3
   4 <!--
   5 <mediaobject>
   6 <imageobject>
   7 <imagedata fileref="kfkt.png" format="PNG"/>
   8 </imageobject>
   9 </mediaobject>
  10
  11 <para>This menu entry or toolbar button opens the Functions Editor.  Here
  12 you can enter up to 10 functions or
  13 function groups.  The parser knows <firstterm>explicit</firstterm> and
  14 <firstterm>parametric</firstterm> form.  With specific extensions it
  15 is possible to add first and second derivatives and to choose values
  16 for the function group parameter.</para>
  17 -->
  18
  19 <sect1 id="func-syntax">
  20 <title>Function Syntax</title>
  21
  22 <para>Some syntax rules must be complied with:</para>
  23
  24 <screen>
  25 <userinput>name(var1[, var2])=term [;extensions]</userinput>
  26 </screen>
  27
  28
  29 <variablelist>
  30 <varlistentry>
  31 <term>name</term>
  32 <listitem>
  33
  34 <para>The function name.  If the first character is <quote>r</quote>
  35 the parser assumes that you are using polar coordinates.  If the first
  36 character is <quote>x</quote> (for instance <quote>xfunc</quote>) the
  37 parser expects a second function with a leading <quote>y</quote> (here
  38 <quote>yfunc</quote>) to define the function in parametric form.
  39 </para>
  40 </listitem>
  41 </varlistentry>
  42 <varlistentry>
  43 <term>var1</term>
  44 <listitem><para>The function's variable</para></listitem>
  45 </varlistentry>
  46 <varlistentry>
  47 <term>var2</term>
  48 <listitem><para> The function <quote>group parameter</quote>. It must be
  49 separated from the function's variable by a comma. You can use the group
  50 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>
  51 </varlistentry>
  52 <varlistentry>
  53 <term>term</term>
  54 <listitem><para>The expression defining the function.</para></listitem>
  55 </varlistentry>
  56 </variablelist>
  57 </sect1>
  58
  59 <sect1 id="func-predefined">
  60 <title>Predefined Function Names and Constants</title>
  61
  62 <para>
  63 All the predefined functions and constants that &kmplot; knows can be shown by
  64 selecting <menuchoice><guimenu>Help</guimenu><guimenuitem>Names</guimenuitem>
  65 </menuchoice>. They are:
  66
  67 <variablelist>
  68
  69 <varlistentry>
  70 <term>sqr, sqrt</term>
  71 <listitem>
  72 <para>Return the square and square root of a number, respectively.</para>
  73 </listitem>
  74 </varlistentry>
  75
  76 <varlistentry>
  77 <term>exp, ln</term>
  78 <listitem>
  79 <para>Return the exponential and natural logarithm of a number, respectively.</para>
  80 </listitem>
  81 </varlistentry>
  82
  83 <varlistentry>
  84 <term>log</term>
  85 <listitem>
  86 <para>Returns the logarithm to base 10 of a number.</para>
  87 </listitem>
  88 </varlistentry>
  89
  90 <varlistentry>
  91 <term>sin, arcsin</term>
  92 <listitem>
  93 <para>Return the sine and inverse sine of a number, respectively. Note that the
  94 argument to sin and the return value of arcsin are in radians.</para>
  95 </listitem>
  96 </varlistentry>
  97
  98 <varlistentry>
  99 <term>cos, arccos</term>
 100 <listitem>
 101 <para>Return the cosine and inverse cosine of a number, respectively. Also in radians.</para>
 102 </listitem>
 103 </varlistentry>
 104
 105 <varlistentry>
 106 <term>tan, arctan</term>
 107 <listitem>
 108 <para>Return the tangent and inverse tangent of a number,
 109 respectively. Also in radians.</para>
 110 </listitem>
 111 </varlistentry>
 112
 113 <varlistentry>
 114 <term>sinh, arcsinh</term>
 115 <listitem>
 116 <para>Return the hyperbolic sine and inverse hyperbolic sine of a number,
 117 respectively.</para>
 118 </listitem>
 119 </varlistentry>
 120
 121 <varlistentry>
 122 <term>cosh, arccosh</term>
 123 <listitem>
 124 <para>Return the hyperbolic cosine and inverse hyperbolic cosine of a number, respectively.</para>
 125 </listitem>
 126 </varlistentry>
 127
 128 <varlistentry>
 129 <term>tanh, arctanh</term>
 130 <listitem>
 131 <para>Return the hyperbolic tangent and inverse hyperbolic tangent of a number,
 132 respectively.</para>
 133 </listitem>
 134 </varlistentry>
 135
 136 <varlistentry>
 137 <term>sin, arcsin</term>
 138 <listitem>
 139 <para>Return the sine and inverse sine of a number, respectively. Note that the
 140 argument to sin and the return value of arcsin are in radians.</para>
 141 </listitem>
 142 </varlistentry>
 143
 144 <varlistentry>
 145 <term>cos, arccos</term>
 146 <listitem>
 147 <para>Return the cosine and inverse cosine of a number, respectively. Also in radians.</para>
 148 </listitem>
 149 </varlistentry>
 150
 151 <varlistentry>
 152 <term>pi, e</term>
 153 <listitem>
 154 <para>Constants representing &pgr; (3.14159...) and e (2.71828...), respectively.</para>
 155 </listitem>
 156 </varlistentry>
 157
 158 </variablelist>
 159 </para>
 160
 161 <para>
 162 These functions and constants and even all user defined functions can
 163 be used to determine the axes settings as well. See <xref linkend="axes-config"/>.
 164 </para>
 165
 166 </sect1>
 167
 168 <sect1 id="func-extension">
 169   <title>Extensions</title>
 170   <para>An extension for a function is specified by entering a semicolon,
 171     followed by the extension, after the function definition. The extension can either be written in the Quick Edit box or by using the DCOP 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:
 172     <screen>
 173       <userinput>
 174         f(x)=x^2; A1
 175       </userinput>
 176     </screen>
 177     will show the graph y=x<superscript>2</superscript> with its first
 178     derivative. Supported extensions are described below:
 179     <variablelist>
 180       <varlistentry>
 181         <term>N</term>
 182         <listitem>
 183           <para>
 184             The function will be stored but not be drawn.
 185             It can be used like any other user-defined or predefined function.
 186           </para>
 187         </listitem>
 188       </varlistentry>
 189       <varlistentry>
 190         <term>A1</term>
 191         <listitem>
 192           <para>
 193             The graph of the derivative of the function will be drawn
 194             additionally with the same color but less line width.
 195           </para>
 196         </listitem>
 197       </varlistentry>
 198       <varlistentry>
 199         <term>A2</term>
 200         <listitem>
 201           <para>
 202             The graph of the second derivative of the function will be
 203             drawn additionally with the same color but less line width.
 204           </para>
 205         </listitem>
 206       </varlistentry>
 207       <varlistentry>
 208         <term>D[a,b]</term>
 209         <listitem>
 210           <para>
 211             Sets the domain for which the function will be displayed.
 212           </para>
 213         </listitem>
 214       </varlistentry>
 215       <varlistentry>
 216         <term>P[a{,b...}]</term>
 217         <listitem>
 218           <para>
 219             Give a set of values of a group parameter for which the function should be
 220             displayed. For example: <userinput>f(x,k)=k*x;P[1,2,3]</userinput> will plot
 221             the functions f(x)=x, f(x)=2*x and f(x)=3*x. You can also use functions as the
 222             arguments to the P option.
 223           </para>
 224         </listitem>
 225       </varlistentry>
 226     </variablelist>
 227   </para>
 228   <para>
 229     Please note that you can do all of these operations by using the function editor dialog too.
 230 </para>
 231 </sect1>
 232
 233 <sect1 id="math-syntax">
 234 <title>Mathematical Syntax</title>
 235 <para>&kmplot; uses a common way of expressing mathematical functions, so you
 236 should have no trouble working it out. The operators &kmplot; understands are,
 237 in order of decreasing precedence:
 238 <variablelist>
 239
 240 <varlistentry>
 241 <term>^</term>
 242 <listitem><para>The caret symbol performs exponentiation. &eg;,
 243 <userinput>2^4</userinput> returns 16.</para>
 244 </listitem>
 245 </varlistentry>
 246
 247 <varlistentry>
 248 <term>*, /</term>
 249 <listitem>
 250 <para>The asterisk and slash symbols perform multiplication and
 251 division . &eg;,
 252 <userinput>3*4/2</userinput> returns 6.</para>
 253 </listitem>
 254 </varlistentry>
 255
 256 <varlistentry>
 257 <term>+, -</term>
 258 <listitem><para>The plus and minus symbols perform addition and
 259 subtraction. &eg;, <userinput>1+3-2</userinput> returns 2.</para>
 260 </listitem>
 261 </varlistentry>
 262
 263 </variablelist>
 264 </para>
 265 <para>
 266 Note the precedence, which means that if parentheses are not used,
 267 exponentiation is performed before multiplication/division, which is performed
 268 before addition/subtraction. So <userinput>1+2*4^2</userinput> returns 33, and
 269 not, say 144. To override this, use parentheses. To use the above example,
 270 <userinput>((1+2)*4)^2</userinput> <emphasis>will</emphasis> return 144.
 271 </para>
 272 </sect1>
 273
 274 <!--
 275 <sect1 id="coord-system">
 276 <title>Coordinate Systems</title>
 277
 278 <para><inlinemediaobject>
 279 <imageobject>
 280 <imagedata fileref="ksys1.png" format="PNG"/>
 281 </imageobject>
 282 </inlinemediaobject></para>
 283
 284 <para>
 285 <inlinemediaobject>
 286 <imageobject>
 287 <imagedata fileref="ksys2.png" format="PNG"/>
 288 </imageobject>
 289 </inlinemediaobject></para>
 290
 291 <para>
 292 <inlinemediaobject>
 293 <imageobject>
 294 <imagedata fileref="ksys3.png" format="PNG"/>
 295 </imageobject>
 296 </inlinemediaobject></para>
 297 -->
 298 <sect1 id="coord-area"><title>Plotting Area</title>
 299 <para>
 300 By default, explicitly given functions are plotted for the whole of the visible part of the
 301 x-axis. You can specify an other range in the edit-dialog for the function. For every pixel on the x-axis &kmplot; calculates a function value.
 302 If the plotting area contains the resulting point it is connected to the last
 303 drawn point by a line.
 304 </para>
 305 <para>
 306 Parametric functions are plotted for parameter values from 0 up to 2&pgr;.
 307 You can set the plotting range in the dialog for the function too.
 308 </para>
 309 </sect1>
 310
 311 <sect1 id="coord-cross">
 312 <title>Cross Hair Cursor</title>
 313 <para>
 314 While the mouse cursor is over the plotting area the cursor changes to a cross hair. 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.
 315 </para>
 316 <para>
 317 You can trace a function's values more precisely by clicking onto or next to a graph. The selected function is shown in the statusbar in the right column. The cross hair 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 cross hair will have the inverted color of the background. When moving the mouse or pressing the keys Left or Right the cross hair will follow the function and you see the current x- and y-value. If the cross hair 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.
 318 </para>
 319 <para>
 320 Note that tracing is only possible with explicitly given functions.
 321 The coordinates are always displayed according to a Cartesian system of
 322 coordinates. Neither non-single-point parametric functions nor functions given in polar
 323 coordinates can be traced in this way.
 324 </para>
 325
 326 </sect1>
 327
 328 </chapter>
 329
 330 <!--
 331 Local Variables:
 332 mode: sgml
 333 sgml-minimize-attributes:nil
 334 sgml-general-insert-case:lower
 335 sgml-indent-step:0
 336 sgml-indent-data:nil
 337 sgml-parent-document:("index.docbook" "BOOK" "CHAPTER")
 338 End:
 339 -->