Merge branch 'plot-legend-doc' into x-plot-legend - gsl-shell.git - gsl-shell

diff --git a/INSTALL b/INSTALL
index 6b8c639d..24608484 100644
--- a/INSTALL
+++ b/INSTALL

@@ -1,5 +1,5 @@

-GSL Shell 2.0

+GSL Shell 2.1

** BUILD INSTRUCTION

diff --git a/README b/README
index 1c15146d..b9e4ba81 100644
--- a/README
+++ b/README

@@ -1,5 +1,5 @@

-* GSL shell 2.0

+* GSL shell 2.1

* Copyright (C) 2009-2011 Francesco Abbate

* Author: Francesco Abbate

* Published under GNU GENERAL PUBLIC LICENSE, version 3

diff --git a/defs.h b/defs.h
index e9a24ad6..0ba40c63 100644
--- a/defs.h
+++ b/defs.h

@@ -32,7 +32,7 @@

#endif

#define LUA_INDEX_CONVENTION

-#define GSL_SHELL_RELEASE "2.0.0"

+#define GSL_SHELL_RELEASE "2.1.0"

#ifdef WIN32

#ifndef __cplusplus

diff --git a/doc/gsl-shell-index/benchmarks.rst b/doc/gsl-shell-index/benchmarks.rst
new file mode 100644
index 00000000..76374332
--- /dev/null
+++ b/doc/gsl-shell-index/benchmarks.rst

@@ -0,0 +1,55 @@

+

+.. _benchmarks:

+

+Benchmarks

+==========

+

+The performance of the algorithms implemented in GSL Shell have been tested agaist an equivalent C implementation.

+

+The purpose of the benchmarks is twofold. One of the objectives is to test the correctness of the results against the native GSL implementation while the other is to compare C and Lua implementation in term of performance.

+

+The performance is measured simply in term of time of execution, no attemt has been done to add other factors like memory utilisation or others.

+

+Besides the benchmark of optimized C code the LuaJIT2 implementation was tested with and without the JIT support enabled.

+When the JIT support is disabled (option ``-joff``) the algorithm is executed in purely interpreted mode.

+This latter result is reported to give an idea of the improvement given by the JIT compiler.

+

+Results

+-------

+

+We present here the results of the benchmark in term of execution time.

+The time is normalized taking the ratio with the 'LuaJIT2' results.

+The ratio obtained is therefore plotted in logarithmic scale.

+

+.. figure:: gsl-shell-benchmark.png

+

+A few remarks about these results.

+

+Only a very few ODE algorithms are currently implemented in GSL Shell and these use an interface different of those used in the GSL library.

+In GSL Shell the variables of the ode system are not packed into an array but are passed like function arguments.

+One implication is that only ODE system with a small number of variables can be integrated.

+This difference can affect the execution speed and should be kept in mind.

+

+Otherwise there is nothing that prevents the implementation in GSL Shell of an ODE integrator in array form.

+This is actually planned to be done in the near future.

+

+For all the other algorithms the GSL implementation closely mirror the GSL interface and the comparaison is aboslutely fair.

+

+

+Technical details

+-----------------

+

+The C and Lua version of the benchmark was written to solve exactly the same problem with the same input values and the same algorithm parameters.

+

+The C version of the benchmark was compiled using the following compiler flags: ``-O2 -fomit-frame-pointer``.

+The GSL library itself was compiled with the same options and the executable was created by linking to the GSL shared library.

+

+While some tweak of the compiler options are possible to improve performance of GSL C code no attempt was done in this direction.

+The idea was that we want to compare the Lua implementation with a C executable compiled with standard optimizing options and in accord to common practices.

+

+Benchmark availability

+----------------------

+

+The source code of all the benchmark is available with the GSL Shell source code inside the 'benchmarks' folder.

+

+We encourage all the interested users to reproduce the benchmarks results by themselves.

diff --git a/doc/gsl-shell-index/conf.py b/doc/gsl-shell-index/conf.py
index 09f8e0d0..f0380a6f 100644
--- a/doc/gsl-shell-index/conf.py
+++ b/doc/gsl-shell-index/conf.py

@@ -48,9 +48,9 @@ copyright = u'2011, Francesco Abbate'

# built documents.

#

# The short X.Y version.

-version = '2.0'

+version = '2.1'

# The full version, including alpha/beta/rc tags.

-release = '2.0.0'

+release = '2.1.0'

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

diff --git a/doc/gsl-shell-index/gsl-shell-benchmark.png b/doc/gsl-shell-index/gsl-shell-benchmark.png
new file mode 100644
index 00000000..d20c5156
--- /dev/null
+++ b/doc/gsl-shell-index/gsl-shell-benchmark.png

diff --git a/doc/gsl-shell-index/index.rst b/doc/gsl-shell-index/index.rst
index be0c50d4..a764beb4 100644
--- a/doc/gsl-shell-index/index.rst
+++ b/doc/gsl-shell-index/index.rst

