matthew-hilty / glucat Goto Github PK

README for GluCat 0.8.2 with PyClical
=====================================

GluCat is a library of C++ template classes for calculations with the universal
Clifford algebras over the real field. The dimension of the algebras you can
use is limited only by computer word size. Unlike some software packages for
Clifford algebras, the maximum signature is fixed by default or by user defined
template parameter values, and calculations are performed in the appropriate
subalgebra.

GluCat classes are meant to be used as numeric classes with other template
libraries. To do this, GluCat classes need to look and behave like floating
point  numeric types such as float and double. The GluCat classes do this by
providing a definition for std::numeric_limits<>, most or all the expected
operators like +, -, *, /, and functions like sqrt(). In use with other template
libraries, you will need to look out for the differences between GluCat classes
and floating point numeric types. Two key differences are that Clifford algebras
do not have a total ordering, and that multiplication in Clifford algebras is
not necessarily commutative. A third difference is that not all non-zero
elements of a Clifford algebra have a multiplicative inverse.

PyClical is a Python extension module that is designed to make it easy for you
to use Python to perform computations in Clifford algebras, and to implement
algorithms and programs that use these computations. The syntax and semantics
of the main index_set and clifford classes in PyClical is designed to be as
similar as possible to that of the GluCat template classes index_set<> and
matrix_multi<double>, so that you should be able to use PyClical to teach
yourself how to use calculations in Clifford algebras, and then transfer that
knowledge to your ability to use GluCat template classes in C++.


Before you go any further
=========================

To make the best use of the GluCat template library and the PyClical extension
module, you will need to become familiar with Geometric Algebra and Clifford
algebras in general. The AUTHORS file includes lists of recommended web pages,
books, and software that can help you to learn about Clifford algebras. Here is
a short list to get you started.

o Wikipedia: Geometric algebra
  http://en.wikipedia.org/wiki/Geometric_algebra

o Alan Macdonald, A Survey of Geometric Algebra and Geometric Calculus
  http://faculty.luther.edu/~macdonal/GA&GC.pdf

o Alan Macdonald, Linear and Geometric Algebra, 2011.
  http://books.google.com.au/books?q=isbn:9781453854938

You should also install PyClical and run the tutorials. Once you have run the
PyClical tutorials, run the PyClical demos and look at the sample demo output.
Now examine the C++ code for the GluCat tests, as well as the sample output.
Finally, look at Glucat API documentation. Instructions for each of these steps
are given below.


Getting started
===============

To use the software to its full potential, you will want to:
1. Download and update the software,
2. Understand the source code directory structure,
3. Resolve dependencies, install and test the software,
4. Use the PyClical extension module with Python,
5. Write C++ programs that use GluCat classes,
6. Compile and run C++ programs that use GluCat classes, and finally,
7. Help to improve the software by requesting features, filing bug reports and
   writing your own source code patches.

These tasks are treated in some detail below.


1. Downloading and updating the software
----------------------------------------

You can download new versions of GluCat from
http://sourceforge.net/projects/glucat/files/
or alternatively, use the Git version:
From SourceForge: http://sourceforge.net/p/glucat/git/ci/master/tree/
From GitHub: https://github.com/penguian/glucat
For more on installing from Git, see INSTALL.


2. Understanding the source code directory structure
----------------------------------------------------

GluCat is a C++ template library, similar to the C++ Standard Library or the
Boost uBLAS Library (uBLAS). It consists of source code header files, a
suite of test routines, and the PyClical Python extension module and associated
files.

Once you have downloaded, unzipped and untarred the GluCat source code,
you should have a directory, glucat-xxx, where xxx is the version number.
Under glucat-xxx you should see a number of directories, including ./admin,
./doc, ./gfft_test, ./glucat, ./m4, ./products, ./pyclical, ./squaring, ./test,
./test_runtime, ./testxx,  and ./transforms.

The ./glucat directory contains all the header files that define the GluCat C++
template library.

The ./pyclical directory contains the C++ and Cython source code for the
PyClical Python extension module, as well as a subdirectory ./pyclical/demos
containing Python source code for the PyClical demos and tutorials, and sample
demo output.

The ./admin and ./m4 directories are part of the autotools infrastructure for
building GluCat, and should normally be left unchanged.

The ./doc directory contains documentation. Currently only the GluCat API
Reference Manual can be found here, under ./doc/api.

The ./gfft_test, ./products, ./squaring and ./transform directories contain the
C++ source code for timing tests for GluCat.

