~neon/analitza/master

/*
Main page of docs for analitza library.
Copyright (C) 2013 by Percy Camilo Triveño Aucahuasi <percy.camilo.ta@gmail.com>
Distributed under the LGPL.
*/

/** \mainpage Analitza - KDE Mathematical Library

<p><b>
Overview |
\ref getting_started "Getting Started" |
\ref tutorials "Tutorials" |
\ref examples_showcases "Examples and Showcases"
</b></p>

Analitza is a library that work with mathematical objects. Analitza add 
mathematical features to your program, such as symbolic 
computations and some numerical methods; for instance the library
can parse mathematical expressions and let you evaluate and draw them. 

Development of Analitza take place in 
<a href="https://commits.kde.org/analitza">this</a> 
repository.

\section modules Modules

The library consists of the following modules:

\li \ref AnalitzaModule "Analitza" is the core module, it is the parser of 
mathematical expressions.
\li \ref AnalitzaPlotModule "AnalitzaPlot" let you draw mathematical objects 
like functions, equations, etc.
\li \ref AnalitzaGUIModule "AnalitzaGUI" several UI components based on 
QWidget and QML.

\ref AnalitzaGUIModule "AnalitzaGUI" depends of 
\ref AnalitzaPlotModule "AnalitzaPlot" and \ref AnalitzaPlotModule "AnalitzaPlot" 
depends of \ref AnalitzaModule "Analitza".

\section design Design Aspects

\ref AnalitzaModule "Analitza" is based on a subset of 
<a href="http://www.w3.org/TR/MathML2/">Mathematical Markup Language (MathML) Version 2.0</a> 
so for instance the \ref AnalitzaModule "parser" maintains structures that are 
mapped with a MathML content tag and thus can generate a MathML presentation 
for the current expression. This means also that all modules of the library 
are based implicitly on MathML.

Some important classes from each module are:
\li \ref Analitza::Expression "Expression" abstracts a valid expression from 
user input (a 
<a href="http://qt-project.org/doc/qt-4.8/qstring.html">QString</a>) and then 
\ref Analitza::Analyzer "Analyzer" can evaluate the expression.
\li \ref Analitza::PlotsModel "PlotsModel" manage the mathematical objects that can be 
drawn by \ref Analitza::Plotter2D "Plotter2D" or 
\ref Analitza::Plotter3DES "Plotter3D" (both plotters are agnostic of technologies 
like QtWidgets or QtQuick).
\li \ref Analitza::ExpressionEdit "ExpressionEdit" is a widget that allows inline 
editing of mathematical expressions. \ref Analitza::PlotsView2D "PlotsView2D" is 
a widget that uses \ref Analitza::Plotter2D "Plotter2D" to show plots (same with 
\ref Analitza::PlotsView3D "PlotsView3D": it uses 
\ref Analitza::Plotter3DES "Plotter3D").

\section features Features

\li Parser can work with lambdas, matrices, vectors, polynomials, custom variables, etc.
\li Parser suport some symbolic computations like derivatives, solving equations, etc.
\li MathML built-in, so (for instance) is easy to export formulas to 
<a href="http://www.latex-project.org/">Latex</a>.
\li Extensible framework for plotting mathematical objects such implicit surfaces, 
parametrical curves, etc. in many coordinate systems.
\li GUI components for input and manage mathematical expressions.


@authors
Aleix Pol \<aleixpol@kde.org\>
Percy Camilo Triveño Aucahuasi \<percy.camilo.ta@gmail.com\>

@maintainers
Aleix Pol \<aleixpol@kde.org\>

@licenses
@lgpl

*/


