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

KYOSU implements SIMD complex numbers: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 (with a few exceptions restricted to some dimensionnalities constraints) 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. They don't satisfy the concepts::real concept;
• scalar and simd floating types only satisfy the concepts::cayley-dickson_like concept, meaning they are interoperable with proper cayley-dickson values. They satisfy the concepts::real concept.
• Almost all functions involving angles (within the parameters or the results) can receive an option (namely kyosu::radpi) such that every angle parameter or result will be expressed in \(\pi\) multiples rather than in mere radians. (This use can be beneficial as some currently used angles values are small integer multiples of \(\pi\). \(\pi\) is not exactly represented by floating point values; but small integers are...)

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). Note that except for real and complex this is NOT b/a.

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.

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, div and ldiv. These version are multiparameters and can also use KUMI tuples. Also plus and minus can be used for unary versions.

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

The multiplication to the left by i or -i (i*i=-1) can be done calling respectively muli and mulmi which ensure optimization. With the right option the multiplication is done to the right.

Functions

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

Also many functions as sqrt nthroot or log are the principal value of a multiple valued inverse of an analytic function. Most of these functions can use a second parameter that allows to choose another branch.

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.

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

However, many of those functions provide a real_only option that allows to call them with floating value typed parameters (NOT cayley_dickson_like with null pure part) and returns the floating value of the same type which is the eve call result.

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

• 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 never return real results for real entries. (For instance exp_i).

abs	acos	acosh	acot
acoth	acsc	acsch	add
agd	airy	airy_ai	airy_bi
am	arg	asec	asech
asin	asinh	associator	atan
atanh	average	bessel_h	bessel_i
bessel_j	bessel_k	bessel_y	beta
ceil	cbrt	chi	commutator
conj	convert	cos	cosh
cot	coth	csc	csch
	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	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	kronecker	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	nthroot	oneminus	pow
pow1p	pow_abs	powm1	proj
pure	radinpi	rec	reldist
reverse_horner	rising_factorial	sec	sech
sign	sin	sinc	sincos
sinh	sinhc	sinhcosh	slerp
sqr	sqr_abs	sqrt	sub
tan	tanh	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.

    Warning

    i(as<Z>()) and j(as<Z>()) are not aliases of each other. j(as<Z>()) is always at least a quaternion. Sorry for the electrical engineers!