Hypercomplex

A Python library for working with quaternions, octonions, sedenions, and beyond following the Cayley-Dickson construction of hypercomplex numbers.

The complex numbers may be viewed as an extension of the everyday real numbers. A complex number has two real-number coefficients, one multiplied by 1, the other multiplied by i.

In a similar way, a quaternion, which has 4 components, can be constructed by combining two complex numbers. Likewise, two quaternions can construct an octonion (8 components), and two octonions can construct a sedenion (16 components).

The method for this construction is known as the [Cayley-Dickson construction][2] and the resulting classes of numbers are types of [hypercomplex numbers][1]. There is no limit to the number of times you can repeat the Cayley-Dickson construction to create new types of hypercomplex numbers, doubling the number of components each time.

This Python 3 package allows the creation of number classes at any repetition level of Cayley-Dickson constructions, and has built-ins for the lower, named levels such as quaternion, octonion, and sedenion.

[![Hypercomplex numbers containment diagram][8]][8]

Installation

pip install hypercomplex

View on PyPI - View on GitHub

This package was built in Python 3.9.6 and has been tested to be compatible with python 3.6 through 3.10.

Basic Usage

from hypercomplex import Complex, Quaternion, Octonion, Voudon, cayley_dickson_construction

c = Complex(0, 7)
print(c)        # -> (0 7)
print(c == 7j)  # -> True

q = Quaternion(1.1, 2.2, 3.3, 4.4)
print(2 * q)  # -> (2.2 4.4 6.6 8.8)

print(Quaternion.e_matrix())  # -> e0  e1  e2  e3
                              #    e1 -e0  e3 -e2
                              #    e2 -e3 -e0  e1
                              #    e3  e2 -e1 -e0

o = Octonion(0, 0, 0, 0, 8, 8, 9, 9)
print(o + q)  # -> (1.1 2.2 3.3 4.4 8 8 9 9)

v = Voudon()
print(v == 0)  # -> True
print(len(v))  # -> 256

BeyondVoudon = cayley_dickson_construction(Voudon)
print(len(BeyondVoudon()))  # -> 512

For more snippets see the Thorough Usage Examples section below.

Package Contents

Three functions form the core of the package:

• reals(base) - Given a base type (float by default), generates a class that represents numbers with 1 hypercomplex dimension, i.e. real numbers. This class can then be extended into complex numbers and beyond with cayley_dickson_construction.

  Any usual math operations on instances of the class returned by reals behave as instances of base would but their type remains the reals class. By default they are printed with the g [format-spec][7] and surrounded by parentheses, e.g. (1), to remain consistent with the format of higher dimension hypercomplex numbers.

  Python's decimal.Decimal might be another likely choice for base.

  # reals example:
  from hypercomplex import reals
  from decimal import Decimal
  
  D = reals(Decimal)
  print(D(10) / 4)   # -> (2.5)
  print(D(3) * D(9)) # -> (27)
  

• cayley_dickson_construction(basis) (alias cd_construction) generates a new class of hypercomplex numbers with twice the dimension of the given basis, which must be another hypercomplex number class or class returned from reals. The new class of numbers is defined recursively on the basis according the [Cayley-Dickson construction][2]. Normal math operations may be done upon its instances and with instances of other numeric types.

  # cayley_dickson_construction example:
  from hypercomplex import *
  RealNum = reals()
  ComplexNum = cayley_dickson_construction(RealNum)
  QuaternionNum = cayley_dickson_construction(ComplexNum)
  
  q = QuaternionNum(1, 2, 3, 4)
  print(q)         # -> (1 2 3 4)
  print(1 / q)     # -> (0.0333333 -0.0666667 -0.1 -0.133333)
  print(q + 1+2j)  # -> (2 4 3 4)
  

• cayley_dickson_algebra(level, base) (alias cd_algebra) is a helper function that repeatedly applies cayley_dickson_construction to the given base type (float by default) level number of times. That is, cayley_dickson_algebra returns the class for the Cayley-Dickson algebra of hypercomplex numbers with 2**level dimensions.

  # cayley_dickson_algebra example:
  from hypercomplex import *
  OctonionNum = cayley_dickson_algebra(3)
  
  o = OctonionNum(8, 7, 6, 5, 4, 3, 2, 1)
  print(o)              # -> (8 7 6 5 4 3 2 1)
  print(2 * o)          # -> (16 14 12 10 8 6 4 2)
  print(o.conjugate())  # -> (8 -7 -6 -5 -4 -3 -2 -1)
  

For convenience, nine internal number types are already defined, built off of each other:

| Name | Aliases | Description | | ------------ | --------------------- | ----------------------------------------------------------------------------------------------------------------- | | Real | R, CD1, CD[0] | Real numbers with 1 hypercomplex dimension based on float. | | Complex | C, CD2, CD[1] | Complex numbers with 2 hypercomplex dimensions based on Real. | | Quaternion | Q, CD4, CD[2] | Quaternion numbers with 4 hypercomplex dimensions based on Complex. | | Octonion | O, CD8, CD[3] | Octonion numbers with 8 hypercomplex dimensions based on Quaternion. | | Sedenion | S, CD16, CD[4] | Sedenion numbers with 16 hypercomplex dimensions based on Octonion. | | Pathion | P, CD32, CD[5] | Pathion numbers with 32 hypercomplex dimensions based on Sedenion. | | Chingon | X, CD64, CD[6] | Chingon numbers with 64 hypercomplex dimensions based on Pathion. | | Routon | U, CD128, CD[7] | Routon numbers with 128 hypercomplex dimensions based on Chingon. | | Voudon | V, CD256, CD[8] | Voudon numbers with 256 hypercomplex dimensions based on Routon. |

# built-in types example:
from hypercomplex import *
print(Real(4))               # -> (4)
print(C(3-7j))               # -> (3 -7)
print(CD4(.1, -2.2, 3.3e3))  # -> (0.1 -2.2 3300 0)
print(CD[3](1, 0, 2, 0, 3))  # -> (1 0 2 0 3 0 0 0)

The names and letter-abbreviations were taken from [this image][3] ([mirror][4]) found in Micheal Carter's paper Visualization of the Cayley-Dickson Hypercomplex Numbers Up to the Chingons (64D), but they also may be known according to their [Latin naming conventions][6].

Thorough Usage Examples

This list follows examples.py exactly and documents nearly all the things you can do with the hypercomplex numbers created by this package.

Every example assumes the appropriate imports are already done, e.g. from hypercomplex import *.

1. Initialization can be done in various ways, including using Python's built in complex numbers. Unspecified coefficients become 0.

   print(R(-1.5))                        # -> (-1.5)
   print(C(2, 3))                        # -> (2 3)
   print(C(2 + 3j))                      # -> (2 3)
   print(Q(4, 5, 6, 7))                  # -> (4 5 6 7)
   print(Q(4 + 5j, C(6, 7), pair=True))  # -> (4 5 6 7)
   print(P())                            # -> (0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0 0)
   

2. Numbers can be added and subtracted. The result will be the type with more dimensions.

   print(Q(0, 1, 2, 2) + C(9, -1))                   # -> (9 0 2 2)
   print(100.1 - O(0, 0, 0, 0, 1.1, 2.2, 3.3, 4.4))  # -> (100.1 0 0 0 -1.1 -2.2 -3.3 -4.4)
   

3. Numbers can be multiplied. The result will be the type with more dimensions.

   print(10 * S(1, 2, 3))                    # -> (10 20 30 0 0 0 0 0 0 0 0 0 0 0 0 0)
   print(Q(1.5, 2.0) * O(0, -1))             # -> (2 -1.5 0 0 0 0 0 0)
   
   # notice quaternions are non-commutative
   print(Q(1, 2, 3, 4) * Q(1, 0, 0, 1))      # -> (-3 5 1 5)
   print(Q(1, 0, 0, 1) * Q(1, 2, 3, 4))      # -> (-3 -1 5 5)
   

4. Numbers can be divided and inverse gives the multiplicative inverse.

   print(100 / C(0, 2))                      # -> (0 -50)
   print(C(2, 2) / Q(1, 2, 3, 4))            # -> (0.2 -0.0666667 0.0666667 -0.466667)
   print(C(2, 2) * Q(1, 2, 3, 4).inverse())  # -> (0.2 -0.0666667 0.0666667 -0.466667)
   print(R(2).inverse(), 1 / R(2))           # -> (0.5) (0.5)
   

5. Numbers can be raised to integer powers, a shortcut for repeated multiplication or division.

   q = Q(0, 3, 4, 0)
   print(q**5)               # -> (0 1875 2500 0)
   print(q * q * q * q * q)  # -> (0 1875 2500 0)
   print(q**-1)              # -> (0 -0.12 -0.16 0)
   print(1 / q)              # -> (0 -0.12 -0.16 0)
   print(q**0)               # -> (1 0 0 0)
   

6. conjugate gives the conjugate of the number.

   print(R(9).conjugate())           # -> (9)
   print(C(9, 8).conjugate())        #