/** \page getting_started Getting Started

<p><b>
\ref index "Overview" |
Getting Started |
\ref tutorials "Tutorials" |
\ref examples_showcases "Examples and Showcases"
</b></p>

\section intall_analitza Install Analitza

In Linux, if your distribution have already the package then installing is 
easy, for example in Debian type as root user:

\code
aptitude install libanalitza-dev
\endcode

In Windows the task is very simple thanks to 
<a href="http://techbase.kde.org/Projects/KDE_on_Windows/Installation">KDE Installer</a> 
you just need to follow the wizard and check to install the Analitza package. For 
more information about KDE on windows read 
<a href="http://techbase.kde.org/Projects/KDE_on_Windows">this</a>.

Just remeber that Analitza version depends of KDE version, and your 
distribution (in case of Linux) or KDE Installer (in case of windows) 
can have and old version of KDE.

\section build Build and Install Analitza

In case the repositories doesn't have the library package or you want the 
last version of Analitza, then you can build and then install the library from 
sources. 

First, check this prerequisites:

\li Make sure you have 
<a href="http://techbase.kde.org/Development/Git">Git</a> installed.
\li Make sure you have 
<a href="http://techbase.kde.org/Development/Tutorials/CMake">CMake</a> installed.
\li Analitza needs a successful installation of 
<a href="http://api.kde.org/4.x-api/kdelibs-apidocs/">KDELibs</a>, 
however since doesn't use the most heavy/exotics components from KDELibs, 
then you can build Analitza using an older version of KDELibs, you 
just need to install the kdelibs-dev package from your repository 
(from distibution in case of Linux , and from KDE Installer 
in case of windows) If you still want to build KDELibs then read 
<a href="http://techbase.kde.org/Getting_Started/Build">here</a> the details.
\li If you want to use 3D features of Analitza (like drawing implicit surfaces 
for instance), then you need to make sure that 
<a href="http://www.opengl.org/">OpenGL</a> 
development libraries are correctly installed in your system.
\li If you want to build a command line calculator called calgebra, then you need the 
<a href="http://cnswww.cns.cwru.edu/php/chet/readline/rltop.html">readline</a> 
development libraries.

Next, let's follow these steps in your terminal:

\li \code git clone git://anongit.kde.org/analitza\endcode
\li For Linux type: \code cd analitza && mkdir build && cd build\endcode For 
Windows create a folder called build inside analitza and then you need to 
go there (inside build folder).
\li \code cmake .. -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix` -DCMAKE_BUILD_TYPE=debugfull\endcode
\li \code make install\endcode

For more information about building KDE Software you can read 
<a href="http://techbase.kde.org/Getting_Started/Build/KDE_Applications">here</a> 
and 
<a href="http://techbase.kde.org/Getting_Started">here</a>.

\section setup_cmake Setup a CMake Project

Once the Analitza is installed, then you have headers and sublibraries binaries 
for each \ref modules. The installation process ensures that cmake will find 
the library by using find_package macro, this because an AnalitzaConfig.cmake 
was installed. <a href="http://techbase.kde.org/Development/Tutorials/CMake#Using_CMake_for_a_KDE_Project">Here</a> 
you have more information about CMake macros.

Now, let see this basic template for a CMake project:

\code
project(mycalculator)

find_package(KDE4 REQUIRED)
find_package(Qt4 REQUIRED)
find_package(OpenGL REQUIRED)
find_package(Analitza REQUIRED)

include_directories(
  ${KDE4_INCLUDES}
  ${CMAKE_SOURCE_DIR}
  ${CMAKE_CURRENT_BINARY_DIR} 
  ${ANALITZA_INCLUDE_DIR} 
  ${OPENGL_INCLUDE_DIR}
)

set(mycalculator_SRCS main.cpp)

kde4_add_executable(mycalculator ${mycalculator_SRCS})

target_link_libraries(mycalculator 
  ${KDE4_KDECORE_LIBS} 
  ${QT_QTGUI_LIBRARY} 
  ${ANALITZA_LIBRARY} 
  ${ANALITZAPLOT_LIBRARY}
  ${ANALITZAGUI_LIBRARY}
  ${OPENGL_gl_LIBRARY}
  ${OPENGL_glu_LIBRARY}
  ${QT_QTOPENGL_LIBRARY}
)
\endcode

*/


