Tree [29c2e4] master release_0_7_4 /
History



File Date Author Commit
admin 2014-12-24 Paul Leopardi Paul Leopardi [48b23a] Make admin shell files executable.
gfft_test 2014-04-27 Paul Leopardi Paul Leopardi [ecffa2] Implement scalar promotion and demotion, and us...
glucat 2014-12-24 Paul Leopardi Paul Leopardi [e869a4] Use static_cast<>.
products 2014-02-23 Paul Leopardi Paul Leopardi [fdac0b] Do not trigger the "unused local typedefs" warning
pyclical 2014-12-24 Paul Leopardi Paul Leopardi [4f2ae7] In PyClical sqrt_log_demo, do not print the val...
squaring 2014-02-23 Paul Leopardi Paul Leopardi [fdac0b] Do not trigger the "unused local typedefs" warning
test 2012-05-09 Paul C. Leopardi Paul C. Leopardi [7a1bfc] Common definitions to support timing tests.
test00 2014-02-23 Paul Leopardi Paul Leopardi [fdac0b] Do not trigger the "unused local typedefs" warning
test01 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test02 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test03 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test04 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test05 2012-05-11 Paul C. Leopardi Paul C. Leopardi [db8430] Change operator|(lhs,rhs) to operator||(lhs,rhs),
test06 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test07 2014-12-24 Paul Leopardi Paul Leopardi [be0183] Use scalar_t with scalar constants.
test08 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test09 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test10 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test11 2014-12-24 Paul Leopardi Paul Leopardi [c3c816] Use tuning parameter function_precision but not...
test12 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test13 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test14 2009-12-21 Paul C. Leopardi Paul C. Leopardi [f14505] For operator!= (const Scalar_T& scr, const Mult...
test15 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test16 2009-07-27 Paul C. Leopardi Paul C. Leopardi [b6a5d4] Files created automatically by automake.
test_runtime 2014-12-24 Paul Leopardi Paul Leopardi [b30a70] Update test results for GluCat 0.7.4.
transforms 2014-04-27 Paul Leopardi Paul Leopardi [ecffa2] Implement scalar promotion and demotion, and us...
.cvsignore 2002-01-12 Paul C. Leopardi Paul C. Leopardi [5585eb] Add glucat to cvs
AUTHORS 2014-12-24 Paul Leopardi Paul Leopardi [e5c504] Update GluCat and PyClical versions to 0.7.4.
COPYING 2007-08-22 Paul C. Leopardi Paul C. Leopardi [349def] Relicense under LGPLv3.
ChangeLog 2014-12-26 Paul Leopardi Paul Leopardi [29c2e4] Update ChangeLog for version 0.7.4.
Doxyfile 2014-12-24 Paul Leopardi Paul Leopardi [e5c504] Update GluCat and PyClical versions to 0.7.4.
INSTALL 2014-12-24 Paul Leopardi Paul Leopardi [e0c92c] Update INSTALL, NEWS, README and TODO for GluCa...
Makefile.am 2010-05-27 Paul C. Leopardi Paul C. Leopardi [ffbd20] Append pyclical to SUBDIRS (and therefor build ...
Makefile.dist 2002-08-13 Paul C. Leopardi Paul C. Leopardi [506325] Update to automake 1.6.3 and autoconf 2.52
NEWS 2014-12-24 Paul Leopardi Paul Leopardi [e0c92c] Update INSTALL, NEWS, README and TODO for GluCa...
README 2014-12-24 Paul Leopardi Paul Leopardi [e0c92c] Update INSTALL, NEWS, README and TODO for GluCa...
TODO 2014-12-24 Paul Leopardi Paul Leopardi [e0c92c] Update INSTALL, NEWS, README and TODO for GluCa...
acinclude.m4 2014-03-27 Paul Leopardi Paul Leopardi [2cbcd7] Use [] quotes for DEFUN names to stop autorecon...
config.h.in 2012-07-14 Paul C. Leopardi Paul C. Leopardi [fe3d88] Generated file.
configure.files 2002-08-14 Paul C. Leopardi Paul C. Leopardi [dc8396] (Re)add files possibly needed by autoconf, auto...
configure.in 2014-05-07 Paul Leopardi Paul Leopardi [1f4bf4] Add GLUCAT_MSG_WARN_DEPRECATED for deprecated o...
configure.in.in 2014-05-07 Paul Leopardi Paul Leopardi [1f4bf4] Add GLUCAT_MSG_WARN_DEPRECATED for deprecated o...
glucat.lsm 2014-12-24 Paul Leopardi Paul Leopardi [e5c504] Update GluCat and PyClical versions to 0.7.4.
stamp-h1 2002-08-14 Paul C. Leopardi Paul C. Leopardi [dc8396] (Re)add files possibly needed by autoconf, auto...
subdirs 2010-05-27 Paul C. Leopardi Paul C. Leopardi [5b61ff] New in CVS: Include only those directories for ...

Read Me

README for GluCat 0.7.4 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.

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 tutorial.Once you have run the
PyClical tutorial, 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 CVS version:
http://sourceforge.net/scm/?type=cvs&group_id=37255


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,
./CVS, ./doc, ./gfft_test, ./glucat, ./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 Python source code for the
PyClical demos and tutorials, and sample demo output.

The ./admin directory is part of the autotools infrastructure for building
GluCat, and should normally be left unchanged.

The ./CVS directory is used by the CVS version control system. There are also
CVS directories in each of the other directories. These should also be left
unchanged.

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

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
follwing instuctions 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. For example, assuming
you are using the Bash shell on Linux, use the following commands:

% cp 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"
 typedef glucat::tuning<> Tune_P;
 #include "glucat/glucat_imp.h"

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

The second line defines Tune_P, the tuning policy class. This class may be
included as a template parameter in future versions, but for now, 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>.

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).


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 installation directory is in your include path.
   The default 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 <leopardi@users.sourceforge.net> ).

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

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
http://gcc.gnu.org/onlinedocs/libstdc++/17_intro/C++STYLE
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>