@@ -60,6 +60,7 @@ Contents:

:maxdepth: 2

download.rst

+ benchmarks.rst

why-donate.rst

older-news.rst

acknowledgments.rst

diff --git a/doc/user-manual/conf.py b/doc/user-manual/conf.py
index 13449488..5a8a3733 100644
--- a/doc/user-manual/conf.py
+++ b/doc/user-manual/conf.py

@@ -48,9 +48,9 @@ copyright = u'2009-2011, Francesco Abbate'

# built documents.

#

# The short X.Y version.

-version = '2.0'

+version = '2.1'

# The full version, including alpha/beta/rc tags.

-release = '2.0.0'

+release = '2.1.0'

# The language for content autogenerated by Sphinx. Refer to documentation

# for a list of supported languages.

diff --git a/doc/user-manual/graphics-categories-example.png b/doc/user-manual/graphics-categories-example.png
new file mode 100644
index 00000000..37effa4b
--- /dev/null
+++ b/doc/user-manual/graphics-categories-example.png

diff --git a/doc/user-manual/graphics.rst b/doc/user-manual/graphics.rst
index c929b420..b43e80d7 100644
--- a/doc/user-manual/graphics.rst
+++ b/doc/user-manual/graphics.rst

@@ -252,6 +252,28 @@ We give in this section the description of all the higher level plotting functio

.. figure:: graphics-example-ibars.png

+.. function:: rgb(r, g, b)

+ rgba(r, g, b, a)

+

+ Returns a color specified by the given ``r``, ``g``, ``b`` values.

+ These latters should be numbers in the interval [0, 1].

+ The second variant of the function let you specify an alpha value.

+ This latter can range from 0 (completely transparent) to 1 (completely opaque).

+

+ In GSL Shell a color is encoded as an integer number with 8 bit per channel and 4 channels, R, G, B, A in the given order.

+ To express a pure green color you can for example write::

+

+ green = 0x00ff00ff

+

+ where the last two digits express the alpha value equal to 255 for opaque color.

+

+.. function:: raindow(n)

+ webcolor(n)

+

+ Returns a color from a predefined palette.

+ The argument ``n`` can be any integer number to select the color.

+ A limited number of colors is available and they are repeated cyclically.

+

Multiple plot window

--------------------

@@ -514,6 +536,34 @@ You can add elements to a plot in any moments even when it is already shown. GSL

Save the plot in the given filename in SVG format.

Two optional parameters can be given to specify the width and height of the drawing area.

+

+ .. method:: set_mini(placement, p)

+

+ Add the plot ``p`` as a small plot is the side area of the main plot.

+ The argument ``placement`` is used to give the placement of the mini plot and should be on of the letters 'l', 'r', 'b', 't'.

+ They stands for "left", "right", "bottom" and "top" respectively.

+

+ The mini plot is shown using an region of the drawing area are equal to the bounding box of the mini plot itself.

+ When rendered as a mini plot the plot coordinates and the screen coordinates are therefore in a one-to-one scale rapport.

+

+ .. method:: set_categories(axis, categories)

+

+ Configure the given ``axis`` (a letter, 'x' or 'y') to use a custom set of labels specified by ``categories``.

+ This latter should be a list of that gives in a sequence, the values where the label should be placed and the label text itself.

+ The coordinate refers to the plot system of coordinates.

+

+ Example::

+

+ use 'math'

+

+ p = graph.fxplot(sin, 0, 2*pi)

+ p:set_categories('x', {0, '0', pi, 'pi', 2*pi, '2 pi'})

+ p.title = 'Sin function'

+

+ will produce the following plot:

+

+ .. figure:: graphics-categories-example.png

+

.. attribute:: title

The title of the plot. You can change or set the title using

@@ -650,6 +700,25 @@ Graphical Objects

Set the position where the test is diplayed. It corresponds to

the bottom left corner of the text.

+.. function:: textshape(x, y, text, size)

+

+ Create a text shape graphical object of given ``text`` and ``size`` at the position ``x``, ``y``.

+

+.. class:: TextShape

+

+ A text shape object is used to display a text.

+ The difference with a simple text object is that a text shape has a well definite shape and extension in the plot system of coordinates.

+ One of the implications is that the text shape will occupy a well definite area and the plot can adapt its area to include the text itself.

+ For the other side text shape could be deformed if a different scale is used for x and y axis.

+ If the aspect ration of coordinate system is not unitary a simple "text" object should be used instead.

+

+ The text shape has currently no methods and its properties are determined during the creation of the object.

+

+ .. tip::

+ Text shape objects are useful to create plot legends.

+ In this case the size and position of the text shape can be expressed in screen coordinates (pixel).

+ The reason is that when a mini plot is added to a plot the area of the screen used to display the mini plot is equal to the bounding box of the mini plot itself.

+

.. _graphics-transforms:

Graphical transformations