<?xml version="1.0" ?>
<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.5-Based Variant V1.1//EN" "dtd/kdedbx45.dtd" [
  <!ENTITY kappname "&kalgebra;">
  <!ENTITY commands SYSTEM "commands.docbook">

  <!ENTITY % addindex "IGNORE">
  <!ENTITY % English "INCLUDE">
]>

<book id="kalgebra" lang="&language;">

<bookinfo>
<title>The &kalgebra; Handbook</title>

<authorgroup>
<author>
<firstname>Aleix</firstname>
<surname>Pol</surname>
<affiliation>
<address>&Aleix.Pol.mail;</address>
</affiliation>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>

<copyright>
<year>2007</year>
<holder>&Aleix.Pol;</holder>
</copyright>

<legalnotice>&FDLNotice;</legalnotice>


<date>2016-04-19</date>
<releaseinfo>0.10 (Applications 16.04)</releaseinfo>

<abstract>
<para>
&kalgebra; is an application that can replace your graphing calculator.
It has numerical, logical, symbolic, and analysis features that let you calculate
mathematical expressions on the calculator and graphically plot the results
in 2D or 3D. &kalgebra; is rooted in the Mathematical Markup Language
(MathML); however, one does not need to know MathML to use &kalgebra;.
</para>
</abstract>

<keywordset>
<keyword>KDE</keyword>
<keyword>kdeedu</keyword>
<keyword>graph</keyword>
<keyword>mathematics</keyword>
<keyword>2D</keyword>
<keyword>3D</keyword>
<keyword>mathML</keyword>
</keywordset>

</bookinfo>

<chapter id="introduction">
<title>Introduction</title>

<para>
&kalgebra; has numerous features that allow the user to perform all sorts
of mathematical operations and show graphically. At one time, this
program was MathML oriented. Now it can be used by anyone with a little
mathematical knowledge to solve simple and advanced problems alike.
</para>
<!--FIXME Ask Burkhard where to put tutorials and if it is worth efforts to do. Example from UB page: http://swiftscythe.blogspot.de/2011/02/how-to-work-with-complex-numbers-in.html-->
<para>
It includes such features as:
</para>


<itemizedlist>
<listitem><para>
A calculator for quick and easy evaluation of math
functions.
</para></listitem>
<listitem><para>
Scripting capability for advanced series of calculations
</para></listitem>
<listitem><para>
Language capabilities including function definition and syntax autocompletion.
</para></listitem>
<listitem><para>
Calculus functions including symbolic differentiation, vector calculus,
and list manipulation.
</para></listitem>
<listitem><para>
Function plotting with live cursor for graphical root finding and other
types of analysis.
</para></listitem>
<listitem><para>
3D plotting for useful visualization of 3D functions.
</para></listitem>
<listitem><para>
A built-in operator dictionary for quick reference to the many available
functions.
</para></listitem>
</itemizedlist>

<para>
Below is a screenshot of the &kalgebra; application in action:
</para>

<screenshot>
<screeninfo>Here's a screenshot of &kalgebra; main window</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kalgebra-main-window.png" format="PNG"/>
	  </imageobject>
	    <textobject>
	    <phrase>&kalgebra; main window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>

<para>
When the user begins a &kalgebra; session, they are presented with a
single window consisting of a <guilabel>Calculator</guilabel> tab,
a <guilabel>2D Graph</guilabel> tab,
a <guilabel>3D Graph</guilabel> tab and a
<guilabel>Dictionary</guilabel> tab. Within each tab, you will find an
input field to enter your functions or calculations, and a display field
which shows the results.
</para>

<para>At any time the user may manage their session with the main menu
<guilabel>Session</guilabel> options:</para>

<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>N</keycap></keycombo></shortcut>
<guimenu>Session</guimenu><guimenuitem>New</guimenuitem>
</menuchoice></term>
<listitem><para>Opens a new &kalgebra; window.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;&Shift;
<keycap>F</keycap></keycombo></shortcut>
<guimenu>Session</guimenu><guimenuitem>Full Screen Mode</guimenuitem>
</menuchoice></term>
<listitem><para>Toogle full screen mode for &kalgebra; window. The full
screen mode can also be switched on and off using  <inlinemediaobject>
<imageobject> <imagedata fileref="view-fullscreen.png" format="PNG"/>
</imageobject> </inlinemediaobject> button at the top right part of
&kalgebra; window.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>Q</keycap></keycombo></shortcut>
<guimenu>Session</guimenu><guimenuitem>Quit</guimenuitem>
</menuchoice></term>
<listitem><para>Shuts the program down.</para></listitem>
</varlistentry>

