TbGAL: Tensor-Based Geometric Algebra Library

TbGAL is a C++/Python library for Euclidean, homogeneous/projective, Mikowski/spacetime, conformal, and arbitrary geometric algebras with assuming (p, q) metric signatures.

Geometric algebra is a powerful mathematical system encompassing many mathematical concepts (e.g., complex numbers, quaternions algebra, Grassmann-Cayley algebra, and Plücker coordinates) under the same framework. Geometric algebra is mainly based on the algebraic system called Clifford algebra, but with a strong emphasis on geometric interpretation. In geometric algebra, subspaces are treated as primitives for computation. As such, it is an appropriate mathematical tool for modeling and solving geometric problems in physics, chemistry, engineering, and computer science.

TbGAL represents blades (and versors) in their decomposed state as the outer product (and geometric product), rather than using their representation as a weighted summation of basis blades in ⋀ℝⁿ. The main advantage of the factorized approach is that it is able to compute geometric algebra operations in higher dimensions, i.e., assume multivectors space ⋀ℝⁿ with n > 256. In terms of memory, TbGAL stores only 1 + n² coefficients per blade or versor in worst case, while operations have maximum complexity of O(n³).

Please cite our Advances in Applied Clifford Algebras paper if you use this code in your research. The paper presents a complete description of the library:

