GATL is a C library for Euclidean, homogeneous/projective, Mikowski/spacetime, conformal, and arbitrary geometric algebras.

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.

GATL uses template meta-programming to implement the lazy evaluation strategy. This way, GATL is capable of performing some optimizations on the program at compile time. In other words, GATL is designed to automatically execute low-level algebraic manipulation in the procedures described by the users with geometric algebra operations, leading to more efficient programs.

Please, cite this book chapter if you use GATL in your research:

@InCollection{fernandes-SEMA-13-2021,
  title     = {Exploring lazy evaluation and compile-time simplifications for efficient geometric algebra computations},
  author    = {Fernandes, Leandro A. F.},
  chapter   = {6},
  pages     = {111--131},
  booktitle = {Systems, Patterns and Data Engineering with Geometric Calculi},
  editor    = {Xambó-Descamps, S.},
  volume    = {13},
  series    = {SEMA SIMAI Springer Series},
  publisher = {Springer, Cham},
  doi       = {https://doi.org/10.1007/978-3-030-74486-1_6},
  isbn      = {978-3-030-74485-4},
  e-isbn    = {978-3-030-74486-1},
  url       = {https://github.com/laffernandes/gatl},
  year      = {2021},
}

Let me know if you want to contribute to this project. Here you will find my contact information.

Contents:

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

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

Required tool:

• Your favorite C 17 compiler.

Optional tool:

• CMake to automate installation and to build and run examples and unit-tests.

GATL doesn't have any dependencies other than the C standard library.

GATL is a pure template library defined in the headers. Therefore, if you want to use GATL, you can use the header files right away. There is no binary library to link to and no configured header file.

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

git clone https://github.com/laffernandes/gatl.git <gatl-dir>

The directory <gatl-dir>/cpp/include must be in the include path of your program, i.e., you have to use the -I<gatl-dir>/cpp/include option flag while compiling your program. Alternatively, you can use CMake to copy GATL's header files to the common include directory in your system (e.g., /usr/local/include, in Linux) to avoid the use of the -I<gatl-dir>/cpp/include option flag. The basic steps for installing GATL using CMake look like this:

cd <gatl-dir>/cpp
mkdir build
cd build
cmake ..

If you are using CMake to handle builds of your program, then it is strongly recommended to use the commands above to install GATL. After installation CMake will find GATL using the command find_package(GATL) (see CMake documentation for details). In addition, you will be able to use the GATL_INCLUDE_DIRS variable in the CMakeList.txt file of your program while defining the include directories of your project or targets.

The basic steps for configuring and building GATL examples look like this:

cd <gatl-dir>/cpp/tools/example
mkdir build
cd build
cmake ..
cmake --build . --config Release

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

The executable files produced by the last command start with gatl_example_.

Unit-tests are under construction. Please, don't try to build them.

Here you find a brief description of the namespaces, macros, classes, functions, procedures, and operators available for the user. The detailed documentation is not ready yet.

According to GATL conventions, in the following definitions, lhs and rhs are informal shorthand for, respectively, the left-hand side and the right-hand side arguments of binary procedures. In addition, the mtr argument must be an instance of the metric_space<...> class, while all other arguments can be either an instances of the clifford_expression<...> class or other numerical types (e.g., double, float, int, or instances of third-party classes). Numerical types are automatically converted by GATL to scalar Clifford expression using the scalar function.

Contents:

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

Namespaces are declarative regions that provide scope to the names of the types, function, variables, etc., inside it. GATL defines the following namespaces.

The namespaces of specific geometric algebras (e.g., ga3e, ga3h, ga3m, and ga3c) already use the ga namespace. In addition, they overload all metric operations presented in the following section by setting the mtr argument according to their respective spaces.

All above-mentioned namespaces declare a nested detail namespace. This is the namespace where the magic happens. Don't touch it!

According to the GATL conventions, the root directory for the header files that you will include in your program is the gatl folder. Also, the header file for each namespace is its name followed by the .hpp extension. Putting both conventions together, we have gatl/ga.hpp, gatl/ga3e.hpp, gatl/ga3h.hpp, gatl/ga3m.hpp, gatl/ga3c.hpp, and so on.

Optionally, set the following macros before including GATL headers in your program to change some conventions of the library.

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

For the sake of simplicity, GATL provides the following set of class aliases and helper meta-functions to assist type definition. Nevertheless, it is strongly recommended to use the auto placeholder type specifier (please, refer to the C specification for details) whenever possible.

Here you find some useful meta-constants and functions to assist the implementation of your program.

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

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

The following tables present the C mathematical functions overloaded by GATL to accept Clifford expressions as input.

GATL includes a set of useful functions, procedures, and meta-functions to help developers to write their programs.

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

Classes and constants of signed geometric algebras of R^{p, q, r}.

Classes, constants, functions, and operations of Euclidean geometric algebras of Rⁿ. They are available in the following namespaces: ga1e, ga2e, ga3e, ga4e, and ga5e.

Classes, constants, functions, and operations of homogeneous/projective geometric algebras of R^d (n = d 1). They are available in the following namespaces: ga1h, ga2h, ga3h, and ga4h.

Classes, constants, functions, and operations of plane-based geometric algebras of R^d (n = d 1). They are available in the following namespaces: ga1p, ga2p, ga3p, and ga4p.

Classes, constants, functions, and operations of Mikowski/spacetime geometric algebras of R^d (n = d 2). They are available in the following namespaces: ga1m, ga2m, and ga3m.

Classes, constants, functions, and operations of conformal geometric algebras of R^d (n = d 2). They are available in the following namespaces: ga1c, ga2c, and ga3c.

Classes, constants, functions, and operations of general geometric algebras defined by the used. The are available by including gatl/ga.hpp and gatl/ga/model/general.hpp.

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.

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