</variablelist>

</chapter>

<chapter id="syntax">
<title>Syntax</title>
<para>
&kalgebra; uses an intuitive algebraic syntax for entering user functions,
similar to that used on most modern graphing calculators. This section
lists the fundamental built-in operators available in &kalgebra;. The
author of &kalgebra; modeled this syntax after
<ulink url="http://maxima.sourceforge.net/">Maxima</ulink> and
  <ulink url="http://www.maplesoft.com/products/maple/">maple</ulink> for users
that may be familiar with these programs.
</para>

<para>
For users that are interested in the inner workings of &kalgebra;, user
entered expressions are converted to MathML on the backend. A rudimentary
understanding of the capabilities supported by MathML will go a long way
toward revealing the inner capabilities of &kalgebra;.
</para>

<para>Here is a list of the available operators we have by now:</para>
<itemizedlist>
<listitem><para>+ - * / : Addition, subtraction, multiplication and
division.</para> </listitem>
<listitem><para>^, **: Power, you can use them both. Also it is possible to use
the unicode ² characters. Powers are one way to make roots too, you can do it
like: a**(1/b)</para></listitem>
<listitem><para>-&gt; : lambda. It is the way to specify one or more free
variables that will be  bound in a function. For example, in the expression,
<userinput>length:=(x,y)->(x*x+y*y)^0.5</userinput>, the lambda operator is used to denote
that x and y will be bound when the length function is used.
</para></listitem>
<listitem><para>x=a..b : This is used when we need to delimit a range
(bounded variable+uplimit+downlimit). This means that x goes from a to b.</para></listitem>
<listitem><para>() : It is used to specify a higher priority.</para></listitem>
<listitem><para>abc(params) : Functions. When the parser finds a function, it checks
if abc is an operator. If it is, it will be treated as an operator, if it is
not, it will be treated as a user function.</para></listitem>
<listitem><para>:= : Definition. It is used to define a variable value. You can
do things like x:=3, x:=y being y defined or not or perimeter:=r->2*pi*r.
</para></listitem>
<listitem><para>? : Piecewise condition definition. Piecewise is the way we can define
conditional operations in &kalgebra;. Put another way, this is a way of
specifying an if, elseif, else condition. If we introduce the condition before the '?' it will
use this condition only if it is true, if it finds a '?' without any condition, it will
enter in the last instance.
Example: piecewise { x=0 ? 0, x=1 ? x+1, ? x**2 }
</para></listitem>
<listitem><para>{ } : MathML container. It can be used to define a container. Mainly
useful for working with piecewise.
</para></listitem>
<listitem><para>= &gt; &gt;= &lt; &lt;= : Value comparators for equal,
greater, greater or equal, less and less or equal respectively</para></listitem>
</itemizedlist>

<para>Now you could ask me, why should the user mind about MathML? That’s easy.
With this, we can operate with functions like cos(), sin(), any other
trigonometrical functions, sum() or product(). It does not matter what kind it is.
We can use plus(), times() and everything which has its operator. Boolean
functions are implemented as well, so we can do something like or(1,0,0,0,0).</para>

</chapter>

<chapter id="using-calculator">
<title>Using the Calculator</title>
<para>&kalgebra;'s calculator is useful as a calculator on steroids. The
user may enter expressions for evaluation in <guimenu>Calculate</guimenu>
or <guimenu>Evaluate</guimenu> mode, depending on the <guimenu>Calculator</guimenu>
menu selection.
</para>
<para>
In evaluation mode &kalgebra; simplifies the expression even if it sees an undefined variable.
When in calculation mode &kalgebra;, calculates everything and if it finds an undefined
variable shows an error.
</para>
<para>
In addition to displaying the user entered equations and results in the
Calculator display, all variables that are declared are displayed in a
persistent frame to the right. By double clicking on a variable you will see a
dialog that lets you change their values (just a way to trick the log).
</para>

<para>
The "ans" variable is special, every time you enter an expression, the
"ans" variable value will be changed to the last result.
</para>

