KYOSU is an unified implementation of the complex, quaternions, octonions and more generally all \(\mathbb{R}\)-Cayley-Dickson algebras in an SIMD aware context provided by EVE

Note: If you are not interested in quite exotics features as quaternion or octonion, but only in real and complex KYOSU is still a library that provides a set of ~150 functions that can be used with real and complex in scalar or simd form with no abstraction penalty. The list of them can be seen below.

The Cayley-Dickson construction scheme defines a new algebra as a Cartesian product of an algebra with itself, with multiplication defined in a specific way (different from the componentwise multiplication) and an involution known as conjugation.

We currently only implement the Cayley-Dickson algebras based on the IEEE float and double representations of real numbers.

Kyosu proper usable objects are all in the namespace kyosu.

Cayley-Dickson algebras

These are algebras over the real numbers with an involution named conjugation. The product of an element by its conjugate is 'real' and its positive square root is a norm on the vector space defined by the algebra.

Starting from the real numbers (supported by type T float or double) we define:

complex numbers (dimension 2)
quaternion (dimension 4)
octonion (dimension 8)
and more generally for any integral power of 2: N, the cayley_dickson algebra of dimension N

Let \(\mathbb{K}\) be a Cayley-Dickson algebra of dimension N its elements can be mathematically written

\(\displaystyle z=\sum_0^{N-1} z_i\;e_i\)

where \(e_0=1\) and \((e_i)_{i>1}\) satisfy \(e_i^2 = -1\) and a proper multiplication table relating them.

Note: Up to octonions these \((e_i)_{i<8}\) have (non indicial) standard names, namely : i, j, k, l, li, lj, lk. And \(e_0\) is 1 and so is generally omitted.

In the documentation we will sometimes use the following notations:

\(|z|\) is the absolute value (or modulus) of \(z\), i.e. \(\sqrt{\sum_0^{N-1} |z_i|^2}\).
\(z_0\) is the real part of \(z\).
\(\underline{z}\) is the pure part of \(z\) i.e. \(\sum_1^{N-1} z_i\;e_i\).
If \(I_z\) denotes \(\pm\underline{z}/|\underline{z}|\) (with \(\pm\) chosen to be the sign of \(z_1\)), the polar form of \(z\) is \(\rho e^{\theta\;I_z} = \rho(\cos\theta + I_z\sin\theta)\), \( \rho\) being the norm of \(z\) and \(\theta\) its argument. (Note the similarity with complex numbers: it is easy to see that \(I_z^2=-1\)).

These datas with different dimensions can be freely mixed with the obvious semantic that if N <M an element of cayley_dickson<N> will be considered as having its components from N to M-1, null as an element of cayley_dickson<M>

Higher are the dimensions weirder are these algebras

real numbers is a commutative ordered field
complex is a commutative field with no multiplication-compatible order
quaternion is a non-commutative field
octonion is a non associative (but alternative) division algebra

The functions commutator (resp. associator) can be used to see if two (resp. three) Cayley-Dickson value commute (resp. associate).

Greater dimensions are not even alternative but keep power-associativity which allows to define most elementary functions.

Note: Let us recall that alternative means that every subalgrebra generated by two elements is associative.

What does this implementation provide

All operators and functions implemented can receive a mix of scalar or simd of cayley-dickson and reals of various dimensionnality and are defined in the namespace kyosu.

Of course the algebra operation +, -, * and / are provided, but as \ is not an usable C++ character as an operator, the left division a \ b is provided as the call ldiv(a,b).

Constructors

complex and quaternion can be constructed using callables facilities complex and quaternion.

complex can also be constructed from their polar representation
quaternion from various parametrizations of \(\mathbb{R}^4\) or from \(\mathbb{R}^3\) rotations:


angle and axis	from_angle_axis	to_angle_axis
cylindrical	from_cylindrical	to_cylindrical
cylindrospherical	from_cylindrospherical	to_cylindrospherical
euler	from_euler	to_euler
multipolar	from_multipolar	to_multipolar
rotation matrix	from_rotation_matrix	to_rotation_matrix
semipolar	from_semipolar	to_semipolar
spherical	from_spherical	to_spherical
two vectors	align

