Boost C++ Libraries

Octonions, like quaternions, are a relative of complex numbers.

Octonions see some use in theoretical physics.

In practical terms, an octonion is simply an octuple of real numbers ( α,β,γ,δ,ε,ζ,η,θ ), which we can write in the form o = α + βi + γj + δk + εe' + ζi' + ηj' + θk' , where i, j and k are the same objects as for quaternions, and e', i', j' and k' are distinct objects which play essentially the same kind of role as i (or j or k).

Addition and a multiplication is defined on the set of octonions, which generalize their quaternionic counterparts. The main novelty this time is that the multiplication is not only not commutative, is now not even associative (i.e. there are quaternions x, y and z such that x(yz) ≠ (xy)z). A way of remembering things is by using the following multiplication table:

Octonions (and their kin) are described in far more details in this other document (with errata and addenda).

Some traditional constructs, such as the exponential, carry over without too much change into the realms of octonions, but other, such as taking a square root, do not (the fact that the exponential has a closed form is a result of the author, but the fact that the exponential exists at all for octonions is known since quite a long time ago).

The interface and implementation are both supplied by the header file octonion.hpp.

namespace boost{ namespace math{

template<typename T> class octonion;
template<>           class octonion<float>;
template<>           class octonion<double>; 
template<>           class octonion<long double>; 

// operators

template<typename T> octonion<T> operator + (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator + (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator + (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, octonion<T> const & rhs);

template<typename T> octonion<T> operator - (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator - (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator - (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, octonion<T> const & rhs);

template<typename T> octonion<T> operator * (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator * (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator * (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, octonion<T> const & rhs);

template<typename T> octonion<T> operator / (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator / (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator / (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, octonion<T> const & rhs); 

template<typename T> octonion<T> operator + (octonion<T> const & o);
template<typename T> octonion<T> operator - (octonion<T> const & o); 

template<typename T> bool operator == (T const & lhs, octonion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, T const & rhs);
template<typename T> bool operator == (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> bool operator == (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, octonion<T> const & rhs);

template<typename T> bool operator != (T const & lhs, octonion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, T const & rhs);
template<typename T> bool operator != (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> bool operator != (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, octonion<T> const & rhs); 

template<typename T, typename charT, class traits>
::std::basic_istream<charT,traits> & operator >> (::std::basic_istream<charT,traits> & is, octonion<T> & o);

template<typename T, typename charT, class traits>
::std::basic_ostream<charT,traits> & operator << (::std::basic_ostream<charT,traits> & os, octonion<T> const & o);

// values

template<typename T> T           real(octonion<T> const & o);
template<typename T> octonion<T> unreal(octonion<T> const & o);

template<typename T> T           sup(octonion<T> const & o);
template<typename T> T           l1(octonion<T>const & o); 
template<typename T> T           abs(octonion<T> const & o);
template<typename T> T           norm(octonion<T>const  & o);
template<typename T> octonion<T> conj(octonion<T> const & o);

template<typename T> octonion<T> spherical(T const & rho, T const & theta, T const & phi1, T const & phi2, T const & phi3, T const & phi4, T const & phi5, T const & phi6);
template<typename T> octonion<T> multipolar(T const & rho1, T const & theta1, T const & rho2, T const & theta2, T const & rho3, T const & theta3, T const & rho4, T const & theta4);
template<typename T> octonion<T> cylindrical(T const & r, T const & angle, T const & h1, T const & h2, T const & h3, T const & h4, T const & h5, T const & h6);

// transcendentals

template<typename T> octonion<T> exp(octonion<T> const & o);
template<typename T> octonion<T> cos(octonion<T> const & o);
template<typename T> octonion<T> sin(octonion<T> const & o);
template<typename T> octonion<T> tan(octonion<T> const & o);
template<typename T> octonion<T> cosh(octonion<T> const & o);
template<typename T> octonion<T> sinh(octonion<T> const & o);
template<typename T> octonion<T> tanh(octonion<T> const & o);

template<typename T> octonion<T> pow(octonion<T> const & o, int n);

}  } // namespaces

namespace boost{ namespace math {
  template<typename T>
class octonion
{
public:
   typedef T value_type;

   explicit  octonion(T const & requested_a = T(), T const & requested_b = T(), T const & requested_c = T(), T const & requested_d = T(), T const & requested_e = T(), T const & requested_f = T(), T const & requested_g = T(), T const & requested_h = T());
   explicit  octonion(::std::complex<T> const & z0, ::std::complex<T> const & z1 = ::std::complex<T>(), ::std::complex<T> const & z2 = ::std::complex<T>(), ::std::complex<T> const & z3 = ::std::complex<T>());
   explicit  octonion(::boost::math::quaternion<T> const & q0, ::boost::math::quaternion<T> const & q1 = ::boost::math::quaternion<T>());
   template<typename X> 
   explicit  octonion(octonion<X> const & a_recopier);

   T                             real() const;
   octonion<T>                   unreal() const;

   T                             R_component_1() const;
   T                             R_component_2() const;
   T                             R_component_3() const;
   T                             R_component_4() const;
   T                             R_component_5() const;
   T                             R_component_6() const;
   T                             R_component_7() const;
   T                             R_component_8() const;

   ::std::complex<T>             C_component_1() const;
   ::std::complex<T>             C_component_2() const;
   ::std::complex<T>             C_component_3() const;
   ::std::complex<T>             C_component_4() const;

   ::boost::math::quaternion<T>  H_component_1() const;
   ::boost::math::quaternion<T>  H_component_2() const;

   octonion<T> & operator = (octonion<T> const  & a_affecter);
   template<typename X> 
   octonion<T> & operator = (octonion<X> const  & a_affecter);
   octonion<T> & operator = (T const  & a_affecter);
   octonion<T> & operator = (::std::complex<T> const & a_affecter);
   octonion<T> & operator = (::boost::math::quaternion<T> const & a_affecter);

   octonion<T> & operator += (T const & rhs);
   octonion<T> & operator += (::std::complex<T> const & rhs);
   octonion<T> & operator += (::boost::math::quaternion<T> const & rhs);
   template<typename X> 
   octonion<T> & operator += (octonion<X> const & rhs);

   octonion<T> & operator -= (T const & rhs);
   octonion<T> & operator -= (::std::complex<T> const & rhs);
   octonion<T> & operator -= (::boost::math::quaternion<T> const & rhs);
   template<typename X> 
   octonion<T> & operator -= (octonion<X> const & rhs);

   octonion<T> & operator *= (T const & rhs);
   octonion<T> & operator *= (::std::complex<T> const & rhs);
   octonion<T> & operator *= (::boost::math::quaternion<T> const & rhs);
   template<typename X> 
   octonion<T> & operator *= (octonion<X> const & rhs);

   octonion<T> & operator /= (T const & rhs);
   octonion<T> & operator /= (::std::complex<T> const & rhs);
   octonion<T> & operator /= (::boost::math::quaternion<T> const & rhs);
   template<typename X> 
   octonion<T> & operator /= (octonion<X> const & rhs);
};

} } // namespaces

namespace boost{ namespace math{

template<>
class octonion<float>
{
public:
   typedef float value_type;

   explicit  octonion(float const & requested_a = 0.0f, float const & requested_b = 0.0f, float const & requested_c = 0.0f, float const & requested_d = 0.0f, float const & requested_e = 0.0f, float const & requested_f = 0.0f, float const & requested_g = 0.0f, float const & requested_h = 0.0f);
   explicit  octonion(::std::complex<float> const & z0, ::std::complex<float> const & z1 = ::std::complex<float>(), ::std::complex<float> const & z2 = ::std::complex<float>(), ::std::complex<float> const & z3 = ::std::complex<float>());
   explicit  octonion(::boost::math::quaternion<float> const & q0, ::boost::math::quaternion<float> const & q1 = ::boost::math::quaternion<float>());
   explicit  octonion(octonion<double> const & a_recopier);
   explicit  octonion(octonion<long double> const & a_recopier);

   float                             real() const;
   octonion<float>                   unreal() const;

   float                             R_component_1() const;
   float                             R_component_2() const;
   float                             R_component_3() const;
   float                             R_component_4() const;
   float                             R_component_5() const;
   float                             R_component_6() const;
   float                             R_component_7() const;
   float                             R_component_8() const;

   ::std::complex<float>             C_component_1() const;
   ::std::complex<float>             C_component_2() const;
   ::std::complex<float>             C_component_3() const;
   ::std::complex<float>             C_component_4() const;

   ::boost::math::quaternion<float>  H_component_1() const;
   ::boost::math::quaternion<float>  H_component_2() const;

   octonion<float> & operator = (octonion<float> const  & a_affecter);
   template<typename X> 
   octonion<float> & operator = (octonion<X> const  & a_affecter);
   octonion<float> & operator = (float const  & a_affecter);
   octonion<float> & operator = (::std::complex<float> const & a_affecter);
   octonion<float> & operator = (::boost::math::quaternion<float> const & a_affecter);

   octonion<float> & operator += (float const & rhs);
   octonion<float> & operator += (::std::complex<float> const & rhs);
   octonion<float> & operator += (::boost::math::quaternion<float> const & rhs);
   template<typename X> 
   octonion<float> & operator += (octonion<X> const & rhs);

   octonion<float> & operator -= (float const & rhs);
   octonion<float> & operator -= (::std::complex<float> const & rhs);
   octonion<float> & operator -= (::boost::math::quaternion<float> const & rhs);
   template<typename X> 
   octonion<float> & operator -= (octonion<X> const & rhs);

   octonion<float> & operator *= (float const & rhs);
   octonion<float> & operator *= (::std::complex<float> const & rhs);
   octonion<float> & operator *= (::boost::math::quaternion<float> const & rhs);
   template<typename X> 
   octonion<float> & operator *= (octonion<X> const & rhs);

   octonion<float> & operator /= (float const & rhs);
   octonion<float> & operator /= (::std::complex<float> const & rhs);
   octonion<float> & operator /= (::boost::math::quaternion<float> const & rhs);
   template<typename X> 
   octonion<float> & operator /= (octonion<X> const & rhs);
};

template<>
class octonion<double>
{
public:
   typedef double value_type;

   explicit  octonion(double const & requested_a = 0.0, double const & requested_b = 0.0, double const & requested_c = 0.0, double const & requested_d = 0.0, double const & requested_e = 0.0, double const & requested_f = 0.0, double const & requested_g = 0.0, double const & requested_h = 0.0);
   explicit  octonion(::std::complex<double> const & z0, ::std::complex<double> const & z1 = ::std::complex<double>(), ::std::complex<double> const & z2 = ::std::complex<double>(), ::std::complex<double> const & z3 = ::std::complex<double>());
   explicit  octonion(::boost::math::quaternion<double> const & q0, ::boost::math::quaternion<double> const & q1 = ::boost::math::quaternion<double>());
   explicit  octonion(octonion<float> const & a_recopier);
   explicit  octonion(octonion<long double> const & a_recopier);

   double                             real() const;
   octonion<double>                   unreal() const;

   double                             R_component_1() const;
   double                             R_component_2() const;
   double                             R_component_3() const;
   double                             R_component_4() const;
   double                             R_component_5() const;
   double                             R_component_6() const;
   double                             R_component_7() const;
   double                             R_component_8() const;

   ::std::complex<double>             C_component_1() const;
   ::std::complex<double>             C_component_2() const;
   ::std::complex<double>             C_component_3() const;
   ::std::complex<double>             C_component_4() const;

   ::boost::math::quaternion<double>  H_component_1() const;
   ::boost::math::quaternion<double>  H_component_2() const;

   octonion<double> & operator = (octonion<double> const  & a_affecter);
   template<typename X> 
   octonion<double> & operator = (octonion<X> const  & a_affecter);
   octonion<double> & operator = (double const  & a_affecter);
   octonion<double> & operator = (::std::complex<double> const & a_affecter);
   octonion<double> & operator = (::boost::math::quaternion<double> const & a_affecter);

   octonion<double> & operator += (double const & rhs);
   octonion<double> & operator += (::std::complex<double> const & rhs);
   octonion<double> & operator += (::boost::math::quaternion<double> const & rhs);
   template<typename X> 
   octonion<double> & operator += (octonion<X> const & rhs);

   octonion<double> & operator -= (double const & rhs);
   octonion<double> & operator -= (::std::complex<double> const & rhs);
   octonion<double> & operator -= (::boost::math::quaternion<double> const & rhs);
   template<typename X> 
   octonion<double> & operator -= (octonion<X> const & rhs);

   octonion<double> & operator *= (double const & rhs);
   octonion<double> & operator *= (::std::complex<double> const & rhs);
   octonion<double> & operator *= (::boost::math::quaternion<double> const & rhs);
   template<typename X> 
   octonion<double> & operator *= (octonion<X> const & rhs);

   octonion<double> & operator /= (double const & rhs);
   octonion<double> & operator /= (::std::complex<double> const & rhs);
   octonion<double> & operator /= (::boost::math::quaternion<double> const & rhs);
   template<typename X> 
   octonion<double> & operator /= (octonion<X> const & rhs);
};

template<>
class octonion<long double>
{
public:
   typedef long double value_type;

   explicit   octonion(long double const & requested_a = 0.0L, long double const & requested_b = 0.0L, long double const & requested_c = 0.0L, long double const & requested_d = 0.0L, long double const & requested_e = 0.0L, long double const & requested_f = 0.0L, long double const & requested_g = 0.0L, long double const & requested_h = 0.0L);
   explicit   octonion( ::std::complex<long double> const & z0, ::std::complex<long double> const & z1 = ::std::complex<long double>(), ::std::complex<long double> const & z2 = ::std::complex<long double>(), ::std::complex<long double> const & z3 = ::std::complex<long double>());
   explicit   octonion( ::boost::math::quaternion<long double> const & q0, ::boost::math::quaternion<long double> const & z1 = ::boost::math::quaternion<long double>());
   explicit   octonion(octonion<float> const & a_recopier);
   explicit   octonion(octonion<double> const & a_recopier);

   long double                             real() const;
   octonion<long double>                   unreal() const;

   long double                             R_component_1() const;
   long double                             R_component_2() const;
   long double                             R_component_3() const;
   long double                             R_component_4() const;
   long double                             R_component_5() const;
   long double                             R_component_6() const;
   long double                             R_component_7() const;
   long double                             R_component_8() const;

   ::std::complex<long double>             C_component_1() const;
   ::std::complex<long double>             C_component_2() const;
   ::std::complex<long double>             C_component_3() const;
   ::std::complex<long double>             C_component_4() const;

   ::boost::math::quaternion<long double>  H_component_1() const;
   ::boost::math::quaternion<long double>  H_component_2() const;

   octonion<long double> & operator = (octonion<long double> const  & a_affecter);
   template<typename X> 
   octonion<long double> & operator = (octonion<X> const  & a_affecter);
   octonion<long double> & operator = (long double const  & a_affecter);
   octonion<long double> & operator = (::std::complex<long double> const & a_affecter);
   octonion<long double> & operator = (::boost::math::quaternion<long double> const & a_affecter);

   octonion<long double> & operator += (long double const & rhs);
   octonion<long double> & operator += (::std::complex<long double> const & rhs);
   octonion<long double> & operator += (::boost::math::quaternion<long double> const & rhs);
   template<typename X> 
   octonion<long double> & operator += (octonion<X> const & rhs);

   octonion<long double> & operator -= (long double const & rhs);
   octonion<long double> & operator -= (::std::complex<long double> const & rhs);
   octonion<long double> & operator -= (::boost::math::quaternion<long double> const & rhs);
   template<typename X> 
   octonion<long double> & operator -= (octonion<X> const & rhs);

   octonion<long double> & operator *= (long double const & rhs);
   octonion<long double> & operator *= (::std::complex<long double> const & rhs);
   octonion<long double> & operator *= (::boost::math::quaternion<long double> const & rhs);
   template<typename X> 
   octonion<long double> & operator *= (octonion<X> const & rhs);

   octonion<long double> & operator /= (long double const & rhs);
   octonion<long double> & operator /= (::std::complex<long double> const & rhs);
   octonion<long double> & operator /= (::boost::math::quaternion<long double> const & rhs);
   template<typename X> 
   octonion<long double> & operator /= (octonion<X> const & rhs);
};

} } // namespaces

value_type

Template version:

typedef T value_type;

Float specialization version:

typedef float value_type;

Double specialization version:

typedef double value_type;

Long double specialization version:

typedef long double value_type;

These provide easy acces to the type the template is built upon.

Constructors

Template version:

explicit  octonion(T const & requested_a = T(), T const & requested_b = T(), T const & requested_c = T(), T const & requested_d = T(), T const & requested_e = T(), T const & requested_f = T(), T const & requested_g = T(), T const & requested_h = T());
explicit  octonion(::std::complex<T> const & z0, ::std::complex<T> const & z1 = ::std::complex<T>(), ::std::complex<T> const & z2 = ::std::complex<T>(), ::std::complex<T> const & z3 = ::std::complex<T>());
explicit  octonion(::boost::math::quaternion<T> const & q0, ::boost::math::quaternion<T> const & q1 = ::boost::math::quaternion<T>());
template<typename X> 
explicit octonion(octonion<X> const & a_recopier);

Float specialization version:

explicit  octonion(float const & requested_a = 0.0f, float const & requested_b = 0.0f, float const & requested_c = 0.0f, float const & requested_d = 0.0f, float const & requested_e = 0.0f, float const & requested_f = 0.0f, float const & requested_g = 0.0f, float const & requested_h = 0.0f);
explicit  octonion(::std::complex<float> const & z0, ::std::complex<float> const & z1 = ::std::complex<float>(), ::std::complex<float> const & z2 = ::std::complex<float>(), ::std::complex<float> const & z3 = ::std::complex<float>());
explicit  octonion(::boost::math::quaternion<float> const & q0, ::boost::math::quaternion<float> const & q1 = ::boost::math::quaternion<float>());
explicit  octonion(octonion<double> const & a_recopier); 
explicit  octonion(octonion<long double> const & a_recopier);

Double specialization version:

explicit  octonion(double const & requested_a = 0.0, double const & requested_b = 0.0, double const & requested_c = 0.0, double const & requested_d = 0.0, double const & requested_e = 0.0, double const & requested_f = 0.0, double const & requested_g = 0.0, double const & requested_h = 0.0);
explicit  octonion(::std::complex<double> const & z0, ::std::complex<double> const & z1 = ::std::complex<double>(), ::std::complex<double> const & z2 = ::std::complex<double>(), ::std::complex<double> const & z3 = ::std::complex<double>());
explicit  octonion(::boost::math::quaternion<double> const & q0, ::boost::math::quaternion<double> const & q1 = ::boost::math::quaternion<double>());
explicit  octonion(octonion<float> const & a_recopier);
explicit  octonion(octonion<long double> const & a_recopier);

Long double specialization version:

explicit  octonion(long double const & requested_a = 0.0L, long double const & requested_b = 0.0L, long double const & requested_c = 0.0L, long double const & requested_d = 0.0L, long double const & requested_e = 0.0L, long double const & requested_f = 0.0L, long double const & requested_g = 0.0L, long double const & requested_h = 0.0L);
explicit  octonion( ::std::complex<long double> const & z0, ::std::complex<long double> const & z1 = ::std::complex<long double>(), ::std::complex<long double> const & z2 = ::std::complex<long double>(), ::std::complex<long double> const & z3 = ::std::complex<long double>());
explicit  octonion(::boost::math::quaternion<long double> const & q0, ::boost::math::quaternion<long double> const & q1 = ::boost::math::quaternion<long double>());
explicit  octonion(octonion<float> const & a_recopier);
explicit  octonion(octonion<double> const & a_recopier);

A default constructor is provided for each form, which initializes each component to the default values for their type (i.e. zero for floating numbers). This constructor can also accept one to eight base type arguments. A constructor is also provided to build octonions from one to four complex numbers sharing the same base type, and another taking one or two quaternions sharing the same base type. The unspecialized template also sports a templarized copy constructor, while the specialized forms have copy constructors from the other two specializations, which are explicit when a risk of precision loss exists. For the unspecialized form, the base type's constructors must not throw.

Destructors and untemplated copy constructors (from the same type) are provided by the compiler. Converting copy constructors make use of a templated helper function in a "detail" subnamespace.

Other member functions

Real and Unreal Parts

T            real()   const;
octonion<T>  unreal() const;

Like complex number, octonions do have a meaningful notion of "real part", but unlike them there is no meaningful notion of "imaginary part". Instead there is an "unreal part" which itself is a octonion, and usually nothing simpler (as opposed to the complex number case). These are returned by the first two functions.

Individual Real Components

T   R_component_1() const;
T   R_component_2() const;
T   R_component_3() const;
T   R_component_4() const;
T   R_component_5() const;
T   R_component_6() const;
T   R_component_7() const;
T   R_component_8() const;

A octonion having eight real components, these are returned by these eight functions. Hence real and R_component_1 return the same value.

Individual Complex Components

::std::complex<T> C_component_1() const;
::std::complex<T> C_component_2() const;
::std::complex<T> C_component_3() const;
::std::complex<T> C_component_4() const;

A octonion likewise has four complex components. Actually, octonions are indeed a (left) vector field over the complexes, but beware, as for any octonion o = α + βi + γj + δk + εe' + ζi' + ηj' + θk' we also have o = ( α + βi) + (γ + δi)j + (ε + ζi)e' + (η - θi)j' (note the minus sign in the last factor). What the C_component_n functions return, however, are the complexes which could be used to build the octonion using the constructor, and not the components of the octonion on the basis (1, j, e', j').

Individual Quaternion Components

::boost::math::quaternion<T> H_component_1() const;
::boost::math::quaternion<T> H_component_2() const;

Likewise, for any octonion o = α + βi + γj + δk + εe' + ζi' + ηj' + θk' we also have o = ( α + βi + γj + δk) + (ε + ζi + ηj - θj)e' , though there is no meaningful vector-space-like structure based on the quaternions. What the H_component_n functions return are the quaternions which could be used to build the octonion using the constructor.

Octonion Member Operators

Assignment Operators

octonion<T> & operator = (octonion<T> const & a_affecter);
template<typename X> 
octonion<T> & operator = (octonion<X> const & a_affecter);
octonion<T> & operator = (T const & a_affecter);
octonion<T> & operator = (::std::complex<T> const & a_affecter);
octonion<T> & operator = (::boost::math::quaternion<T> const & a_affecter);

These perform the expected assignment, with type modification if necessary (for instance, assigning from a base type will set the real part to that value, and all other components to zero). For the unspecialized form, the base type's assignment operators must not throw.

Other Member Operators

octonion<T> & operator += (T const & rhs)
octonion<T> & operator += (::std::complex<T> const & rhs);
octonion<T> & operator += (::boost::math::quaternion<T> const & rhs);
template<typename X> 
octonion<T> & operator += (octonion<X> const & rhs);

These perform the mathematical operation (*this)+rhs and store the result in *this. The unspecialized form has exception guards, which the specialized forms do not, so as to insure exception safety. For the unspecialized form, the base type's assignment operators must not throw.

octonion<T> & operator -= (T const & rhs)
octonion<T> & operator -= (::std::complex<T> const & rhs);
octonion<T> & operator -= (::boost::math::quaternion<T> const & rhs);
template<typename X> 
octonion<T> & operator -= (octonion<X> const & rhs);

These perform the mathematical operation (*this)-rhs and store the result in *this. The unspecialized form has exception guards, which the specialized forms do not, so as to insure exception safety. For the unspecialized form, the base type's assignment operators must not throw.

octonion<T> & operator *= (T const & rhs)
octonion<T> & operator *= (::std::complex<T> const & rhs);
octonion<T> & operator *= (::boost::math::quaternion<T> const & rhs);
template<typename X> 
octonion<T> & operator *= (octonion<X> const & rhs);

These perform the mathematical operation (*this)*rhs in this order (order is important as multiplication is not commutative for octonions) and store the result in *this. The unspecialized form has exception guards, which the specialized forms do not, so as to insure exception safety. For the unspecialized form, the base type's assignment operators must not throw. Also, for clarity's sake, you should always group the factors in a multiplication by groups of two, as the multiplication is not even associative on the octonions (though there are of course cases where this does not matter, it usually does).

octonion<T> & operator /= (T const & rhs)
octonion<T> & operator /= (::std::complex<T> const & rhs);
octonion<T> & operator /= (::boost::math::quaternion<T> const & rhs);
template<typename X> 
octonion<T> & operator /= (octonion<X> const & rhs);

These perform the mathematical operation (*this)*inverse_of(rhs) in this order (order is important as multiplication is not commutative for octonions) and store the result in *this. The unspecialized form has exception guards, which the specialized forms do not, so as to insure exception safety. For the unspecialized form, the base type's assignment operators must not throw. As for the multiplication, remember to group any two factors using parenthesis.

Unary Plus and Minus Operators

template<typename T> octonion<T> operator + (octonion<T> const & o);

This unary operator simply returns o.

template<typename T> octonion<T> operator - (octonion<T> const & o);

This unary operator returns the opposite of o.

Binary Addition Operators

template<typename T> octonion<T> operator + (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator + (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator + (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator + (octonion<T> const & lhs, octonion<T> const & rhs);

These operators return octonion<T>(lhs) += rhs.

Binary Subtraction Operators

template<typename T> octonion<T> operator - (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator - (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator - (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator - (octonion<T> const & lhs, octonion<T> const & rhs);

These operators return octonion<T>(lhs) -= rhs.

Binary Multiplication Operators

template<typename T> octonion<T> operator * (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator * (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator * (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator * (octonion<T> const & lhs, octonion<T> const & rhs);

These operators return octonion<T>(lhs) *= rhs.

Binary Division Operators

template<typename T> octonion<T> operator / (T const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, T const & rhs);
template<typename T> octonion<T> operator / (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> octonion<T> operator / (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> octonion<T> operator / (octonion<T> const & lhs, octonion<T> const & rhs);

These operators return octonion<T>(lhs) /= rhs. It is of course still an error to divide by zero...

Binary Equality Operators

template<typename T> bool operator == (T const & lhs, octonion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, T const & rhs);
template<typename T> bool operator == (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> bool operator == (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> bool operator == (octonion<T> const & lhs, octonion<T> const & rhs);

These return true if and only if the four components of octonion<T>(lhs) are equal to their counterparts in octonion<T>(rhs). As with any floating-type entity, this is essentially meaningless.

Binary Inequality Operators

template<typename T> bool operator != (T const & lhs, octonion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, T const & rhs);
template<typename T> bool operator != (::std::complex<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, ::std::complex<T> const & rhs);
template<typename T> bool operator != (::boost::math::quaternion<T> const & lhs, octonion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, ::boost::math::quaternion<T> const & rhs);
template<typename T> bool operator != (octonion<T> const & lhs, octonion<T> const & rhs);

These return true if and only if octonion<T>(lhs) == octonion<T>(rhs) is false. As with any floating-type entity, this is essentially meaningless.

Stream Extractor

template<typename T, typename charT, class traits>
::std::basic_istream<charT,traits> & operator >> (::std::basic_istream<charT,traits> & is, octonion<T> & o);

Extracts an octonion o. We accept any format which seems reasonable. However, since this leads to a great many ambiguities, decisions were made to lift these. In case of doubt, stick to lists of reals.

The input values must be convertible to T. If bad input is encountered, calls is.setstate(ios::failbit) (which may throw ios::failure (27.4.5.3)).

Returns is.

Stream Inserter

template<typename T, typename charT, class traits>
::std::basic_ostream<charT,traits> & operator << (::std::basic_ostream<charT,traits> & os, octonion<T> const & o);

Inserts the octonion o onto the stream os as if it were implemented as follows:

template<typename T, typename charT, class traits>
::std::basic_ostream<charT,traits> & operator << ( ::std::basic_ostream<charT,traits> & os,
octonion<T> const & o)
{
   ::std::basic_ostringstream<charT,traits> s;

   s.flags(os.flags());
   s.imbue(os.getloc());
   s.precision(os.precision());

   s << '(' << o.R_component_1() << ','
      << o.R_component_2() << ','
      << o.R_component_3() << ','
      << o.R_component_4() << ','
      << o.R_component_5() << ','
      << o.R_component_6() << ','
      << o.R_component_7() << ','
      << o.R_component_8() << ')';

   return os << s.str();
}

Real and Unreal

template<typename T> T  real(octonion<T> const & o);
template<typename T> octonion<T> unreal(octonion<T> const & o);

These return o.real() and o.unreal() respectively.

conj

template<typename T> octonion<T> conj(octonion<T> const & o);

This returns the conjugate of the octonion.

sup

template<typename T> T   sup(octonion<T> const & o);

This return the sup norm (the greatest among abs(o.R_component_1())...abs(o.R_component_8())) of the octonion.

l1

template<typename T> T   l1(octonion<T> const & o);

This return the l1 norm (abs(o.R_component_1())+...+abs(o.R_component_8())) of the octonion.

abs

template<typename T> T   abs(octonion<T> const & o);

This return the magnitude (Euclidian norm) of the octonion.

norm

template<typename T> T  norm(octonion<T>const  & o);

This return the (Cayley) norm of the octonion. The term "norm" might be confusing, as most people associate it with the Euclidian norm (and quadratic functionals). For this version of (the mathematical objects known as) octonions, the Euclidian norm (also known as magnitude) is the square root of the Cayley norm.

template<typename T> octonion<T> spherical(T const & rho, T const & theta, T const & phi1, T const & phi2, T const & phi3, T const & phi4, T const & phi5, T const & phi6);
template<typename T> octonion<T> multipolar(T const & rho1, T const & theta1, T const & rho2, T const & theta2, T const & rho3, T const & theta3, T const & rho4, T const & theta4);
template<typename T> octonion<T> cylindrical(T const & r, T const & angle, T const & h1, T const & h2, T const & h3, T const & h4, T const & h5, T const & h6);

These build octonions in a way similar to the way polar builds complex numbers, as there is no strict equivalent to polar coordinates for octonions.

spherical is a simple transposition of polar, it takes as inputs a (positive) magnitude and a point on the hypersphere, given by three angles. The first of these, theta has a natural range of -pi to +pi, and the other two have natural ranges of -pi/2 to +pi/2 (as is the case with the usual spherical coordinates in R³ ). Due to the many symmetries and periodicities, nothing untoward happens if the magnitude is negative or the angles are outside their natural ranges. The expected degeneracies (a magnitude of zero ignores the angles settings...) do happen however.

cylindrical is likewise a simple transposition of the usual cylindrical coordinates in R³ , which in turn is another derivative of planar polar coordinates. The first two inputs are the polar coordinates of the first C component of the octonion. The third and fourth inputs are placed into the third and fourth R components of the octonion, respectively.

multipolar is yet another simple generalization of polar coordinates. This time, both C components of the octonion are given in polar coordinates.

In this version of our implementation of octonions, there is no analogue of the complex value operation arg as the situation is somewhat more complicated.