The ./test and ./testxx directories contain the C++ source code for programming
examples and regression tests for GluCat.

The ./test_runtime directory contains regression test input and sample output
for the GluCat timing and regression tests.


3. Resolving dependencies, installing and testing the software
--------------------------------------------------------------

Detailed instructions for these tasks are included in the ./INSTALL file in the
same directory that contains this README file.


4. Using the PyClical extension module with Python
--------------------------------------------------

The PyClical Python extension module is written in C++ and Cython, and is defined
in the files pyclical/glucat.pxd, pyclical/PyClical.h, pyclical/PyClical.pxd,
and pyclical/PyClical.pyx. PyClical is designed to be installed using make. For
details on building PyClical, see the ./INSTALL file.

The following instructions assume that you have already installed PyClical. If
you have only run make within the PyClical directory, but have not yet
installed PyClical, then, assuming you are using the bash interpreter on Linux,
you will need to set the PYTHONPATH environment variable so that Python can
find your newly built copy of PyClical. If the make has succeeded, you should
have the file ./pyclical/PyClical.so. Set PYTHONPATH to include the full
./pyclical directory path name before any other path names. For example:

  export PYTHONPATH=/home/leopardi/src/glucat/pyclical:$PYTHONPATH

or you can change the PYTHONPATH variable for just one command, e.g.

  PYTHONPATH=/home/leopardi/src/glucat/pyclical:$PYTHONPATH python

PyClical is designed to be used within a Python environment. You will usually
need to run a Python IDE or interpreter, such as IDLE, ipython or python. The
following instructions use the standard python interpreter.

To use the capabilities of PyClical from within Python, you must either import
the PyClical extension module or import objects from this module.  The simplest
way to do this is to use the following Python statement:

>>> from PyClical import *

Probably the easiest way to get familiar with PyClical is to make a copy of the
pyclical/demos directory and run the tutorials and demos. By default, the
pyclical/demos directory installs into /usr/local/share/pyclical/demos.

For example, assuming you are using the Bash shell on Linux, and have installed
PyClical, use the following commands:

% cp /usr/local/share/pyclical/demos /path/to/my/demos
% cd /path/to/my/demos
% python pyclical_tutorials.py

where you must replace /path/to/my/demos with the real pathname you want to use.

The pyclical_tutorials program starts by displaying

    Currently available PyClical tutorials:

    0.0 Notation.
    0.1 Index sets.
    0.2 Operations.
    0.3 Algebraic functions.
    0.4 Square root and transcendental functions.
    1.0 Plane geometry.
    1.1 Complex numbers.
    1.2 Space geometry and vector algebra.
    1.3 Electromagnetism and Lorentz transformations.
    1.4 The fourth dimension.
    1.5 Conformal Geometric Algebra.
    2.0 Exterior product.

    Enter the number for the tutorial you want to run, or Q to quit:

Just enter one of the numbers, e.g. 0.0, or Q to quit. At any point in an
individual tutorial, you can interrupt by entering CTRL-c.

If you are running Linux or a Unix equivalent, the following should also work:

% cd /path/to/my/demos
% chmod +x pyclical_tutorials.py
% ./pyclical_tutorials.py


For more usage examples, see the example Python files pyclical_demo.py,
plotting_demo.py, plotting_demo_mayavi.py, and sqrt_log_demo.py, and the example
output files pyclical_demo.out and sqrt_log_demo.out.

To run pyclical_demo.py and sqrt_log_demos.py, use the following commands:

% cd /path/to/my/demos
% python pyclical_demo.py
% python sqrt_log_demo.py

If you are running Linux or a Unix equivalent, the following should also work:

% cd /path/to/my/demos
% chmod +x pyclical_demo.py
% ./pyclical_demo.py
% chmod +x sqrt_log_demo.py
% ./sqrt_log_demo.py

To run plotting_demo.py, run "ipython --pylab" and enter the following commands
at the ipython prompt:

In [1]: %run plotting_demo

In [2]: help(demo)

In [3]: demo()

This demo uses Matplotlib to produce a number of plots.

