<chapter id="using-kmplot">
<title>Using &kmplot;</title>

<para>&kmplot; deals with several different types of functions, which can be written in function form or as an equation:</para>

<itemizedlist>
	<listitem><para>Cartesian plots can either be written as &eg; <quote>y = x^2</quote>, where x has to be used as the variable; or as &eg; <quote>f(a) = a^2</quote>, where the name of the variable is arbitrary.</para></listitem>
	<listitem><para>Parametric plots are similar to Cartesian plots. The x and y coordinates can be entered as equations in t, &eg; <quote>x = sin(t)</quote>, <quote>y = cos(t)</quote>, or as functions, &eg; <quote>f_x(s) = sin(s)</quote>, <quote>f_y(s) = cos(s)</quote>.</para></listitem>
	<listitem><para>Polar plots are also similar to Cartesian plots. They can be either be entered as an equation in &thgr;, &eg; <quote>r = &thgr;</quote>, or as a function, &eg; 
<quote>f(x) = x</quote>.</para></listitem>
	<listitem><para>For implicit plots, the name of the function is entered separately from the expression relating the x and y coordinates. If the x and y variables are specified via the function name (by entering &eg;<quote>f(a,b)</quote> as the function name), then these variables will be used. Otherwise, the letters x and y will be used for the variables.</para></listitem>
	<listitem><para>Explicit differential plots are differential equations whereby the highest derivative is given in terms of the lower derivatives. Differentiation is denoted by a prime ('). In function form, the equation will look like <quote>f''(x) = f' &minus; f</quote>. In equation form, it will look like <quote>y'' = y' &minus; y</quote>. Note that in both cases, the <quote>(x)</quote> part is not added to the lower order differential terms (so you would enter <quote>f'(x) = &minus;f</quote> and not <quote>f'(x) = &minus;f(x)</quote>).</para></listitem>
</itemizedlist>

<para>All the equation entry boxes come with a button on the right. Clicking this invokes the advanced <guilabel>Equation Editor</guilabel> dialog, which provides:
	
	<itemizedlist>
		<listitem>
			<para>A variety of mathematical symbols that can be used in equations, but aren't found on normal keyboards.</para>
		</listitem>
		<listitem>
			<para>The list of user constants and a button for editing them.</para>
		</listitem>
		<listitem>
			<para>The list of predefined functions. Note that if you have text already selected, it will be used as the function argument when a function is inserted. For example, if <quote>1 + x</quote> is selected in the equation <quote>y = 1 + x</quote>, and the sine function is chosen, then the equation will become <quote> y = sin(1+x)</quote>.
			</para>
		</listitem>
	</itemizedlist>
</para>

<screenshot>
	<screeninfo>Here is a screenshot of the &kmplot; welcome window</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="main.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Screenshot</phrase>
		</textobject>
	</mediaobject>
</screenshot>

<sect1 id="function-types">
	<title>Function Types</title>
	
	<sect2 id="cartesian-functions">
		<title>Cartesian Functions</title>
		<para>To enter an explicit function (&ie;, a function in the form y=f(x)) into &kmplot;, just enter it in the
			following form:
			<screen><userinput><replaceable>f</replaceable>(<replaceable>x</replaceable>) = <replaceable>expression</replaceable></userinput></screen>
			where:
			<itemizedlist>
				<listitem><para>
						<replaceable>f</replaceable> is the name of the function, and can be any
						string of letters and numbers.</para>
				</listitem>
				
				<listitem><para>
						<replaceable>x</replaceable> is the x-coordinate, to be used in the expression
						following the equals sign. It is a dummy variable, so you can use any
						variable name you like to achieve the same effect.</para>
				</listitem>
				
				<listitem>
					<para><replaceable>expression</replaceable> is the expression to be plotted,
						given in the appropriate syntax for &kmplot;. See <xref linkend="math-syntax"/>.
					</para>
				</listitem>
				
			</itemizedlist>
		</para>
	</sect2>
	
	<sect2 id="parametric-functions">
		<title>Parametric Functions</title>
		<para>Parametric functions are those in which the x and y coordinates are
			defined by separate functions of another variable, often called t. To enter a
			parametric function in &kmplot;, follow the procedure as for a Cartesian
			function for each of the x and y functions. As with Cartesian functions, you may use any variable name you wish for the
			parameter.</para>
		<para>As an example, suppose you want to draw a circle, which has parametric
			equations x = sin(t), y = cos(t). After creating a parametric plot, enter the appropriate equations in the x and y boxes, &ie;,
			<userinput>f_x(t)=sin(t)</userinput> and
			<userinput>f_y(t)=cos(t)</userinput>.
		</para>
		<para>You can set some further options for the plot in the function editor:
			<variablelist>
				<varlistentry>
					<term><guilabel>Min</guilabel></term>
					<term><guilabel>Max</guilabel></term>
					<listitem>
						<para>These options control the range of the parameter t for which the function is plotted.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</para>
	</sect2>
	
	<sect2 id="polar-functions">
		<title>Functions in Polar Coordinates</title>
		
		<para>Polar coordinates represent a point by its distance from the origin
			(usually called r), and the angle a line from the origin to the point makes
			with the x-axis (usually represented by &thgr; the Greek letter theta). To enter
			functions in polar coordinates, click the <guilabel>Create</guilabel> button and select <guilabel>Polar Plot</guilabel> from the list.
			In the definition box, complete the
			function definition, including the name of the theta variable you want
			to use, &eg;, to draw the Archimedes' spiral r = &thgr;, enter:
			<screen><userinput>r(&thgr;) = &thgr;</userinput></screen>
			Note that you can use any name for the theta variable, so
			<quote>r(t) = t</quote> or <quote>f(x) = x</quote> will produce exactly the same output.
		</para>
	</sect2>
	
	<sect2 id="implicit-functions">
		<title>Implicit Functions</title>
		
		<para>An implicit expression relates the x and y coordinates as an equality. To create a circle, for example, 
		click the <guilabel>Create</guilabel> button and select <guilabel>Implicit Plot</guilabel> from the list. 
		Then, enter into the equation box (below the function name box) the following:
			<screen><userinput>x^2 + y^2 = 25</userinput></screen>
		</para>
	</sect2>
	
	<sect2 id="differential-functions">
		<title>Differential Functions</title>
		
		<para>&kmplot; can plot explicit differential equations. These are equations of the form
			y<superscript>(n)</superscript> = F(x,y',y'',...,y<superscript>(n&minus;1)</superscript>), where y<superscript>k</superscript> is the k<superscript>th</superscript> derivative of y(x). &kmplot; can only interpret the derivative order as the number of primes following the function name.
		
			To draw a sinusoidal curve, for example, you would use the differential equation
			<userinput>y'' = &minus; y</userinput> or <userinput>f''(x) = −f</userinput>.
		</para>
		
		<para>However, a differential equation on its own isn't enough to determine a plot. Each curve in the diagram is generated by a combination of the differential equation and the initial conditions. You can edit the initial conditions by clicking on the <guilabel>Initial Conditions</guilabel> tab when a differential equation is selected. The number of columns provided for editing the initial conditions is dependent on the order of the differential equation.
		</para>
		
		<para>You can set some further options for the plot in the function editor:
			<variablelist>
				<varlistentry>
					<term><guilabel>Step</guilabel></term>
					<listitem>
						<para>The step value in the precision box is used in numerically solving the differential equation (using the Runge Kutta method). Its value is the maximum step size used; a smaller step size may be used if part of the differential plot is zoomed in close enough.</para>
					</listitem>
				</varlistentry>
			</variablelist>
		</para>
		
	</sect2>
</sect1>

<sect1 id="combining-functions">
	<title>Combining Functions</title>
	<para>Functions can be combined to produce new ones. Simply enter the functions
		after the equals sign in an expression as if the functions were variables. For
		example, if you have defined functions f(x) and g(x), you can plot the sum of f
		and g with:
		<screen><userinput>sum(x) = f(x) + g(x)</userinput></screen>
	</para>
</sect1>

<sect1 id="function-appearance">
	<title>Changing the appearance of functions</title>
	
	<para>To change the appearance of a function's graph on the main plot
		window, select the function in the <guilabel>Functions</guilabel> sidebar.
		You can change the plot's line width, color and many other aspects by clicking on the 
		<guibutton>Color</guibutton> or <guibutton>Advanced...</guibutton>
		 button at the bottom of the section <guilabel>Appearance</guilabel>.
	</para>
	
	<para>
		If you are editing a Cartesian function, the function editor will have three tabs.
		In the first one you specify the equation of the function.
		The <guilabel>Derivatives</guilabel> tab lets you draw the first and second derivative to the function.
		With the <guilabel>Integral</guilabel> tab you can draw the integral of the function.
	</para>
</sect1>

<sect1 id="popupmenu">
	<title>Popup menu</title>
	<screenshot>
	<screeninfo>Graph right-click popup menu</screeninfo>
	<mediaobject>
		<imageobject>
			<imagedata fileref="popup.png" format="PNG"/>
		</imageobject>
		<textobject>
			<phrase>Graph right-click popup menu</phrase>
		</textobject>
	</mediaobject>
	</screenshot>

	<para>When right-clicking on a plot function or a single-point parametric plot function a popup menu will appear.
		In the menu there are three items available:</para>
	
	<variablelist>
		<varlistentry>
			<term><menuchoice><guimenuitem>Edit</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>Selects the function in the <guilabel>Functions</guilabel> sidebar for editing.</para>
			</listitem>
		</varlistentry>

		<varlistentry>
			<term><menuchoice><guimenuitem>Hide</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>Hides the selected graph. Other plots of the graph's function will still be shown.</para>
			</listitem>
		</varlistentry>
		
		<varlistentry>
			<term><menuchoice><guimenuitem>Remove</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>Removes the function. All its graphs will disappear.</para>
			</listitem>
		</varlistentry>
		<varlistentry>
			<term><menuchoice><guimenuitem>Animate Plot...</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>Displays the <guilabel>Parameter Animator</guilabel> dialog.</para>
			</listitem>
		</varlistentry>
		<varlistentry>
			<term><menuchoice><guimenuitem>Calculator</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>Opens the <guilabel>Calculator</guilabel> dialog.</para>
			</listitem>
		</varlistentry>
	</variablelist>
	
	<para>Depending on the plot type, there will also be up to four tools available:</para>
	
	<variablelist>
		<varlistentry>
			<term><menuchoice><guimenuitem>Plot Area...</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>Select the minimum and maximum x-values for the graph in the new dialog that appears.
					Calculates the integral and draws the area between the graph and the x-axis in the 
					selected range in the color of the graph.
				</para>
			</listitem>
		</varlistentry>
		
		<varlistentry>
			<term><menuchoice><guimenuitem>Find Minimum...</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>
					Find the minimum value of the graph in a specified range. The
					selected graph will be highlighted in the dialog that appears. Enter
					the lower and upper boundaries of the region in which you want to
					search for a minimum.
				</para>
				<para>
					Note: You can also tell the plot to visually show the extreme points in the <guilabel>Plot Appearance</guilabel> dialog, accessible in the <guilabel>Functions</guilabel> sidebar by clicking on <guibutton>Advanced...</guibutton>.
				</para>
			</listitem>
		</varlistentry>
		
		<varlistentry>
			<term><menuchoice><guimenuitem>Find Maximum...</guimenuitem>
				</menuchoice></term>
			<listitem>
				<para>This is the same as <guimenuitem>Find Minimum...</guimenuitem> above, but finds the maximum value instead of the minimum value.</para>
			</listitem>
		</varlistentry>
		
	</variablelist>
</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:
-->