Clifford and Geometric Algebra with TensorFlow

# TFGA - TensorFlow Geometric Algebra

Python package for Geometric / Clifford Algebra with TensorFlow 2.

This project is a work in progress. Its API may change and the examples aren't polished yet.

Pull requests and suggestions either by opening an issue or by sending me an email are welcome.

## Installation

Install using pip: `pip install tfga`

Requirements:

• Python 3
• tensorflow 2
• numpy

## Basic usage

There are two ways to use this library. In both ways we first create a `GeometricAlgebra` instance given a metric. Then we can either work on `tf.Tensor` instances directly where the last axis is assumed to correspond to the algebra's blades.

```import tensorflow as tf
from tfga import GeometricAlgebra

# Create an algebra with 3 basis vectors given their metric.
# Contains geometric algebra operations.
ga = GeometricAlgebra(metric=[1, 1, 1])

# Create geometric algebra tf.Tensor for vector blades (ie. e_0 + e_1 + e_2).
# Represented as tf.Tensor with shape  (one value for each blade of the algebra).
# tf.Tensor: [0, 1, 1, 1, 0, 0, 0, 0]
ordinary_vector = ga.from_tensor_with_kind(tf.ones(3), kind="vector")

# 5 + 5 e_01 + 5 e_02 + 5 e_12
quaternion = ga.from_tensor_with_kind(tf.fill(dims=4, value=5), kind="even")

# 5 + 1 e_0 + 1 e_1 + 1 e_2 + 5 e_01 + 5 e_02 + 5 e_12
multivector = ordinary_vector + quaternion

# Inner product e_0 | (e_0 + e_1 + e_2) = 1
# ga.print is like print, but has extra formatting for geometric algebra tf.Tensor instances.
ga.print(ga.inner_prod(ga.e0, ordinary_vector))

# Exterior product e_0 ^ e_1 = e_01.
ga.print(ga.ext_prod(ga.e0, ga.e1))

# Grade reversal ~(5 + 5 e_01 + 5 e_02 + 5 e_12)
# = 5 + 5 e_10 + 5 e_20 + 5 e_21
# = 5 - 5 e_01 - 5 e_02 - 5 e_12
ga.print(ga.reversion(quaternion))

# tf.Tensor 5
ga.print(quaternion)

# tf.Tensor of shape : -5 (ie. reversed sign of e_01 component)

# tf.Tensor of shape  with only e_01 component equal to 5
```

Alternatively we can convert the geometric algebra `tf.Tensor` instance to `MultiVector` instances which wrap the operations and provide operator overrides for convenience. This can be done by using the `__call__` operator of the `GeometricAlgebra` instance.

```# Create geometric algebra tf.Tensor instances
a = ga.e123
b = ga.e1

# Wrap them as `MultiVector` instances
mv_a = ga(a)
mv_b = ga(b)

# Reversion ((~mv_a).tensor equivalent to ga.reversion(a))
print(~mv_a)

# Geometric / inner / exterior product
print(mv_a * mv_b)
print(mv_a | mv_b)
print(mv_a ^ mv_b)
```

## Keras layers

TFGA also provides Keras layers which provide layers similar to the existing ones but using multivectors instead. For example the `GeometricProductDense` layer is exactly the same as the `Dense` layer but uses multivector-valued weights and biases instead of scalar ones. The exact kind of multivector-type can be passed too. Example:

```import tensorflow as tf
from tfga import GeometricAlgebra
from tfga.layers import TensorToGeometric, GeometricToTensor, GeometricProductDense

# 4 basis vectors (e0^2=+1, e1^2=-1, e2^2=-1, e3^2=-1)
sta = GeometricAlgebra([1, -1, -1, -1])

# We want our dense layer to perform a matrix multiply
# with a matrix that has vector-valued entries.

# Create our input of shape [Batch, Units, BladeValues]
tensor = tf.ones([20, 6, 4])

# The matrix-multiply will perform vector * vector
# so our result will be scalar + bivector.
# Use the resulting blade type for the bias too which is
result_indices = tf.concat([
], axis=0)

sequence = tf.keras.Sequential([
# Converts the last axis to a dense multivector
# (so, 4 -> 16 (total number of blades in the algebra))
# Perform matrix multiply with vector-valued matrix
GeometricProductDense(
algebra=sta, units=8, # units is analagous to Keras' Dense layer
),
# Extract our wanted blade indices (last axis 16 -> 7 (1+6))
])

# Result will have shape [20, 8, 7]
result = sequence(tensor)
```

### Available layers

Class Description
`GeometricProductDense` Analagous to Keras' `Dense` with multivector-valued weights and biases. Each term in the matrix multiplication does the geometric product `x * w`.
`GeometricSandwichProductDense` Analagous to Keras' `Dense` with multivector-valued weights and biases. Each term in the matrix multiplication does the geometric product `w *x * ~w`.
`GeometricProductElementwise` Performs multivector-valued elementwise geometric product of the input units with a different weight for each unit.
`GeometricSandwichProductElementwise` Performs multivector-valued elementwise geometric sandwich product of the input units with a different weight for each unit.
`GeometricProductConv1D` Analagous to Keras' `Conv1D` with multivector-valued kernels and biases. Each term in the kernel multiplication does the geometric product `x * k`.
`TensorToGeometric` Converts from a `tf.Tensor` to the geometric algebra `tf.Tensor` with as many blades on the last axis as basis blades in the algebra where blade indices determine which basis blades the input's values belong to.
`GeometricToTensor` Converts from a geometric algebra `tf.Tensor` with as many blades on the last axis as basis blades in the algebra to a `tf.Tensor` where blade indices determine which basis blades we extract for the output.
`TensorWithKindToGeometric` Same as `TensorToGeometric` but using `BladeKind` (eg. `"bivector"`, `"even"`) instead of blade indices.
`GeometricToTensorWithKind` Same as `GeometricToTensor` but using `BladeKind` (eg. `"bivector"`, `"even"`) instead of blade indices.
`GeometricAlgebraExp` Calculates the exponential function of the input. Input must square to a scalar.

## Notebooks

Generic examples

Using Keras layers to estimate triangle area

Classical Electromagnetism using Geometric Algebra

Quantum Electrodynamics using Geometric Algebra

Projective Geometric Algebra

1D Multivector-valued Convolution Example

## Tests

Tests using Python's built-in `unittest` module are available in the `tests` directory. All tests can be run by executing `python -m unittest discover tests` from the root directory of the repository.

## Citing

See our Zenodo page. For citing all versions the following BibTeX can be used

``````@software{python_tfga,
author       = {Kahlow, Robin},
title        = {TensorFlow Geometric Algebra},
publisher    = {Zenodo},
doi          = {10.5281/zenodo.3902404},
url          = {https://doi.org/10.5281/zenodo.3902404}
}
``````

## Disclaimer

TensorFlow, the TensorFlow logo and any related marks are trademarks of Google Inc.

## Project details

This version 0.1.16 0.1.15 0.1.14 0.1.13 0.1.12 0.1.11 0.1.10 0.1.9 0.1.8 0.1.7 0.1.6 0.1.5 0.1.4 0.1.3 0.1.1 0.1