summaryrefslogtreecommitdiffstats
path: root/doc/kmplot/reference.docbook
blob: ca2aa0d290785cdf0c37b4836b0d13793c8b672b (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
<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>. They are:

<variablelist>

<varlistentry>
<term>sqr, sqrt</term>
<listitem>
<para>Return the square and square root of a number, respectively.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>exp, ln</term>
<listitem>
<para>Return the exponential and natural logarithm of a number, respectively.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>log</term>
<listitem>
<para>Returns the logarithm to base 10 of a number.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>sin, arcsin</term>
<listitem>
<para>Return the sine and inverse sine of a number, respectively. Note that the
argument to sin and the return value of arcsin are in radians.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>cos, arccos</term>
<listitem>
<para>Return the cosine and inverse cosine of a number, respectively. Also in radians.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tan, arctan</term>
<listitem>
<para>Return the tangent and inverse tangent of a number,
respectively. Also in radians.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>sinh, arcsinh</term>
<listitem>
<para>Return the hyperbolic sine and inverse hyperbolic sine of a number,
respectively.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>cosh, arccosh</term>
<listitem>
<para>Return the hyperbolic cosine and inverse hyperbolic cosine of a number, respectively.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>tanh, arctanh</term>
<listitem>
<para>Return the hyperbolic tangent and inverse hyperbolic tangent of a number,
respectively.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>sin, arcsin</term>
<listitem>
<para>Return the sine and inverse sine of a number, respectively. Note that the
argument to sin and the return value of arcsin are in radians.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>cos, arccos</term>
<listitem>
<para>Return the cosine and inverse cosine of a number, respectively. Also in radians.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>pi, e</term>
<listitem>
<para>Constants representing &pgr; (3.14159...) and e (2.71828...), respectively.</para>
</listitem>
</varlistentry>

</variablelist>
</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>

</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 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:
    <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 using the function editor dialog 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. &eg;,
<userinput>2^4</userinput> returns 16.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>*, /</term>
<listitem>
<para>The asterisk and slash symbols perform multiplication and
division . &eg;,
<userinput>3*4/2</userinput> returns 6.</para>
</listitem>
</varlistentry>

<varlistentry>
<term>+, -</term>
<listitem><para>The plus and minus symbols perform addition and
subtraction. &eg;, <userinput>1+3-2</userinput> returns 2.</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. For every pixel on the x-axis &kmplot; calculates a function value.
If the plotting area contains the resulting point it is connected to the last
drawn point by a line.
</para>
<para>
Parametric functions are plotted for parameter values from 0 up to 2&pgr;. 
You can set the plotting range in the dialog for the function too.
</para>
</sect1>

<sect1 id="coord-cross">
<title>Cross Hair Cursor</title>
<para>
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.
</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 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.
</para>
<para>
Note that tracing is only possible with explicitly given functions.
The coordinates are always displayed according to a Cartesian system of
coordinates. Neither non-single-point parametric functions nor functions given in polar
coordinates can be traced in this way.
</para>

</sect1>

</chapter>