To run plotting_demo_mayavi.py, first ensure that you have Mayavi2 and wxPython
installed and working.
(See http://code.enthought.com/projects/mayavi/ and http://www.wxpython.org/ )
Then run "ipython --gui=wx" and enter the following commands at the ipython prompt:

In [1]: %run plotting_demo_mayavi

In [2]: help(demo)

In [3]: demo()

This demo uses Matplotlib to produce a number of plots. With Mayavi and wxPython,
these plots are displayed in interactive windows, you can rotate, zoom and pan
them. See (e.g.) http://mayavi.sourceforge.net/docs/guide/ch03s04.html

You can also run the Mayavi plotting demo from a graphical user interface.
To do this, run "./plotting_demo_dialog.py". For this to work properly, you will
need to have Traits and TraitsUI installed. See (e.g.)
http://code.enthought.com/projects/traits/
http://code.enthought.com/projects/traits_ui/

The tutorials and demos are also accompanied by a corresponding set of IPython
notebooks. To build the notebooks, see INSTALL. To run the notebooks, assuming
that you have a copy of the notebooks in the directory /path/to/my/demos, you have
ipython installed, you have installed PyClical, or set PYTHONPATH appropriately,
and you are able to use ipython notebooks via a web browser, use the following
commands:

% cd /path/to/my/demos
% ipython notebook

Your web browser should open a new window or tab, displaying a page that lists
all of the available tutorials and demos as notebooks. To select a notebook,
click on the corresponding name in the list.


5. Writing C++ programs that use GluCat classes
-----------------------------------------------

Once you have familiarized yourself with Clifford algebras and have tried using
PyClical, take a good look at the test C++ code in ./test00 to ./test16 and the
test output in ./test_runtime.

A good way to begin writing your own C++ code using GluCat is to start with the
programming example code in ./test01. The file test01/peg01.cpp includes
test/driver.h and test01/peg01.h.

The key lines of code in test/driver.h are:

 #include "glucat/glucat.h"
 #include "test/tuning.h"
 #include "glucat/glucat_imp.h"

The first line includes <glucat/glucat.h>, a convenience header that includes
all the GluCat declarations.

The second line includes "test/tuning.h", a convenience header that defines
Tune_P, the tuning policy class. This class may be included as a template
parameter in future versions of GluCat, but for now, in your own code, you will
need to define it by using a typedef before including <glucat/glucat_imp.h>.
The glucat::tuning<> template class is defined in <glucat/global.h>. See
"test/tuning.h" for examples of values that you can use for the members of
Tune_P.

The third line includes <glucat/glucat_imp.h>, a convenience header that includes
all the GluCat definitions.

The key line of code in test01/peg01.h is:

 using namespace glucat;

Glucat defines and uses the glucat:: namespace. You can use names from this
namespace by using the glucat:: prefix or by the "using" declaration above.


To obtain detailed information on the GluCat namespaces, classes and functions,
see the Doxygen documentation in doc/api/GluCat-API-reference-manual.pdf (PDF)
and doc/api/html/ (HTML). By default, this documentation is installed in
the directories /usr/local/doc/glucat/api/html and /usr/local/doc/glucat/api/pdf.


6. Compiling and running C++ programs that use GluCat classes
-------------------------------------------------------------

You can use the Makefile for ./test01 as the starting point for your own
Makefile. Your Makefile needs to pass the appropriate flags to your compiler.

 o Make sure that the header installation directory is in your include path.
   The default header installation directory is /usr/local/include/.

 o GluCat uses preprocessor defines to control header files.
   See "To Configure" in the ./INSTALL file for details of these preprocessor
   defines.


7. Helping to improve the software
----------------------------------

To request features, file bug reports or submit source code patches:

The fastest way to ask for help with GluCat or to submit patches is to send an
email to the project manager ( Paul Leopardi <[email protected]> ).

The SourceForge page http://sourceforge.net/projects/glucat/support also
provides project forums, project mailing lists and project trackers.

The GitHub project page at https://github.com/penguian/glucat provides a
convenient interface that allows you to fork the code and create pull requests.

If you are thinking of writing patches, please try to match the programming
style used in the relevant source files, and be aware of the coding standards
used, as listed below.


Coding standards
================

The headers are split into declarations and definitions. The software was
developed using the GNU g++ compiler, which does not implement the "export"
keyword. Separate compilation is possible, if you include both the declarations
and definitions in each compilation unit, but compilation is slow and the
resulting binary is large.

The code follows many, but not all of the guidelines in the
GNU C++ Standard Library Style Guidelines at
https://gcc.gnu.org/onlinedocs/libstdc++/manual/source_code_style.html
The code also follows much of Scott Meyers' advice from "Effective C++",
Second Edition.

Some code conventions are:
name_t: The name of a type, either global or local to a class.
Sentence_Case_T: The name of a type used as a template parameter.
Other_Sentence_Case: Other template parameters, including template template
parameters.
ALL_CAPS_WITH_UNDERSCORES: A global constant defined in <glucat/global.h>