Kyosu

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.

• Proper cayley-dickson values are those of dimensionnality greater or equal to 2 (complex, quaternion, ...) and satisfy the concepts::cayley-dickson concept;
• scalar and simd floating types only satisfy the concepts::cayley-dickson_like concept, meaning they are interoperable with proper cayley-dickson values.

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, mul 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_like 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.

  The extension scheme is the following for a function \(f(z)\) defined on complex input \(z\). If c is an arbitrary cayley_dickson entry:

  • first compute \(v=f(\Re(c)+ i |\underline{c}|)\), where \(\Re(c)\) is the real part of \(c\) and \(\underline{c}\) its pure part.
  • The result is then \(\Re(v)+I_c\Im(v)\) where \(I_c\) is defined above and \(\Im(v)\) is the imaginary part of the complex \(v\)

  Moreover some functions are defined that does not pertain to EVE because they do not return real results for real entries. (For instance erfi).

abs	acos	acosh	acospi
acot	acoth	acotpi	acsc
acsch	acscpi	add	agd
airy	airy_ai	airy_bi	am
arg	asec	asech	asecpi
asin	asinh	asinpi	associator
atan	atanh	atanpi	atanpi
average	bessel_h	bessel_i	bessel_j
bessel_k	bessel_y	beta	ceil
chi	commutator	conj	convert
cos	cosh	cospi	cot
coth	cotpi	csc	csch
cscpi	dec	deta	digamma
dist	div	dot	ellint_fe
ellint_rc	ellint_rd	ellint_rf	ellint_rg
ellint_rj	erf	erfcx	erfi
eta	exp	exp10	exp2
exp_i	exp_ipi	expm1	expmx2
expx2	faddeeva	fam	floor
fma	fms	fnma	fnms
frac	from_polar	fsm	gd
gegenbauer	horner	hypergeometric	hypot
if_else	inc	is_cinf	is_denormal
is_equal	is_eqz	is_finite	is_flint
is_fnan	is_imag	is_infinite	is_nan
is_nez	is_not_cinf	is_not_denormal	is_not_equal
is_not_finite	is_not_flint	is_not_fnan	is_not_infinite
is_not_nan	is_not_real	is_pure	is_real
is_unitary	jacobi_elliptic	kummer	lambda
lbeta	ldiv	legendre	lerp
log	log10	log1p	log2
log_abs	log_abs_gamma	log_gamma	lpnorm
lrising_factorial	manhattan	maxabs	maxmag
minabs	minmag	minus	mul
muli	mulmi	nearest	negmaxabs
negminabs	oneminus	parts	pow
pow1p	pow_abs	powm1	proj
pure	radinpi	rec	reldist
reverse_horner	rising_factorial	sec	sech
secpi	sign	sin	sinc
sincos	sinh	sinhc	sinhcosh
sinpi	sinpicospi	slerp	sqr
sqr_abs	sqrt	sub	tan
tanh	tanpi	tchebytchev	tgamma
tgamma_inv	to_cylindrical	to_polar	tricomi
trunc	zeta

• 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, mi, j, k, cinf and fnan are defined.
  • i(as<Z>()) returns at least a complex of the same underlying type as Z or a value of the Z type and verifying i*i==-1;
  • mi(as<Z>()) returns at least a complex of the same underlying type as Z or a value of the Z type equal to -i;
  • 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.
  • fnan(as<Z>()) returns a cayley-dickson like in which all parts are nans.