/** \page tutorials Tutorials

<p><b>
\ref index "Overview" |
\ref getting_started "Getting Started" |
Tutorials |
\ref examples_showcases "Examples and Showcases"
</b></p>

\section simple_parser A simple parser demo

If you want to evaluate a simple math expression like sin(pi/6)+3, first you need to 
create the \ref Analitza::Expression "Expression" that encapsules the string value 
and then you can use \ref Analitza::Analyzer "Analyzer" to get the result:

\code
#include <iostream>
#include <analitza/analyzer.h>
#include <analitza/value.h>

using namespace std;
using namespace Analitza;

int main(int argc, char *argv[]) {
	QString input("sin(pi/6)+3");
	Expression exp(input); // create a math expression
	Analyzer a; // setup the Analyzer instance with its own Variables module

	a.setExpression(exp); // Analyzer needs to know about expression
	double result = a.calculate().toReal().value(); // get the numeric result

	cout << result << endl;

	return 0;
}
\endcode

You can also use \ref Analitza::Expression "Expression" to make some queries, 
for example, in regards to the data type of the expression, the next code prints 
0 (false):

\code
	bool eq = exp.isEquation(); // or a.expression().isEquation()
	cout << eq << endl;
\endcode

\section advanced_parser Some advanced parsing features
Lets create a variable k = 2.1 and a function f(x) = sin(x) + k. We will 
calculate values for a lambda expression (our f(x) function) and get the 
derivative of f(x) (wich is a lambda expression too: d(f(x))=f'(x)):

\code
#include <iostream>
#include <analitza/analyzer.h>
#include <analitza/variables.h>
#include <analitza/value.h>

using namespace std;
using namespace Analitza;

int main(int argc, char *argv[]) {
	Variables *vars = new Variables(); // create a variables container 
	vars->modify("k", 2.1); // add a new variable called k with initial value 2.1

	Expression func("x->sin(x) + k"); // create our lambda f(x)=sin(x) + k

	Cn *x = new Cn(); // create a bound variable to manipulate x in f(x)
	x->setValue(3.14); // set a initial value for x

	Analyzer a(vars); // when calculating, Analyzer will access to variables in vars
	QStack<Object*> runStack; // Analyzer use this stack to calculate f(x)
	runStack.push(x); // add our bound variable to the stack

	Expression result; // an expression instance to save computations and result 

	// play with f(x)
	a.setExpression(func);
	a.setStack(runStack); // this is important to calculate lambda expressions
	result = a.calculateLambda();

	cout << func.toString().toStdString() << endl;
	cout << result.isReal() << endl; // simple query
	cout << result.toReal().value() << endl; // get f(3.14)

	// get the derivative of f(x) and play with it
	Expression dfunc = a.derivative("x");
	a.setExpression(dfunc); // update the expression
	a.setStack(runStack); // this is important, update the stack too
	result = a.calculateLambda();

	cout << dfunc.toString().toStdString() << endl; // get the derivative string
	cout << result.toReal().value() << endl; // derivative of f(x) at x = 3.14

	delete vars; // free the memory

	return 0;
}
\endcode

*/


/** \page examples_showcases Examples and Showcases

<p><b>
\ref index "Overview" |
\ref getting_started "Getting Started" |
\ref tutorials "Tutorials" |
Examples and Showcases
</b></p>

You can find 
<a href="http://lxr.kde.org/source/kde/kdeedu/analitza/analitzaplot/examples/">examples</a> 
of \ref AnalitzaPlotModule "AnalitzaPlot" and also check the tests folders of each 
modules 
<a href="http://lxr.kde.org/source/kde/kdeedu/analitza/analitza/tests/">here</a>, 
<a href="http://lxr.kde.org/source/kde/kdeedu/analitza/analitzaplot/tests/">here</a>, 
and
<a href="http://lxr.kde.org/source/kde/kdeedu/analitza/analitzagui/tests/">here</a>.

Also, remember that Analitza is used by applications like:
\li <a href="http://edu.kde.org/kalgebra/">KAlgebra</a> (see the 
<a href="http://lxr.kde.org/source/kde/kdeedu/kalgebra/">sources</a>).
\li A backend of <a href="http://edu.kde.org/cantor/">Cantor</a> (see the 
<a href="http://lxr.kde.org/source/kde/kdeedu/cantor/src/backends/kalgebra/">sources</a>).
\li <a href="http://lxr.kde.org/source/kde/kdeedu/analitza/calgebra/">calgebra</a>.

*/


/** \defgroup AnalitzaModule Analitza
This is the main module of Analitza, it provides a parser for mathematical expressions.
*/


/** \defgroup AnalitzaPlotModule AnalitzaPlot
This is module is a plotting framework for mathemathical objects.
*/


/** \defgroup AnalitzaGUIModule AnalitzaGUI
This is module contains UI controls for Analitza.
*/


// DOXYGEN_SET_PROJECT_NAME = Analitza
// DOXYGEN_SET_RECURSIVE = YES
// DOXYGEN_SET_FILE_PATTERNS = *.h *.dox
// DOXYGEN_SET_EXCLUDE += @topdir@/analitza/abstractlexer.h
// DOXYGEN_SET_EXCLUDE += @topdir@/analitza/explexer.h
// DOXYGEN_SET_EXCLUDE += @topdir@/analitza/mathmlpresentationlexer.h
// DOXYGEN_SET_EXCLUDE += @topdir@/analitza/expressionparser.h
// DOXYGEN_SET_EXCLUDE += @topdir@/analitza/pushvalue.h
// DOXYGEN_EXCLUDE_PATTERNS = *_p.h */private/* */tests/* */examples/* 
// vim:ts=4:sw=4:expandtab:filetype=doxygen