math-quaternion.qbk

Boost provides free peer-reviewed portable C++ source libraries. We emphasize libraries that work

[article Boost.Quaternions
    [quickbook 1.3]
    [copyright 2001-2003 Hubert Holin]
    [purpose Quaternions]
    [license
        Distributed under the Boost Software License, Version 1.0.
        (See accompanying file LICENSE_1_0.txt or copy at
        [@http://www.boost.org/LICENSE_1_0.txt http://www.boost.org/LICENSE_1_0.txt])
    ]
    [authors [Holin, Hubert]]
    [category math]
    [last-revision $Date: 2006-12-29 11:08:32 +0000 (Fri, 29 Dec 2006) $]
]

[def __R ['[*R]]]
[def __C ['[*C]]]
[def __H ['[*H]]]
[def __O ['[*O]]]
[def __R3 ['[*'''R<superscript>3</superscript>''']]]
[def __R4 ['[*'''R<superscript>4</superscript>''']]]
[def __quadrulple ('''&#x03B1;,&#x03B2;,&#x03B3;,&#x03B4;''')]
[def __quat_formula ['[^q = '''&#x03B1; + &#x03B2;i + &#x03B3;j + &#x03B4;k''']]]
[def __quat_complex_formula ['[^q = ('''&#x03B1; + &#x03B2;i) + (&#x03B3; + &#x03B4;i)j''' ]]]
[def __not_equal ['[^xy '''&#x2260;''' yx]]]

[def __asinh [link boost_quaternions.math_special_functions.asinh asinh]]
[def __acosh [link boost_quaternions.math_special_functions.acosh acosh]]
[def __atanh [link boost_quaternions.math_special_functions.atanh atanh]]
[def __sinc_pi [link boost_quaternions.math_special_functions.sinc_pi sinc_pi]]
[def __sinhc_pi [link boost_quaternions.math_special_functions.sinhc_pi sinhc_pi]]

[def __log1p [link boost_quaternions.math_special_functions.log1p log1p]]
[def __expm1 [link boost_quaternions.math_special_functions.expm1 expm1]]
[def __hypot [link boost_quaternions.math_special_functions.hypot hypot]]

This manual is also available in 
[@http://svn.boost.org/svn/boost/sandbox/pdf/math/release/quaternion.pdf 
printer friendly PDF format].


[section Quaternions]

[section Overview]

Quaternions are a relative of complex numbers.

Quaternions are in fact part of a small hierarchy of structures built 
upon the real numbers, which comprise only the set of real numbers 
(traditionally named __R), the set of complex numbers (traditionally named __C), 
the set of quaternions (traditionally named __H) and the set of octonions 
(traditionally named __O), which possess interesting mathematical properties 
(chief among which is the fact that they are ['division algebras], 
['i.e.] where the following property is true: if ['[^y]] is an element of that 
algebra and is [*not equal to zero], then ['[^yx = yx']], where ['[^x]] and ['[^x']] 
denote elements of that algebra, implies that ['[^x = x']]). 
Each member of the hierarchy is a super-set of the former.

One of the most important aspects of quaternions is that they provide an 
efficient way to parameterize rotations in __R3 (the usual three-dimensional space) 
and __R4.

In practical terms, a quaternion is simply a quadruple of real numbers __quadrulple, 
which we can write in the form __quat_formula, where ['[^i]] is the same object as for complex numbers, 
and ['[^j]] and ['[^k]] are distinct objects which play essentially the same kind of role as ['[^i]].

An addition and a multiplication is defined on the set of quaternions, 
which generalize their real and complex counterparts. The main novelty 
here is that [*the multiplication is not commutative] (i.e. there are 
quaternions ['[^x]] and ['[^y]] such that __not_equal). A good mnemotechnical way of remembering 
things is by using the formula ['[^i*i = j*j = k*k = -1]].

Quaternions (and their kin) are described in far more details in this 
other [@../../../quaternion/TQE.pdf document] 
(with [@../../../quaternion/TQE_EA.pdf errata and addenda]).

Some traditional constructs, such as the exponential, carry over without 
too much change into the realms of quaternions, but other, such as taking 
a square root, do not.

[endsect]

[section Header File]

The interface and implementation are both supplied by the header file 
[@../../../../../boost/math/quaternion.hpp quaternion.hpp].

[endsect]

[section Synopsis]

   namespace boost{ namespace math{
   
   template<typename T> class ``[link boost_quaternions.quaternions.quat quaternion]``;
   template<>           class ``[link boost_quaternions.quaternions.spec quaternion<float>]``;
   template<>           class ``[link boost_quaternions.quaternion_double quaternion<double>]``; 
   template<>           class ``[link boost_quaternions.quaternion_long_double quaternion<long double>]``; 

   // operators
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_addition_operators operator +]`` (T const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_addition_operators operator +]`` (quaternion<T> const & lhs, T const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_addition_operators operator +]`` (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_addition_operators operator +]`` (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_addition_operators operator +]`` (quaternion<T> const & lhs, quaternion<T> const & rhs);

   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_subtraction_operators operator -]`` (T const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_subtraction_operators operator -]`` (quaternion<T> const & lhs, T const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_subtraction_operators operator -]`` (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_subtraction_operators operator -]`` (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_subtraction_operators operator -]`` (quaternion<T> const & lhs, quaternion<T> const & rhs);

   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_multiplication_operators operator *]`` (T const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_multiplication_operators operator *]`` (quaternion<T> const & lhs, T const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_multiplication_operators operator *]`` (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_multiplication_operators operator *]`` (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_multiplication_operators operator *]`` (quaternion<T> const & lhs, quaternion<T> const & rhs);

   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_division_operators operator /]`` (T const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_division_operators operator /]`` (quaternion<T> const & lhs, T const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_division_operators operator /]`` (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_division_operators operator /]`` (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.binary_division_operators operator /]`` (quaternion<T> const & lhs, quaternion<T> const & rhs); 

   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.unary_plus operator +]`` (quaternion<T> const & q);
   template<typename T> quaternion<T> ``[link boost_quaternions.quaternions.non_mem.unary_minus operator -]`` (quaternion<T> const & q); 

   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.equality_operators operator ==]`` (T const & lhs, quaternion<T> const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.equality_operators operator ==]`` (quaternion<T> const & lhs, T const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.equality_operators operator ==]`` (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.equality_operators operator ==]`` (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.equality_operators operator ==]`` (quaternion<T> const & lhs, quaternion<T> const & rhs);

   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.inequality_operators operator !=]`` (T const & lhs, quaternion<T> const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.inequality_operators operator !=]`` (quaternion<T> const & lhs, T const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.inequality_operators operator !=]`` (::std::complex<T> const & lhs, quaternion<T> const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.inequality_operators operator !=]`` (quaternion<T> const & lhs, ::std::complex<T> const & rhs);
   template<typename T> bool ``[link boost_quaternions.quaternions.non_mem.inequality_operators operator !=]`` (quaternion<T> const & lhs, quaternion<T> const & rhs); 

   template<typename T, typename charT, class traits>
   ::std::basic_istream<charT,traits>& ``[link boost_quaternions.quaternions.non_mem.stream_extractor operator >>]`` (::std::basic_istream<charT,traits> & is, quaternion<T> & q);

   template<typename T, typename charT, class traits>
   ::std::basic_ostream<charT,traits>& operator ``[link boost_quaternions.quaternions.non_mem.stream_inserter operator <<]`` (::std::basic_ostream<charT,traits> & os, quaternion<T> const & q);

   // values
   template<typename T>	T              ``[link boost_quaternions.quaternions.value_op.real_and_unreal real]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.value_op.real_and_unreal unreal]``(quaternion<T> const & q);

   template<typename T>	T              ``[link boost_quaternions.quaternions.value_op.sup sup]``(quaternion<T> const & q);
   template<typename T>	T              ``[link boost_quaternions.quaternions.value_op.l1 l1]``(quaternion<T> const & q);
   template<typename T>	T              ``[link boost_quaternions.quaternions.value_op.abs abs]``(quaternion<T> const & q);
   template<typename T>	T              ``[link boost_quaternions.quaternions.value_op.norm norm]``(quaternion<T>const  & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.value_op.conj conj]``(quaternion<T> const & q);

   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.creation_spherical spherical]``(T const & rho, T const & theta, T const & phi1, T const & phi2);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.creation_semipolar semipolar]``(T const & rho, T const & alpha, T const & theta1, T const & theta2);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.creation_multipolar multipolar]``(T const & rho1, T const & theta1, T const & rho2, T const & theta2);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.creation_cylindrospherical cylindrospherical]``(T const & t, T const & radius, T const & longitude, T const & latitude);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.creation_cylindrical cylindrical]``(T const & r, T const & angle, T const & h1, T const & h2);

   // transcendentals
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.exp exp]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.cos cos]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.sin sin]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.tan tan]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.cosh cosh]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.sinh sinh]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.tanh tanh]``(quaternion<T> const & q);
   template<typename T>	quaternion<T>  ``[link boost_quaternions.quaternions.trans.pow pow]``(quaternion<T> const & q, int n);

   } // namespace math
   } // namespace boost
   
[endsect]

[section:quat Template Class quaternion]

   namespace boost{ namespace math{
   
   template<typename T>
   class quaternion
   {
   public:

      typedef T ``[link boost_quaternions.quaternions.mem_typedef value_type]``;

      explicit ``[link boost_quaternions.quaternions.mem_fun.constructors quaternion]``(T const & requested_a = T(), T const & requested_b = T(), T const & requested_c = T(), T const & requested_d = T());
      explicit ``[link boost_quaternions.quaternions.mem_fun.constructors quaternion]``(::std::complex<T> const & z0, ::std::complex<T> const & z1 = ::std::complex<T>());
      template<typename X> 
      explicit ``[link boost_quaternions.quaternions.mem_fun.constructors quaternion]``(quaternion<X> const & a_recopier);

      T                  ``[link boost_quaternions.quaternions.mem_fun.real_and_unreal_parts real]``() const;
      quaternion<T>      ``[link boost_quaternions.quaternions.mem_fun.real_and_unreal_parts unreal]``() const;
      T                  ``[link boost_quaternions.quaternions.mem_fun.individual_real_components R_component_1]``() const;
      T                  ``[link boost_quaternions.quaternions.mem_fun.individual_real_components R_component_2]``() const;
      T                  ``[link boost_quaternions.quaternions.mem_fun.individual_real_components R_component_3]``() const;
      T                  ``[link boost_quaternions.quaternions.mem_fun.individual_real_components R_component_4]``() const;
      ::std::complex<T>  ``[link boost_quaternions.quaternions.mem_fun.individual_complex__components C_component_1]``() const;
      ::std::complex<T>  ``[link boost_quaternions.quaternions.mem_fun.individual_complex__components C_component_2]``() const;

      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.assignment_operators operator = ]``(quaternion<T> const  & a_affecter);
      template<typename X>	
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.assignment_operators operator = ]``(quaternion<X> const  & a_affecter);
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.assignment_operators operator = ]``(T const  & a_affecter);
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.assignment_operators operator = ]``(::std::complex<T> const & a_affecter);

      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.addition_operators operator += ]``(T const & rhs);
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.addition_operators operator += ]``(::std::complex<T> const & rhs);
      template<typename X>
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.addition_operators operator += ]``(quaternion<X> const & rhs);

      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.subtraction_operators operator -= ]``(T const & rhs);
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.subtraction_operators operator -= ]``(::std::complex<T> const & rhs);
      template<typename X>
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.subtraction_operators operator -= ]``(quaternion<X> const & rhs);

      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.multiplication_operators operator *= ]``(T const & rhs);
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.multiplication_operators operator *= ]``(::std::complex<T> const & rhs);
      template<typename X>
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.multiplication_operators operator *= ]``(quaternion<X> const & rhs);

      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.division_operators operator /= ]``(T const & rhs);
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.division_operators operator /= ]``(::std::complex<T> const & rhs);
      template<typename X>
      quaternion<T>&     ``[link boost_quaternions.quaternions.mem_fun.division_operators operator /= ]``(quaternion<X> const & rhs);
   };

   } // namespace math
   } // namespace boost
   
[endsect]

[section:spec Quaternion Specializations]

   namespace boost{ namespace math{