The third column references to the corresponding to_xxx version that gives back the chosen representation from a quaternion input.

TODO cayley_dickson<N> construction by a function.

Operators

Operators (as said before) +, -, * and / can be used in infix form and can mix cayley-dickson values of different dimensionalities. Of course the biggest dimensionlity is recovered in the output.

Prefix forms are also provided as add, sub, multiply and div. Also plus and minus for unary versions.

The left division sometimes necessary if the dimensionality is greater than 2 is given as ldiv.

The left multiplication to the left by i or -i (i*i=-1) can be done calling respectively muli and mulmi

Functions

Most KYOSU callables are usable with all cayley_dickson types. The exceptions mainly being rotation related quaternion usage.

Warning: EVE callables that correspond to mathematical functions that are only defined on a proper part of the real axis as, for example, acos DOES NOT ever provide the same result if called in EVE or KYOSU context.

eve::acos(2.0) wil returns a NaN value, but kyosu::acos(2.0) will return the pure imaginary complex number \(i\;\log(2+\sqrt{3})\)

All these kinds of functions called with a floating value in the kyosu namespace will return a complex value.

callables usable with all cayley_dickson types

Most EVE arithmetic and math functions are provided. In particular, real analytic functions of one variable can be quite naturally extended using the polar form described above from a mere complex implementation.


abs	acos	acosh	acospi	acot
acotpi	atanpi	acoth	arg	acsc
acscpi	acsch	asec	asecpi	asech
asin	asinpi	asinh	atan	atanh
average	beta	ceil	chi	conj
cos
cosh	cospi	cot	cotpi	coth
convert	csc	cscpi	csch	dec
deta	digamma	dist	dot	erf
erfcx	erfi	eta	exp	exp10
exp2	exp_i	exp_ipi	expm1	expmx2
expx2	faddeeva	fam	floor	fma
fms	fnma	fnms	frac	fsm
from_polar	horner	hypot	if_else	inc
ipart	is_denormal	is_equal	is_eqz	is_finite
is_infinite	is_imag	is_nan	is_nez	is_not_denormal
is_not_equal	is_not_finite	is_not_infinite	is_not_nan	is_not_real
is_pure	is_real	is_unitary	jpart	kpart
ldiv	lambda	lbeta	lerp	lipart
ljpart	lkpart	log	log2	lpart
lipart	ljpart	lkpart	lpnorm	lrising_factorial
manhattan	minus	nearest	oneminus	pow
pow1p	pow_abs	powm1	proj	pure
radinpi	real	rec	reldist	reverse_horner

Bessel functions

They deserve a separate list to avoid verbosity:
- cylindrical Bessel functions: cyl_bessel_xxx are all defined for xxx being j0, j1, jn, y0, y1, yn, i0, i1, in, h1_0, h1_1, h1n, h2_0, h2_1, h2n, k1, k0, kn.
- spherical Bessel functions: sph_bessel_xxx are all defined for xxx being j0, j1, jn, y0, y1, yn, i1_0, i1_1, i1n, i2_0, i2_1, i2n, h1_0, h1_1, h1n, h2_0, h2_1 h2n, k1, k0, kn.
Callables usable with quaternion, complex and real only

These functions are related to \(\mathbb{R}^3\) rotations


rot_angle	rot_axis	rotate_vec

Constant i, j, k and cinf are defined.
- i(as<Z>()) returns at least a complex of the same underlying type as Z or a value of the Z type;
- j(as<Z>()) and k(as<Z>()) return a least a quaternion of the same underlying type as Z or a value of the Z type;
- cinf(as<Z>()) returns at least a complex with nan real part and inf imaginary part, that can be roughly taken as a complex-infinity, in the sense that abs is infinite and arg is undefinite (nan), or a value of the Z type.

	kyosu v0.1.0 Complex Without Complexes