[kde-doc-english] [kartesio] /: CMake fixed and basic documentation ready.
Luca Tringali
tringalinvent at libero.it
Tue May 7 21:38:52 UTC 2013
Git commit 032f56ad7f855b1d16f22e9a7e2dddda2e405638 by Luca Tringali.
Committed on 07/05/2013 at 23:33.
Pushed by lucatringali into branch 'master'.
CMake fixed and basic documentation ready.
M +5 -1 CMakeLists.txt
A +8 -0 build.sh
A +33 -0 cmake-mod/Findzorbaneural.cmake
A +5 -0 doc/CMakeLists.txt
A +297 -0 doc/index.docbook
A +68 -0 doc/man-kartesio.1.docbook
A +- -- doc/neuralnet1.png
A +- -- doc/neuralnet2.png
A +- -- doc/neuralnet3.png
A +- -- doc/quick-start.png
A +- -- doc/redraw.png
A +- -- doc/regression1.png
A +- -- doc/regression2.png
A +- -- doc/regression3.png
A +- -- doc/regression4.png
A +- -- doc/regression5.png
A +- -- doc/rms.png
M +3 -3 src/main.cpp
http://commits.kde.org/kartesio/032f56ad7f855b1d16f22e9a7e2dddda2e405638
diff --git a/CMakeLists.txt b/CMakeLists.txt
index 817092a..d8e3c39 100644
--- a/CMakeLists.txt
+++ b/CMakeLists.txt
@@ -1,7 +1,10 @@
project(kartesio)
+set(CMAKE_MODULE_PATH ${CMAKE_MODULE_PATH} "${CMAKE_SOURCE_DIR}/cmake-mod/")
+
find_package(KDE4 REQUIRED)
find_package( Qt4 REQUIRED )
+find_package(zorbaneural REQUIRED)
add_definitions(${KDE4_DEFINITIONS} ${QT_DEFINITIONS})
include_directories(${CMAKE_SOURCE_DIR} ${CMAKE_BINARY_DIR} ${KDE4_INCLUDES} ${KDE4_INCLUDE_DIR} ${QT_INCLUDES} )
@@ -18,4 +21,5 @@ message(STATUS "using oxygen application icons from ${KDE4_ICON_DIR}")
add_subdirectory(src)
-add_subdirectory(icons)
\ No newline at end of file
+add_subdirectory(icons)
+add_subdirectory(doc)
\ No newline at end of file
diff --git a/build.sh b/build.sh
new file mode 100755
index 0000000..5a6e157
--- /dev/null
+++ b/build.sh
@@ -0,0 +1,8 @@
+mkdir build
+cd build
+sudo make uninstall
+make clean
+rm CMakeCache.txt
+cmake .. -DCMAKE_INSTALL_PREFIX=`kde4-config --prefix`
+make
+sudo make install
diff --git a/cmake-mod/Findzorbaneural.cmake b/cmake-mod/Findzorbaneural.cmake
new file mode 100644
index 0000000..2ecb9d2
--- /dev/null
+++ b/cmake-mod/Findzorbaneural.cmake
@@ -0,0 +1,33 @@
+#locate libzorbaneural library
+
+# This module defines
+# LIBZORBANEURAL_LIBRARY
+# LIBZORBANEURAL_FOUND
+# LIBZORBANEURAL_INCLUDE_DIR
+# LIBZORBANEURAL_CFLAGS
+# LIBZORBANEURAL_LINKFLAGS
+
+
+IF(LIBZORBANEURAL_LIBRARY AND LIBZORBANEURAL_INCLUDE_DIR)
+ SET(LIBZORBANEURAL_FOUND TRUE)
+ELSE(LIBZORBANEURAL_LIBRARY AND LIBZORBANEURAL_INCLUDE_DIR)
+ INCLUDE(UsePkgConfig)
+ PKGCONFIG("libzorbaneural" _libzorbaneuralIncDir _libzorbaneuralLibDir _libzorbaneuralLinkFlags _libzorbaneuralCflags)
+
+ # set additional flags needed to compile/link against libzorbaneural
+ SET(LIBZORBANEURAL_CFLAGS ${_libzorbaneuralCFlags} CACHE STRING "CFLAGS required for libzorbaneural")
+ SET(LIBZORBANEURAL_LINKFLAGS ${_libzorbaneuralLinkFlags} CACHE STRING "Flags used for linking against libzorbaneural")
+
+ # search for include and library path
+ FIND_PATH(LIBZORBANEURAL_INCLUDE_DIR libzorbaneural/neuralnet.h PATHS ${_libzorbaneuralIncDir} ${_libzorbaneuralIncDir}/libzorbaneural)
+ FIND_LIBRARY(LIBZORBANEURAL_LIBRARY zorbaneural PATHS ${_libzorbaneuralLibDir})
+
+ IF(LIBZORBANEURAL_INCLUDE_DIR AND LIBZORBANEURAL_LIBRARY)
+ SET(LIBZORBANEURAL_FOUND TRUE)
+ MESSAGE(STATUS "Found libzorbaneural: ${LIBZORBANEURAL_LIBRARY}")
+
+ ELSE(LIBZORBANEURAL_INCLUDE_DIR AND LIBZORBANEURAL_LIBRARY)
+ SET(LIBZORBANEURAL_FOUND FALSE)
+ MESSAGE(SEND_ERROR "Could NOT find libzorbaneural")
+ ENDIF(LIBZORBANEURAL_INCLUDE_DIR AND LIBZORBANEURAL_LIBRARY)
+ENDIF(LIBZORBANEURAL_LIBRARY AND LIBZORBANEURAL_INCLUDE_DIR)
\ No newline at end of file
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
new file mode 100644
index 0000000..637a494
--- /dev/null
+++ b/doc/CMakeLists.txt
@@ -0,0 +1,5 @@
+########### install files ###############
+#
+
+kde4_create_handbook(index.docbook INSTALL_DESTINATION ${HTML_INSTALL_DIR}/en SUBDIR kartesio)
+kde4_create_manpage(man-kartesio.1.docbook 1 INSTALL_DESTINATION ${MAN_INSTALL_DIR})
diff --git a/doc/index.docbook b/doc/index.docbook
new file mode 100644
index 0000000..ff2b5c5
--- /dev/null
+++ b/doc/index.docbook
@@ -0,0 +1,297 @@
+<?xml version="1.0" ?>
+<!DOCTYPE book PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!-- <!ENTITY kappname "Kartesio">
+ <!ENTITY package "kdeedu">
+ <!ENTITY % addindex "IGNORE"> -->
+ <!ENTITY % English "INCLUDE"><!-- change language only here -->
+ ]>
+
+ <book lang="&language;">
+
+ <bookinfo>
+ <title>The Kartesio Handbook</title>
+
+ <authorgroup>
+ <author>
+ <firstname>Luca</firstname>
+ <surname>Tringali</surname>
+ <affiliation>
+ <address>TRINGALINVENT at libero.it</address>
+ </affiliation>
+ </author>
+
+ <!-- TRANS:ROLES_OF_TRANSLATORS -->
+
+ </authorgroup>
+
+ <copyright>
+ <year>2013</year>
+ <holder>Luca Tringali</holder>
+ </copyright>
+
+ <legalnotice>&FDLNotice;</legalnotice>
+
+ <date>2013-05-07</date>
+ <releaseinfo>0.1.00 (&kde; 4.11)</releaseinfo>
+
+ <abstract>
+ <para>Kartesio is a program for calculating best fit curves with
+ experimental points using regression algorithms or neural networks.</para>
+ </abstract>
+
+ <keywordset>
+ <keyword>KDE</keyword>
+ <keyword>education</keyword>
+ <keyword>elements</keyword>
+ <keyword>chemistry</keyword>
+ <keyword>university</keyword>
+ <keyword>physics</keyword>
+ <keyword>kartesio</keyword>
+ </keywordset>
+
+ </bookinfo>
+
+ <chapter id="introduction">
+ <title>Introduction</title>
+
+ <para>Kartesio is a program for calculating best fit curves with
+ experimental points using regression algorithms or neural networks.
+ It is free and licensed under the &GNU; Public License.
+ </para>
+
+ <para>Kartesio has a simple interface that allows you to plot points
+ and a curve. The curve is usually calculated by the program, but you
+ can also write it by yourself.</para>
+
+ </chapter>
+
+ <chapter id="quick-start">
+ <title>Kartesio quick start guide</title>
+
+ <para>As soon as you open Kartesio, you will get a blank table and a blank plot. This is also the same screen you can get in every moment just clicking on (<menuchoice> <guimenu>File</guimenu> <guimenuitem>New</guimenuitem> </menuchoice>). You can try to best fit your experimental points with a regression algorithm or a neural network, using the tools in the appropriate tab. Please note that regression algorithm needs maxima to be installed on your computer.</para>
+ <screenshot>
+ <screeninfo>Kartesio main window</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="quick-start.png" format="PNG" /></imageobject>
+ <textobject><phrase>Kartesio main window</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ </chapter>
+ <chapter id="regression">
+ <title>Regression</title>
+
+ <para>
+ You should start adding your points to the table. Obiously, a bidimensional point is identified with two coordinates (on X and Y axis).
+ </para>
+
+ <screenshot>
+ <screeninfo>Adding points</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="regression1.png" format="PNG" /></imageobject>
+ <textobject><phrase>Adding points</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>In the "Regression" tab, you can write a generic function that will be used by Kartesio as a model for the fitting curve. The function must be written with the variables x and y, and with variable coefficients (represented by letters). Obiously, you can also write numeric coefficients. Please take note that the function must be biuniqe.</para>
+
+ <screenshot>
+ <screeninfo>Writing a generic function</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="regression2.png" format="PNG" /></imageobject>
+ <textobject><phrase>Writing a generic function</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Clicking the "Best fit" button, Kartesio will start to calculate coefficients for the function you wrote, trying to best fit the experimental points. The final function will appear the edit box close to the bottom edge of the window.</para>
+
+ <screenshot>
+ <screeninfo>Best fit done</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="regression3.png" format="PNG" /></imageobject>
+ <textobject><phrase>Best fit done</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>After the fit operation, points and the curve will be automatically plotted. Anyway, you may prefer to change to plotted area to see better the image. This can be done using the four spinboxes: Xmin is the minimum value of X axis, and Xmax is the maximum value. For example, if you write respectively 0 and 1, then the plot will start from 0 and end to 1. The same logic works for Y axisi.</para>
+
+ <screenshot>
+ <screeninfo>A closer look</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="regression4.png" format="PNG" /></imageobject>
+ <textobject><phrase>A closer look</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>If you change plot limits, you may need to change also the resolution: if the resolution of the plot is too little, you will se every curve as a single line. If the resoolution is too much high you will waste a lot of CPU time to draw the plot.</para>
+
+ <screenshot>
+ <screeninfo>Higher resolution</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="regression5.png" format="PNG" /></imageobject>
+ <textobject><phrase>Higher resolution</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ </chapter>
+
+ <chapter id="neuralnet">
+ <title>Neural Network</title>
+
+ <para>
+ The neural network method works like the regression one, but you can not write you own function: you must choose it from a list. This list, anyway, contains practically every kind of function you may want (periodic functions are not usable with a neural network).
+ </para>
+
+ <screenshot>
+ <screeninfo>Choosing the correct function</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="neuralnet1.png" format="PNG" /></imageobject>
+ <textobject><phrase>Choosing the correct function</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>Usually, backpropagation training is just what you need. For this reason it is checked by default. Just modify the number of iterations (it should nto be too much high, or the process may end up with way too strange value) and then press the Calculate button. Please take note that the neural network, exactly as a human brain, may give you different results: just press the Calculate button more than one time and you will find out that the network calculates every time a different best fitting curve.</para>
+
+ <screenshot>
+ <screeninfo>Back propagation training</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="neuralnet2.png" format="PNG" /></imageobject>
+ <textobject><phrase>Back propagation training</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>If you are not satisfied by the back propagation training result, you could also use the genetic algorithm training. This can be done simply checking the appropriate checkbox. Gen alg training takes a lot more CPU resources, so you better use a very low iterations number (not more than 500). </para>
+
+ <screenshot>
+ <screeninfo>Genetic algorithm training</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="neuralnet3.png" format="PNG" /></imageobject>
+ <textobject><phrase>Genetic algorithm training</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ </chapter>
+
+ <chapter id="others">
+ <title>Other useful things</title>
+
+ <para>
+ Sometimes it is useful to redraw the plot. For example, it is if you manually changed the best fitting curve or if you edited some points and you don't want to recalculate the fitting function. Just use the "Draw Plot" button.
+ </para>
+
+ <screenshot>
+ <screeninfo>Draw plot</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="redraw.png" format="PNG" /></imageobject>
+ <textobject><phrase>Draw plot</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ <para>
+ To know how much the fitting curve is different from you experimental points, you can look at the root mean square error. To add it to the plot it is needed to check the checkbox "Show RMS error". Then press the "Draw Plot" button to redraw the plot: it should contain a red label with the RMS error.
+ </para>
+
+ <screenshot>
+ <screeninfo>Showing RMS error</screeninfo>
+ <mediaobject>
+ <imageobject><imagedata fileref="rms.png" format="PNG" /></imageobject>
+ <textobject><phrase>Showing RMS error</phrase></textobject>
+ </mediaobject>
+ </screenshot>
+
+ </chapter>
+
+ <chapter id="faq">
+ <title>Questions and Answers</title>
+
+ <qandaset id="faqlist">
+ <qandaentry>
+ <question>
+ <para>Will I ever have to pay for Kartesio?</para>
+ </question>
+ <answer>
+ <para>No, never. Kartesio is licensed
+ under the <ulink url="http://www.gnu.org/licenses/licenses.html#GPL">GPL</ulink>, so you will never have to pay for this program.</para>
+ </answer>
+ </qandaentry>
+
+ </qandaset>
+ </chapter>
+
+ <chapter id="contribute">
+ <title>How can I contribute?</title>
+
+ <qandaset id="tasks">
+ <qandaentry>
+ <question>
+ <para>Find some bugs or give some suggestions</para>
+ </question>
+ <answer>
+ <para>
+ If you find any bugs in the program, or have a few suggestions for
+ improvements, please let me know at TRINGALINVENT at libero.it.
+ </para>
+ </answer>
+
+ </qandaentry>
+ </qandaset>
+ </chapter>
+
+ <chapter id="credits">
+
+ <title>Credits and License</title>
+ <para>Kartesio</para>
+ <para>
+ Program Copyright, 2001-2005 Luca Tringali
+ TRINGALINVENT at libero.it
+ </para>
+
+ <!-- TRANS:CREDIT_FOR_TRANSLATORS -->
+
+ &underFDL; <!-- FDL: do not remove -->
+ &underGPL; <!-- GPL License -->
+
+ </chapter>
+
+ <appendix id="installation">
+ <title>Installation</title>
+
+ <sect1 id="getting-kartesio">
+ <title>How to obtain Kartesio</title>
+
+ &install.intro.documentation;
+
+ </sect1>
+
+ <sect1 id="web_presence">
+ <title>Web Presence</title>
+
+ <para>
+ Kartesio itself can be found on <ulink
+ url="https://projects.kde.org/projects/playground/edu/kartesio">The Kartesio home page</ulink> and
+ is part of the &kde;-Edu project</para>
+
+ </sect1>
+
+ <sect1 id="compilation">
+ <title>Compilation and Installation</title>
+
+ &install.compile.documentation;
+
+ </sect1>
+
+ </appendix>
+
+ &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:
+
+ // vim:ts=2:sw=2:tw=78:noet:noai
+ -->
diff --git a/doc/man-kartesio.1.docbook b/doc/man-kartesio.1.docbook
new file mode 100644
index 0000000..319c888
--- /dev/null
+++ b/doc/man-kartesio.1.docbook
@@ -0,0 +1,68 @@
+<?xml version="1.0" ?>
+<!DOCTYPE refentry PUBLIC "-//KDE//DTD DocBook XML V4.2-Based Variant V1.1//EN" "dtd/kdex.dtd" [
+<!ENTITY % English "INCLUDE">
+]>
+
+<refentry lang="&language;">
+<refentryinfo>
+<author><personname><firstname>Luca</firstname><surname>Tringali</surname></personname></author>
+<date>2013-05-07</date>
+</refentryinfo>
+
+<refmeta>
+<refentrytitle><command>kartesio</command></refentrytitle>
+<manvolnum>1</manvolnum>
+</refmeta>
+
+<refnamediv>
+<refname><command>kartesio</command></refname>
+<refpurpose>A KDE based data analisys tool.</refpurpose>
+</refnamediv>
+
+<refsynopsisdiv>
+<cmdsynopsis>
+<command>kartesio</command>
+
+<group><option>KDE Generic Options</option></group>
+<group><option>Qt Generic Options</option></group>
+
+</cmdsynopsis>
+</refsynopsisdiv>
+
+<refsect1>
+<title>Description</title>
+
+ <para>Kartesio is a program for calculating best fit curves with
+experimental points using regression algorithms or neural networks.
+</para>
+
+<para>Kartesio has a simple interface that allows you to plot points
+and a curve. The curve can be calculated by the program or you can also
+write it by yourself.</para>
+
+<para>This package is part of the official KDE edutainment module. </para>
+
+</refsect1>
+
+<refsect1>
+<title>See Also</title>
+
+<para>More detailed user documentation is available from <ulink
+url="help:/kartesio">help:/kartesio</ulink> (either enter this
+<acronym>URL</acronym> into &konqueror;, or run
+<userinput><command>khelpcenter</command>
+<parameter>help:/kartesio</parameter></userinput>).</para>
+
+
+</refsect1>
+
+<refsect1>
+<title>Authors</title>
+
+<para>Kartesio was written by Luca Tringali - TRINGALINVENT at libero.it </para>
+
+<para>This manual page was prepared by <personname><firstname>Luca</firstname><surname>Tringali</surname></personname></para>
+
+</refsect1>
+
+</refentry>
diff --git a/doc/neuralnet1.png b/doc/neuralnet1.png
new file mode 100644
index 0000000..8a15f0b
Binary files /dev/null and b/doc/neuralnet1.png differ
diff --git a/doc/neuralnet2.png b/doc/neuralnet2.png
new file mode 100644
index 0000000..ed002f7
Binary files /dev/null and b/doc/neuralnet2.png differ
diff --git a/doc/neuralnet3.png b/doc/neuralnet3.png
new file mode 100644
index 0000000..93cbe36
Binary files /dev/null and b/doc/neuralnet3.png differ
diff --git a/doc/quick-start.png b/doc/quick-start.png
new file mode 100644
index 0000000..bc681aa
Binary files /dev/null and b/doc/quick-start.png differ
diff --git a/doc/redraw.png b/doc/redraw.png
new file mode 100644
index 0000000..d211c29
Binary files /dev/null and b/doc/redraw.png differ
diff --git a/doc/regression1.png b/doc/regression1.png
new file mode 100644
index 0000000..d75c6ae
Binary files /dev/null and b/doc/regression1.png differ
diff --git a/doc/regression2.png b/doc/regression2.png
new file mode 100644
index 0000000..530a57b
Binary files /dev/null and b/doc/regression2.png differ
diff --git a/doc/regression3.png b/doc/regression3.png
new file mode 100644
index 0000000..b57f0a2
Binary files /dev/null and b/doc/regression3.png differ
diff --git a/doc/regression4.png b/doc/regression4.png
new file mode 100644
index 0000000..830288e
Binary files /dev/null and b/doc/regression4.png differ
diff --git a/doc/regression5.png b/doc/regression5.png
new file mode 100644
index 0000000..02e71fa
Binary files /dev/null and b/doc/regression5.png differ
diff --git a/doc/rms.png b/doc/rms.png
new file mode 100644
index 0000000..125abda
Binary files /dev/null and b/doc/rms.png differ
diff --git a/src/main.cpp b/src/main.cpp
index decb3bb..bcca146 100644
--- a/src/main.cpp
+++ b/src/main.cpp
@@ -8,10 +8,10 @@
#include "mainwindow.h"
-#define APP_VERSION "0.9.80"
+#define APP_VERSION "0.1.00"
static const char description[] =
- I18N_NOOP("A program to calculate best fit curves");
+ I18N_NOOP("A program for calculating best fit curves with experimental points.");
static const char version[] = APP_VERSION;
@@ -19,7 +19,7 @@ static const char version[] = APP_VERSION;
int main(int argc, char *argv[])
{
- KAboutData about("kartesio", 0, ki18n("Kartesio"), version, ki18n(description), KAboutData::License_GPL, ki18n("(C) 2010-2011 Luca Tringali"), KLocalizedString(), "http://edu.kde.org/kartesio");
+ KAboutData about("kartesio", 0, ki18n("Kartesio"), version, ki18n(description), KAboutData::License_GPL, ki18n("(C) 2011-2013 Luca Tringali"), KLocalizedString(), "https://projects.kde.org/projects/playground/edu/kartesio");
about.addAuthor( ki18n("Luca Tringali"), KLocalizedString(), "TRINGALINVENT at libero.it" );
//about.addCredit(ki18n("your name here"),ki18n("What you have done"));
More information about the kde-doc-english
mailing list