Geometric Algebra Fulcrum Library (GA-FuL) - Documentation

Author: Ahmad H. Eid Email: ga.computing.eg@gmail.com

🇩🇪 Deutsche Version

Table of Contents

1. Introduction
2. Installation and Getting Started
3. Architecture and Design
4. Design Principles
5. API Reference
6. Usage Examples
7. Project Structure
8. Citation

Introduction

The Geometric Algebra Fulcrum Library (GA-FuL) is a unified, generic C# library for geometric algebra computations using any kind of scalars (floating point, rational, symbolic, etc.). GA-FuL can be used for prototyping geometric algorithms based on the powerful mathematics of geometric algebra. The GA-FuL codebase enables numeric computations, symbolic manipulations, and optimized code generation.

What is Geometric Algebra?

Geometric Algebra (GA) is a powerful mathematical language that unifies many algebraic tools under the same framework of mathematical operations. Such tools include, for example:

• Real vectors
• Complex numbers
• Quaternions
• Octonions
• Spinors
• Matrices
• and many more

The most important feature of GA is, however, that it unifies the geometric reasoning process among many seemingly diverse application domains.

Why the Name “Geometric Algebra Fulcrum”?

The name has two levels of meaning:

1. Mathematical Fulcrum: Geometric Algebra acts as a mathematical lever for geometric thinking across scientific and engineering domains. We can use this “Geometric Algebra Fulcrum” to seamlessly balance the abstract ideal needs of geometric reasoning with the concrete tools of algebraic manipulation under a unifying mathematical framework.

2. Computational Fulcrum: There is a need for software tools that act as a pivot point, i.e. a Fulcrum, for prototyping and implementing several kinds of computations on GA’s multivectors. GA-FuL is intended to play the role of a Computational Fulcrum for prototyping algorithms and implementing software based on Geometric Algebra.

Key Features

1. Generic Scalar Abstraction

• Support for various scalar representations:
  • Floating point numbers (32-bit, 64-bit)
  • Arbitrary precision decimals
  • Rational numbers
  • Symbolic expressions (Mathematica, SymPy, etc.)
  • Multi-dimensional arrays and tensors
  • Sampled signals for signal processing

2. Memory-Efficient Sparse Multivectors

• Optimized data structures for sparse multivectors in high-dimensional GAs
• Support for spaces up to 64 dimensions (optimized)
• Support for arbitrary dimensions (generic)

3. Metaprogramming Capabilities

• Automatic code generation from GA expressions
• Optimization through:
  • Constant propagation
  • Common subexpression elimination
  • Symbolic simplification
  • Genetic programming for further optimization
• Target languages:
  • C/C++
  • C#
  • Java
  • JavaScript
  • Python
  • MATLAB
  • CUDA (planned)

4. Layered System Design

• Algebra Layer: Fundamental GA operations and data structures
• Modeling Layer: Geometric modeling and visualization
• Metaprogramming Layer: Code generation and optimization
• System Utilities Layer: Support services for text, code, and web graphics

5. Data-Oriented Programming (DOP)

• Separation of behavior and data
• Use of generic data structures
• Immutable data
• Separation of data representation and data schema

Application Domains

GA-FuL can be used in various domains:

• Computer Graphics and Visualization
• Robotics and Motion Control
• Physics Simulations
• Signal and Image Processing
• Machine Learning and AI
• Computer Vision
• Mathematical Modeling
• Code Generation for High-Performance Computing

Project Components

The GA-FuL project consists of several modules:

For more details, see the Project Structure Documentation.

System Requirements

• .NET 8.0 or higher
• C# 12 (latest)
• Optional:
  • Wolfram Mathematica (for symbolic computations)
  • MATLAB (for MATLAB integration)

Testing & Quality

Status (2025-10-17): 🎉 97.91% Tests Passing! 🎉

• Total Tests: 1,153
• Passing: 1,129 (97.91%) ✅
• Failing: 0
• Skipped: 24
• Code Coverage: ~50%

Test Suites: | Component | Tests | Pass Rate | |———–|——-|———–| | Algebra Operations | 133 | 100% 🎯 | | Linear Maps | 121 | 100% | | AutoDiff | 69 | 100% | | Modeling (CGa/PGA) | 507 | 91% | | Utilities | 295 | 99.7% |

See ISSUES_TO_FIX.md for details.

Getting Started

For a quick introduction to GA-FuL, please read the Getting Started Guide.

A simple example:

using GeometricAlgebraFulcrumLib.Modeling.Geometry.CGa.Float64;

// Create a CGA space for 3D geometry
var cga = CGaFloat64GeometricSpace5D.Instance;

// Encode points as CGA null vectors
var point1 = cga.Encode.IpnsRound.Point(3.5, 4.3, 2.6);
var point2 = cga.Encode.IpnsRound.Point(-2.1, 3.4, 5.0);

// Perform GA operations (outer product)
var result = point1.Op(point2);

For more examples, see the Examples Documentation.

Citation

If you use GA-FuL in your research or project, please cite the following article:

Eid, A.H.; Montoya, F.G. “Developing GA-FuL: A Generic Wide-Purpose Library for Computing with Geometric Algebra.” Mathematics 2024, 12, 2272. DOI: 10.3390/math12142272

@Article{Eid2024,
  author    = {Eid, Ahmad Hosny and Montoya, Francisco G.},
  journal   = {Mathematics},
  title     = {Developing GA-FuL: A Generic Wide-Purpose Library for Computing with Geometric Algebra},
  year      = {2024},
  issn      = {2227-7390},
  month     = jul,
  number    = {14},
  pages     = {2272},
  volume    = {12},
  doi       = {10.3390/math12142272},
  publisher = {MDPI AG},
}

License

For more information about the license, see the LICENSE file in the project’s root directory.

Resources

• Main Repository: GA-FuL on GitHub
• Publication: MDPI Mathematics - GA-FuL Article
• Predecessor Project: GMac

Contact

For questions, suggestions, or collaboration, please contact:

Ahmad H. Eid Email: ga.computing.eg@gmail.com

Documentation Structure

This documentation is divided into several thematic sections:

• Getting Started - Installation and first steps
• Architecture - System design and component layers
• Design Principles - Core design intentions and DOP principles
• Examples - Comprehensive code examples
• API Reference - Detailed API documentation
• Project Structure - Module organization and dependencies

Language Options:

• English: .md files
• Deutsch: .de.md files

Note: This documentation provides comprehensive information about GA-FuL. Use the table of contents to navigate to desired topics.