@Article{sousa_fernandes-aaca-30(2)-2020,
  author  = {Sousa, Eduardo V. and Fernandes, Leandro A. F.},
  title   = {{TbGAL}: a tensor-based library for geometric algebra},
  journal = {Advances in Applied Clifford Algebras},
  year    = {2020},
  volume  = {30},
  number  = {2},
  pages   = {75},
  doi     = {https://doi.org/10.1007/s00006-020-1053-1},
  url     = {https://github.com/Prograf-UFF/TbGAL},
}

Please, let Eduardo Vera Sousa (http://www.ic.uff.br/~eduardovera) and Leandro A. F. Fernandes (http://www.ic.uff.br/~laffernandes) know if you want to contribute to this project. Also, do not hesitate to contact them if you encounter any problems.

Contents:

1. Requirements
2. How to Build and Install TbGAL
3. Compiling and Running Examples
4. Compiling and Running Unit Tests
5. Documentation
6. Related Project
7. License

1. Requirements

Make sure that you have the following tools before attempting to use TbGAL.

Required tools:

• Your favorite C++17 compiler.
• CMake (version >= 3.14) to automate installation and to build and run examples.

Required C++ library:

• Eigen (version >= 3) to evaluate basic matrix algebra routines.

Required tools, if you want to use TbGAL with Python:

• Python 2 or 3 interpreter, if you want to build and use TbGAL with Python.

Required Python packages and C++ libraries, if you want to use TbGAL with Python:

• NumPy, the fundamental package for scientific computing with Python.
• Boost.Python (version >= 1.56), a C++ library which enables seamless interoperability between C++ and the Python programming language.
• Boost.NumPy, a C++ library that extends Boost.Python to NumPy.

Required C++ libraries, if you want to run unit tests:

• GATL is another C++ library for geometric algebra.
• Google Test is a unit testing library for the C++ programming language, based on the xUnit architecture.

Optional tool to use TbGAL with Python:

• Virtual enviroment to create an isolated workspace for a Python application.

2. How to Build and Install TbGAL

Use the git clone command to download the project, where <tbgal-dir> must be replaced by the directory in which you want to place TbGAL's source code, or remove <tbgal-dir> from the command line to download the project to the ./TbGAL directory:

git clone https://github.com/Prograf-UFF/TbGAL.git <tbgal-dir>

TbGAL/C++ is a pure template library. Therefore, there is no binary library to link to, but you have to install the header files. Optionally, you can build and install the TbGAL/Python front-end.

Use CMake to copy TbGAL's header files to the common include directory in your system (e.g., /usr/local/include, in Linux). The basic steps for installing TbGAL/C++ using CMake look like this in Linux:

cd <tbgal-dir>
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..

Notice that you may use the -G <generator-name> option of CMake's command-line tool to choose the build system (e.g., Unix makefiles, Visual Studio, etc.). Please, refer to CMake's Help for a complete description of how to use the CMake's command-line tool.

After installation, CMake will find TbGAL/C++ using the command find_package(TbGAL) (see CMake documentation for details). In addition, you will be able to use the TbGAL_INCLUDE_DIRS variable in the CMakeList.txt file of your program while defining the include directories of your C++ project or targets.

TbGAL/Python is a back-end to access TbGAL/C++ from a Python environment. In this case, you have to build and install the TbGAL/Python modules using the commands presented bellow:

cmake --build . --config Release --parallel 8 --target install

It is important to emphasize that both Python 2 and 3 are supported. Please, refer to CMake's documentation for details about how CMake finds the Python interpreter, compiler, and development environment.

Finally, add <cmake-install-prefix>/lib/tbgal/python/<python-version> to the the PYTHONPATH environment variable. The <cmake-install-prefix> placeholder usually is /usr/local on Linux, and C:/Program Files/TbGAL or C:/Program Files (x86)/TbGAL on Windows. But it may change according to what was set in CMake. The <python-version> placeholder is the version of the Python interpreter found by CMake.

Set the PYTHONPATH variable by calling following command in Linux:

export PYTHONPATH="$PYTHONPATH:<cmake-install-prefix>/lib/tbgal/python/<python-version>"

But this action is not permanent. The new value of PYTHONPATH will be lost as soon as you close the terminal. A possible solution to make an environment variable persistent for a user's environment is to export the variable from the user's profile script:

1. Open the current user's profile (the ~/.bash_profile file) into a text editor.
2. Add the export command for the PYTHONPATH environment variable at the end of this file.
3. Save your changes.

Execute the following steps to set the PYTHONPATH in Windows:

1. From the Windows Explorer, right click the Computer icon.
2. Choose Properties from the context menu.
3. Click the Advanced system settings link.
4. Click Environment Variables. In the section System Variables, find the PYTHONPATH environment variable and select it. Click Edit. If the PYTHONPATH environment variable does not exist, click New.
5. In the Edit System Variable (or New System Variable) window, specify the value of the PYTHONPATH environment variable to include "<cmake-install-prefix>/lib/tbgal/python/<python-version>". Click OK. Close all remaining windows by clicking OK.
6. Reopen yout Python environment.

3. Compiling and Running Examples

The basic steps for configuring and building the C++ example of the TbGAL look like this:

cd <tbgal-dir>/cpp/example
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --config Release --parallel 8

Call the executables files placed at <tbgal-dir>/cpp/example/build on Linux and at <tbgal-dir>\cpp\example\build\Release on Windows.

Recall that <tbgal-dir> is the directory in which you placed TbGAL's source code.

Use the files in the <tbgal-dir>/cpp/example directory as examples of how to use TbGAL in your C++ program. For instance, after installation of the TbGAL library, CMake will find TbGAL using the command find_package(TbGAL) (see the <tbgal-dir>/cpp/example/CMakeLists.txt file and the CMake documentation for details). Also, you will be able to use the TbGAL_INCLUDE_DIRS variable in the CMakeList.txt file of your program while defining the include directories of your C++ project or targets. In your source code, you have to use the #include <tbgal/using_Eigen.hpp> directive to instrument the library to perform matrix computations using Eigen and the #include <tbgal/assuming_[some-model].hpp> directive to assume some pre-defined model of geometry.

Similarly, you will find examples of how to use the TbGAL library with Python in the <tbgal-dir>/python/example/py2 and <tbgal-dir>/python/example/py3 directories.

4. Compiling and Running Unit Tests

The basic steps for configuring and building the C++ unit tests of the TbGAL look like this:

cd <tbgal-dir>/cpp/test
mkdir build
cd build
cmake -DCMAKE_BUILD_TYPE=Release ..
cmake --build . --parallel 8

The configuration process will donwload, build, and install Google Test automatically. GATL must be installed by you first. If successfull, call the test target to run all tests:

cmake --build . --target test

5. Documentation

Here you find a brief description of the namespaces, macros, classes, functions, procedures, and operators available for the user. All methods are available with C++ and most of them with Python. The detailed documentation is not ready yet.

Contents:

• Namespaces
• Macros
• Classes and Data Types
• Utilities Constants and Functions
• Products and Basic Operations
• Overloaded Operators
• Tools
• Algebra-Specific Declarations
  • Signed
  • Euclidean
  • Homogeneous/Projective
  • Mikowski/Spacetime
  • Conformal

Namespaces

In C++, namespaces are declarative regions that provide scope to the names of the types, function, variables, etc., inside it. TbGAL defines the following namespaces.

The tbgal namespace also declares a nested detail namespace. This is the namespace where the magic happens. Don't touch it!

According to the TbGAL conventions, the root directory for the header files that you will include in your program is the tbgal folder. The core operations may be implemented by TbGAL using different libraries, so you have to indicate the one that will be used. So far, Eigen is the only one available. It can be indicated by including the header file tbgal/using_Eigen.hpp. Also, the header file for each above-mentioned namespace is its name preceded by assuming_ and followed by the .hpp extension. Putting both conventions together, we have tbgal/assuming_Euclidean3.hpp, tbgal/assuming_Homogeneous3.hpp, tbgal/assuming_Minkowski3.hpp, tbgal/assuming_Conformal3.hpp, and so on.

As an example, if you want to use the Eigen-based implementation of TbGAL with conformal geometric algebra of R³ then you have to put the following instructions among the first lines of your source code:

#include <tbgal/using_Eigen.hpp>
#include <tbgal/assuming_Conformal3.hpp>

using namespace tbgal;
using namespace tbgal::Conformal3;

In Python, one only have to import the content of the submodule related to the model of geometry:

from tbgal.conformal3 import *

Macros

Optionally, set the following macros before including TbGAL headers in your program to change some conventions of the library. They are not available in Python.

Classes and Data Types

The following basic data types are defined in order to assign a meaning to conventional types, like double, int, and so on.

The following classes correspond to the most important structures of TbGAL.

The D, P, Q, MaxD, and MaxN template arguments of the classes implementing the MetricSpaceType concept may be set to non-negative integer values in compilation time. As a result, the dimensionality of the vector space will be constant at runtime. The other option is to set them to Dynamic if one plans to change the dimensionality of the vector space at runtime. You don't have to worry about that if you are using a model of geometry defined in one of the tbgal/assuming_[whatever].hpp headers.

The explicit use of C++ templates while implementing a solution may be overwhelming. For the sake of simplicity, it is strongly recommended to use the auto placeholder type specifier (please, refer to the C++ specification for details) whenever possible.

Utilities Constants and Functions

Here you find some useful functions to assist the implementation of your program.

Products and Basic Operations

The following tables present a set of basic products and operations from geometric algebra.

Overloaded Operators

TbGAL overload some C++ operators to make the writing of source code closer to the writing of mathematical expressions with geometric algebra.

It is important to notice that the precedence and associativity of C++ operators are different than the one assumed in mathematical functions. For instance, one would expect that the outer/wedge product ^ would be evaluated before the addition operation in the following expression a + b ^ c, because product precedes addition in math. However, in C++ the addition operator (+) precedes the bitwise XOR operator (^), leading to possible mistakes while implementing mathematical procedures (please, refer to the C++ specification for details). As a result, the resulting expression in this example would be (a + b) ^ c. The use of parenthesis is strongly recommended in order to avoid those mistakes. By rewriting the example, a + (b ^ c) will guarantee the expected behavior.

Tools

TbGAL includes a set of useful functions to help developers to write their programs.

Algebra-Specific Declarations

In the following sub-section, you find declarations that are specific of the respective geometric algebra.

Signed

Classes and constants of signed geometric algebras of R^{p, q}. They are available in the following namespace: tbgal::SignedPQ.

Euclidean

Classes, constants, functions, and operations of Euclidean geometric algebras of Rⁿ. They are available in the following namespaces: tbgal::Euclidean1, tbgal::Euclidean2, tbgal::Euclidean3, and tbgal::EuclideanD.

Homogeneous/Projective

Classes, constants, functions, and operations of homogeneous/projective geometric algebras of R^d (n = d + 1). They are available in the following namespaces: tbgal::Homogeneous1, tbgal::Homogeneous2, tbgal::Homogeneous3, and tbgal::HomogeneousD.

Mikowski/Spacetime

Classes, constants, functions, and operations of Mikowski/spacetime geometric algebras of R^d (n = d + 2). They are available in the following namespaces: tbgal::Minkowski1, tbgal::Minkowski2, tbgal::Minkowski3, and tbgal::MinkowskiD.

Conformal

Classes, constants, functions, and operations of conformal geometric algebras of R^d (n = d + 2). They are available in the following namespaces: tbgal::Conformal1, tbgal::Conformal2, tbgal::Conformal3, and tbgal::ConformalD.

6. Related Project

Please, visit the GitHub repository of the ga-benchmark project for a benchmark comparing the most popular libraries, library generators, and code optimizers for geometric algebra.

7. License

This software is licensed under the GNU General Public License v3.0. See the LICENSE file for details.