<para>The following are example functions that can be entered in
the input field of the calculator window:</para>
<itemizedlist>
<listitem><para>sin(pi)</para></listitem>
<listitem><para>k:=33</para></listitem>
<listitem><para>sum(k*x : x=0..10)</para></listitem>
<listitem><para>f:=p->p*k</para></listitem>
<listitem><para>f(pi)</para></listitem>
</itemizedlist>

<para>
The following shows a screenshot of the calculator window after entering
the above example expressions:
</para>
<screenshot>
<screeninfo>Screenshot of &kalgebra; calculator window with example expressions</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kalgebra-console-window.png" format="PNG"/>
	  </imageobject>
	    <textobject>
	    <phrase>&kalgebra; calculator window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>


<para>A user can control the execution of a series of calculations
using the <guimenu>Calculator</guimenu> menu options:</para>

<variablelist>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>L</keycap></keycombo></shortcut>
<guimenu>Calculator</guimenu><guimenuitem>Load Script</guimenuitem>
</menuchoice></term>
<listitem><para>Executes the instructions in a file sequentially.
Useful if you want to define some libraries or resume some previous work.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>G</keycap></keycombo></shortcut>
<guimenu>Calculator</guimenu><guimenuitem>Save Script</guimenuitem>
</menuchoice></term>
<listitem><para>Saves the instructions you have typed since the session began to be able to reuse. Generates text files so it should be easy to fix
using any text editor, like Kate.</para></listitem>
</varlistentry>

<varlistentry>
<term><menuchoice>
<shortcut><keycombo action="simul">&Ctrl;
<keycap>S</keycap></keycombo></shortcut>
<guimenu>Calculator</guimenu><guimenuitem>Export Log</guimenuitem>
</menuchoice></term>
<listitem><para>Saves the log with all results into an &HTML; file to be able to print or publish.</para></listitem>
</varlistentry>

</variablelist>

</chapter>

<chapter id="two-D-graphs">
<title>2D Graphs</title>
<para>To add a new 2D graph on &kalgebra;, select the <guilabel>2D
Graph</guilabel> tab and click the <guilabel>Add</guilabel> tab to add
a new function. Your focus will go to an input text box where you can
type your function.</para>

<sect1 id="two-D-syntax">
<title>Syntax</title>
<para>If you want to use a typical f(x) function it is not necessary to specify
it, but if you want a f(y) or a polar function, you will have to add y-&gt; and q-&gt;
as the bounded variables.</para>

<para>Examples:</para>
<itemizedlist>
<listitem><para>sin(x)</para></listitem>
<listitem><para>x²</para></listitem>
<listitem><para>y->sin(y)</para></listitem>
<listitem><para>q->3*sin(7*q)</para></listitem>
<listitem><para>t->vector{sin t, t**2}</para></listitem>
</itemizedlist>
<para>If you have entered the function click on the <guibutton>OK</guibutton> button to display the graph in the main window.</para>

</sect1>

<sect1 id="two-D-features">
<title>Features</title>
<para>You can set several graphs on the same view. Just use the <guilabel>Add</guilabel> button when
you are in List mode. You can set each graph its own color.</para>

<para>The view can be zoomed and moved with the mouse. Using the wheel
you can zoom in and out. You can also select an area with the left button
of the mouse and this area will be zoomed in. Move the view with the arrow keys.</para>

<note>
 <para>The viewport of 2D graphs can be explicitly defined using the <guilabel>Viewport</guilabel> tab on a <guilabel>2D Graph</guilabel> tab.</para>
</note>
 
<para>In the <guilabel>List</guilabel> tab, you can open an <guilabel>Editing</guilabel> tab to edit or remove a function with double-click and check or uncheck the check box next to the function name to show or hide it.</para>
<para>In the <guimenu>2D Graph</guimenu> menu you find these options:</para>
<itemizedlist>
<listitem><para>Show or hide the grid</para></listitem>
<listitem><para>Keep the aspect ratio while zooming</para></listitem>
<listitem><para>Zoom in (<keycombo action="simul">&Ctrl;
<keycap>+</keycap></keycombo>) and zoom out (<keycombo action="simul">&Ctrl;
<keycap>-</keycap></keycombo>)</para></listitem>
<listitem><para>Save (<keycombo action="simul">&Ctrl;
<keycap>S</keycap></keycombo>) the graph as image file</para></listitem>
<listitem><para>Reset the view to the original zoom</para></listitem>
<listitem><para>Select a resolution for the graphs</para></listitem>
</itemizedlist>

