README for GluCat 0.13.0 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++.</double>

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

• Wikipedia: Geometric algebra
  

• Alan Macdonald, A Survey of Geometric Algebra and Geometric Calculus
  

• Alan Macdonald, Linear and Geometric Algebra, 2011.
  

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

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.md file in the
same directory that contains this README.md 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.md 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 python3

PyClical is designed to be used within a Python environment. You will usually
need to run a Python IDE or interpreter, such as IDLE, ipython3 or python3. The
following instructions use the standard python3 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
% python3 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 clifford_demo.py,
pyclical_demo.py, plotting_demo.py, plotting_demo_dialog.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 clifford_demo.py, pyclical_demo.py, or sqrt_log_demo.py, use the
following commands:

% cd /path/to/my/demos
% python3 $DEMO.py

where $DEMO is one of clifford_demo, pyclical_demo or sqrt_log_demo.

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

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

To run plotting_demo.py, run ipython3 --pylab and enter the following command
at the IPython prompt:

In [1]: %run plotting_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 ipython3 and enter the following command at the ipython3 prompt:

In [1]: %run plotting_demo_mayavi

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.

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

% cd /path/to/my/demos
% jupyter 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 ./test17 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 "glucat/glucat_imp.h"
 #include "test/tuning.h"

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

The second line includes "glucat/glucat_imp.h", a convenience header that
includes all the GluCat definitions.

The third line includes "test/tuning.h", a convenience header that defines
specific instances of tuning<> for use as Tune_P, the tuning policy class.
This class is used as a template parameter in in the template classes
framed_multi<> and matrix_multi<>. The tuning<> template class is defined in
"glucat/tuning.h". See this file and "test/tuning.h" for examples of values
that you can use for the template parameters of tuning<> for use as Tune_P.

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/pdf and /usr/local/doc/glucat/api/html
respectively.

5.1 Truncation

Because the transform from framed_multi<> to matrix_multi<> may involve many
multiplications and additions, rounding errors can accumulate and result in one
or more non-zero matrix entries where exact arithmetic would have yielded zero.
Similarly, the inverse transform from matrix_multi<> to framed_multi<> can
result in small non-zero terms which would be zero in exact arithmetic.

The clifford_algebra::truncated() member function returns the multivector
*this with all relatively small terms set to zero. The function compares the
absolute value of each term to the largest absolute value of any term, and sets
to zero any term whose relative absolute value is smaller than the given limit.
The default limit is std::numeric_limits<Scalar_T>::epsilon(). The truncated()
matrix function operates similarly to set relatively small matrix entries to zero.

5.1.1 Printing uses truncation

Printing using operator<<() uses truncation to suppress the printing of
relatively small terms. Depending on the floating point format used, the
truncation used is calculated using the floating point precision as follows.

scientific:
truncation = 10 ** -(precision+1)

fixed:
truncation = (10 ** -precision) / max_abs
This has the effect of deleting all terms whose absolute value is less than
10 ** -precision.

hexfloat:
truncation = default_truncation

default:
truncation = 10 ** -precision

See (e.g.) https://www.cplusplus.com/reference/ios/ios_base/precision/
and see ./test17 for examples.

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.

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

• GluCat uses preprocessor defines to control header files.
  See "To Configure" in the ./INSTALL.md 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 < paul.leopardi@gmail.com > ).

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