<para>
   Below is a screenshot of a user who's cursor is at the rightmost root
   of the function, sin(1/x). The user who graphed it used very fine
   resolution to make this graph (as it oscillates at higher and higher
   frequency near the origin). There is also a live cursor feature
   where whenever you move your cursor over a spot, it shows you the x
   and y values in the bottom left corner of the screen. A live "tangent
   line" is plotted on the function at the live cursor location.
 </para>

<screenshot>
<screeninfo>Here's a screenshot of &kalgebra; 2D graph window</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kalgebra-2dgraph-window.png" format="PNG"/>
	  </imageobject>
	    <textobject>
	    <phrase>&kalgebra; 2D graph window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>


</sect1>

</chapter>

<chapter id="three-D-graphs">
<title>3D Graphs</title>

<para>To draw a 3D Graph with &kalgebra; select the <guilabel>3D Graph</guilabel> tab
and you will see an input field at the bottom where you will type your function.
Z cannot be defined yet. For the moment &kalgebra; only supports
3D graphs explicitly dependent only on the x and y, such as (x,y)->x*y,
where z=x*y.
</para>

<para>Examples:</para>
<itemizedlist>
<listitem><para>(x,y)->sin(x)*sin(y)</para></listitem>
<listitem><para>(x,y)->x/y</para></listitem>
</itemizedlist>

<para>The view can be zoomed and moved with the mouse. Using the wheel
you can zoom in and out. Hold the &LMB; and move the mouse to rotate the graph.</para>

 <para>The left and right arrow keys rotate the graph around the z axis, the up and down arrow keys rotate around the horizontal axis of the view. Press <keycap>W</keycap> to zoom in the plot and <keycap>S</keycap> to zoom it out.</para>

<para>In the <guimenu>3D Graph</guimenu> menu you find these options:</para>
<itemizedlist>
<!-- not in master for 4.11
<listitem><para>Enable or disable transparency in the 3D graph menu</para></listitem>
-->
<listitem><para>Save (<keycombo action="simul">&Ctrl;
<keycap>S</keycap></keycombo>) the graph as image file</para></listitem>
<listitem><para>Reset the view to the original zoom in the 3D graph menu</para></listitem>
<listitem><para>You can draw the graphs with dots, lines or solid styles in the 3D graph menu</para></listitem>
</itemizedlist>

<para>
Below is a screenshot of the so-called "sombrero" function. This particular
graph is shown using the 3D graph line-style.
</para>

<screenshot>
<screeninfo>Here's a screenshot of &kalgebra; 3D graph window</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kalgebra-3dgraph-window.png" format="PNG"/>
	  </imageobject>
	    <textobject>
	    <phrase>&kalgebra; 3D graph window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>

</chapter>

<chapter id="dictionary">
<title>Dictionary</title>

<para>
  The dictionary provides a list of all &kalgebra; built in functions. It can be
used to find the definition of an operation and its input parameters. It's a useful
place to go to find the many capabilities of &kalgebra;.
</para>

 <para>
   Below is a screenshot of the &kalgebra; dictionary lookup of the cosine function.
 </para>

<screenshot>
<screeninfo>Here's a screenshot of the &kalgebra; dictionary window</screeninfo>
	<mediaobject>
	  <imageobject>
	    <imagedata fileref="kalgebra-dictionary-window.png" format="PNG"/>
	  </imageobject>
	    <textobject>
	    <phrase>&kalgebra; dictionary window</phrase>
	  </textobject>
	</mediaobject>
</screenshot>


</chapter>

&commands;

<chapter id="credits">
<title>Credits and License</title>

<itemizedlist>
<listitem><para>Program copyright 2005-2009 &Aleix.Pol;</para>
</listitem>
</itemizedlist>

<para>
Documentation copyright 2007 &Aleix.Pol; &Aleix.Pol.mail;
</para>

<!-- TRANS:CREDIT_FOR_TRANSLATORS -->
&underFDL;               <!-- FDL: do not remove -->
&underGPL;        	 <!-- GPL License -->

</chapter>

&documentation.index;
</book>

<!--
Local Variables:
mode: sgml
sgml-minimize-attributes:nil
sgml-general-insert-case:lower
sgml-indent-step:0
sgml-indent-data:nil
End:
-->