diff --git a/doc/math-background.qbk b/doc/math-background.qbk new file mode 100644 index 000000000..6a721979e --- /dev/null +++ b/doc/math-background.qbk @@ -0,0 +1,89 @@ + +[def __form1 [^\]-1;1\[]] +[def __form2 [^\[0;+'''∞'''\[]] +[def __form3 [^\[+1;+'''∞'''\[]] +[def __form4 [^\]-'''∞''';0\]]] +[def __form5 [^x '''≥''' 0]] + + +[section Background Information and White Papers] + +[section The Inverse Hyperbolic Functions] + +The exponential funtion is defined, for all object for which this makes sense, +as the power series +[$../../libs/math/special_functions/graphics/special_functions_blurb1.jpeg], +with ['[^n! = 1x2x3x4x5...xn]] (and ['[^0! = 1]] by definition) being the factorial of ['[^n]]. +In particular, the exponential function is well defined for real numbers, +complex number, quaternions, octonions, and matrices of complex numbers, +among others. + +[: ['[*Graph of exp on R]] ] + +[: [$../../libs/math/special_functions/graphics/exp_on_R.png] ] + +[: ['[*Real and Imaginary parts of exp on C]]] +[: [$../../libs/math/special_functions/graphics/Im_exp_on_C.png]] + +The hyperbolic functions are defined as power series which +can be computed (for reals, complex, quaternions and octonions) as: + +Hyperbolic cosine: [$../../libs/math/special_functions/graphics/special_functions_blurb5.jpeg] + +Hyperbolic sine: [$../../libs/math/special_functions/graphics/special_functions_blurb6.jpeg] + +Hyperbolic tangent: [$../../libs/math/special_functions/graphics/special_functions_blurb7.jpeg] + +[: ['[*Trigonometric functions on R (cos: purple; sin: red; tan: blue)]]] +[: [$../../libs/math/special_functions/graphics/trigonometric.png]] + +[: ['[*Hyperbolic functions on r (cosh: purple; sinh: red; tanh: blue)]]] +[: [$../../libs/math/special_functions/graphics/hyperbolic.png]] + +The hyperbolic sine is one to one on the set of real numbers, +with range the full set of reals, while the hyperbolic tangent is +also one to one on the set of real numbers but with range __form1, and +therefore both have inverses. The hyperbolic cosine is one to one from __form2 +onto __form3 (and from __form4 onto __form3); the inverse function we use +here is defined on __form3 with range __form2. + +The inverse of the hyperbolic tangent is called the Argument hyperbolic tangent, +and can be computed as [$../../libs/math/special_functions/graphics/special_functions_blurb15.jpeg]. + +The inverse of the hyperbolic sine is called the Argument hyperbolic sine, +and can be computed (for __form5) as [$../../libs/math/special_functions/graphics/special_functions_blurb17.jpeg]. + +The inverse of the hyperbolic cosine is called the Argument hyperbolic cosine, +and can be computed as [$../../libs/math/special_functions/graphics/special_functions_blurb18.jpeg]. + +[endsect] + +[section Sinus Cardinal and Hyperbolic Sinus Cardinal Functions] + +The Sinus Cardinal family of functions (indexed by the family of indices [^a > 0]) +is defined by +[$../../libs/math/special_functions/graphics/special_functions_blurb20.jpeg]; +it sees heavy use in signal processing tasks. + +By analogy, the Hyperbolic Sinus Cardinal family of functions +(also indexed by the family of indices [^a > 0]) is defined by +[$../../libs/math/special_functions/graphics/special_functions_blurb22.jpeg]. + +These two families of functions are composed of entire functions. + +[: ['[*Sinus Cardinal of index pi (purple) and Hyperbolic Sinus Cardinal of index pi (red) on R]]] +[: [$../../libs/math/special_functions/graphics/sinc_pi_and_sinhc_pi_on_R.png]] + +[endsect] + +[section The Quaternionic Exponential] + +Please refer to the following PDF's: + +*[@../../libs/math/quaternion/TQE.pdf The Quaternionic Exponential (and beyond)] +*[@../../libs/math/quaternion/TQE_EA.pdf The Quaternionic Exponential (and beyond) ERRATA & ADDENDA] + +[endsect] + +[endsect] + diff --git a/doc/math-gcd.qbk b/doc/math-gcd.qbk new file mode 100644 index 000000000..9f4fbfbee --- /dev/null +++ b/doc/math-gcd.qbk @@ -0,0 +1,229 @@ + +[section Greatest Common Divisor and Least Common Multiple] + +[section Introduction] + +The class and function templates in +provide run-time and compile-time evaluation of the greatest common divisor +(GCD) or least common multiple (LCM) of two integers. +These facilities are useful for many numeric-oriented generic +programming problems. + +[endsect] + +[section Synopsis] + + namespace boost + { + namespace math + { + + template < typename IntegerType > + class gcd_evaluator; + template < typename IntegerType > + class lcm_evaluator; + + template < typename IntegerType > + IntegerType gcd( IntegerType const &a, IntegerType const &b ); + template < typename IntegerType > + IntegerType lcm( IntegerType const &a, IntegerType const &b ); + + template < unsigned long Value1, unsigned long Value2 > + struct static_gcd; + template < unsigned long Value1, unsigned long Value2 > + struct static_lcm; + + } + } + +[endsect] + +[section GCD Function Object] + +[*Header: ] [@../../boost/math/common_factor_rt.hpp ] + + template < typename IntegerType > + class boost::math::gcd_evaluator + { + public: + // Types + typedef IntegerType result_type; + typedef IntegerType first_argument_type; + typedef IntegerType second_argument_type; + + // Function object interface + result_type operator ()( first_argument_type const &a, + second_argument_type const &b ) const; + }; + +The boost::math::gcd_evaluator class template defines a function object +class to return the greatest common divisor of two integers. +The template is parameterized by a single type, called IntegerType here. +This type should be a numeric type that represents integers. +The result of the function object is always nonnegative, even if either of +the operator arguments is negative. + +This function object class template is used in the corresponding version of +the GCD function template. If a numeric type wants to customize evaluations +of its greatest common divisors, then the type should specialize on the +gcd_evaluator class template. + +[endsect] + +[section LCM Function Object] + +[*Header: ] [@../../boost/math/common_factor_rt.hpp ] + + template < typename IntegerType > + class boost::math::lcm_evaluator + { + public: + // Types + typedef IntegerType result_type; + typedef IntegerType first_argument_type; + typedef IntegerType second_argument_type; + + // Function object interface + result_type operator ()( first_argument_type const &a, + second_argument_type const &b ) const; + }; + +The boost::math::lcm_evaluator class template defines a function object +class to return the least common multiple of two integers. The template +is parameterized by a single type, called IntegerType here. This type +should be a numeric type that represents integers. The result of the +function object is always nonnegative, even if either of the operator +arguments is negative. If the least common multiple is beyond the range +of the integer type, the results are undefined. + +This function object class template is used in the corresponding version +of the LCM function template. If a numeric type wants to customize +evaluations of its least common multiples, then the type should +specialize on the lcm_evaluator class template. + +[endsect] + +[section Run-time GCD & LCM Determination] + +[*Header: ] [@../../boost/math/common_factor_rt.hpp ] + + template < typename IntegerType > + IntegerType boost::math::gcd( IntegerType const &a, IntegerType const &b ); + + template < typename IntegerType > + IntegerType boost::math::lcm( IntegerType const &a, IntegerType const &b ); + +The boost::math::gcd function template returns the greatest common +(nonnegative) divisor of the two integers passed to it. +The boost::math::lcm function template returns the least common +(nonnegative) multiple of the two integers passed to it. +The function templates are parameterized on the function arguments' +IntegerType, which is also the return type. Internally, these function +templates use an object of the corresponding version of the +gcd_evaluator and lcm_evaluator class templates, respectively. + +[endsect] + +[section Compile time GCD and LCM determination] + +[*Header: ] [@../../boost/math/common_factor_ct.hpp ] + + template < unsigned long Value1, unsigned long Value2 > + struct boost::math::static_gcd + { + static unsigned long const value = implementation_defined; + }; + + template < unsigned long Value1, unsigned long Value2 > + struct boost::math::static_lcm + { + static unsigned long const value = implementation_defined; + }; + +The boost::math::static_gcd and boost::math::static_lcm class templates +take two value-based template parameters of the unsigned long type +and have a single static constant data member, value, of that same type. +The value of that member is the greatest common factor or least +common multiple, respectively, of the template arguments. +A compile-time error will occur if the least common multiple +is beyond the range of an unsigned long. + +[h3 Example] + + #include + #include + #include + + + int main() + { + using std::cout; + using std::endl; + + cout << "The GCD and LCM of 6 and 15 are " + << boost::math::gcd(6, 15) << " and " + << boost::math::lcm(6, 15) << ", respectively." + << endl; + + cout << "The GCD and LCM of 8 and 9 are " + << boost::math::static_gcd<8, 9>::value + << " and " + << boost::math::static_lcm<8, 9>::value + << ", respectively." << endl; + + int a[] = { 4, 5, 6 }, b[] = { 7, 8, 9 }, c[3]; + std::transform( a, a + 3, b, c, boost::math::gcd_evaluator() ); + std::copy( c, c + 3, std::ostream_iterator(cout, " ") ); + } + +[endsect] + +[section Header ] + +This header simply includes the headers +[@../../boost/math/common_factor_ct.hpp ] +and [@../../boost/math/common_factor_rt.hpp ]. + +Note this is a legacy header: it used to contain the actual implementation, +but the compile-time and run-time facilities +were moved to separate headers (since they were independent of each other). + +[endsect] + +[section Demonstration Program] + +The program [@../../libs/math/test/common_factor_test.cpp common_factor_test.cpp] is a demonstration of the results from +instantiating various examples of the run-time GCD and LCM function +templates and the compile-time GCD and LCM class templates. +(The run-time GCD and LCM class templates are tested indirectly through +the run-time function templates.) + +[endsect] + +[section Rationale] + +The greatest common divisor and least common multiple functions are +greatly used in some numeric contexts, including some of the other +Boost libraries. Centralizing these functions to one header improves +code factoring and eases maintainence. + +[endsect] + +[section History] + +* 17 Dec 2005: Converted documentation to Quickbook Format. +* 2 Jul 2002: Compile-time and run-time items separated to new headers. +* 7 Nov 2001: Initial version + +[endsect] + +[section Credits] + +The author of the Boost compilation of GCD and LCM computations is +Daryle Walker. The code was prompted by existing code hiding in the +implementations of Paul Moore's rational library and Steve Cleary's +pool library. The code had updates by Helmut Zeisel. + +[endsect] + +[endsect] diff --git a/doc/math-octonion.qbk b/doc/math-octonion.qbk new file mode 100644 index 000000000..8d7ecbd0e --- /dev/null +++ b/doc/math-octonion.qbk @@ -0,0 +1,983 @@ + +[def __R ['[*R]]] +[def __C ['[*C]]] +[def __H ['[*H]]] +[def __O ['[*O]]] +[def __R3 ['[*'''R3''']]] +[def __R4 ['[*'''R4''']]] +[def __octulple ('''α,β,γ,δ,ε,ζ,η,θ''')] +[def __oct_formula ['[^o = '''α + βi + γj + δk + εe' + ζi' + ηj' + θk' ''']]] +[def __oct_complex_formula ['[^o = ('''α + βi) + (γ + δi)j + (ε + ζi)e' + (η - θi)j' ''']]] +[def __oct_quat_formula ['[^o = ('''α + βi + γj + δk) + (ε + ζi + ηj - θj)e' ''']]] +[def __oct_not_equal ['[^x(yz) '''≠''' (xy)z]]] + + +[section Octonions] + +[section Overview] + +Octonions, like [link boost_math.quaternions 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 __octulple, +which we can write in the form __oct_formula, 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 __oct_not_equal). +A way of remembering things is by using the following multiplication table: + +[$../../libs/math/octonion/graphics/octonion_blurb17.jpeg] + +Octonions (and their kin) are described in far more details in this other +[@../../libs/math/quaternion/TQE.pdf document] +(with [@../../libs/math/quaternion/TQE_EA.pdf 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). + +[endsect] + +[section Header File] + +The interface and implementation are both supplied by the header file +[@../../boost/math/octonion.hpp octonion.hpp]. + +[endsect] + +[section Synopsis] + + namespace boost{ namespace math{ + + template class ``[link boost_math.octonions.template_class_octonion octonion]``; + template<> class ``[link boost_math.octonions.octonion_specializations octonion]``; + template<> class ``[link boost_math.octonion_double octonion]``; + template<> class ``[link boost_math.octonion_long_double octonion]``; + + // operators + + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_addition_operators operator +]`` (T const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_addition_operators operator +]`` (octonion const & lhs, T const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_addition_operators operator +]`` (::std::complex const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_addition_operators operator +]`` (octonion const & lhs, ::std::complex const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_addition_operators operator +]`` (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_addition_operators operator +]`` (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_addition_operators operator +]`` (octonion const & lhs, octonion const & rhs); + + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_subtraction_operators operator -]`` (T const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_subtraction_operators operator -]`` (octonion const & lhs, T const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_subtraction_operators operator -]`` (::std::complex const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_subtraction_operators operator -]`` (octonion const & lhs, ::std::complex const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_subtraction_operators operator -]`` (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_subtraction_operators operator -]`` (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_subtraction_operators operator -]`` (octonion const & lhs, octonion const & rhs); + + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_multiplication_operators operator *]`` (T const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_multiplication_operators operator *]`` (octonion const & lhs, T const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_multiplication_operators operator *]`` (::std::complex const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_multiplication_operators operator *]`` (octonion const & lhs, ::std::complex const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_multiplication_operators operator *]`` (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_multiplication_operators operator *]`` (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_multiplication_operators operator *]`` (octonion const & lhs, octonion const & rhs); + + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_division_operators operator /]`` (T const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_division_operators operator /]`` (octonion const & lhs, T const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_division_operators operator /]`` (::std::complex const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_division_operators operator /]`` (octonion const & lhs, ::std::complex const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_division_operators operator /]`` (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_division_operators operator /]`` (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.binary_division_operators operator /]`` (octonion const & lhs, octonion const & rhs); + + template octonion ``[link boost_math.octonions.octonion_non_member_operators.unary_plus_and_minus_operators operator +]`` (octonion const & o); + template octonion ``[link boost_math.octonions.octonion_non_member_operators.unary_plus_and_minus_operators operator -]`` (octonion const & o); + + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_equality_operators operator ==]`` (T const & lhs, octonion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_equality_operators operator ==]`` (octonion const & lhs, T const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_equality_operators operator ==]`` (::std::complex const & lhs, octonion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_equality_operators operator ==]`` (octonion const & lhs, ::std::complex const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_equality_operators operator ==]`` (::boost::math::quaternion const & lhs, octonion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_equality_operators operator ==]`` (octonion const & lhs, ::boost::math::quaternion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_equality_operators operator ==]`` (octonion const & lhs, octonion const & rhs); + + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_inequality_operators operator !=]`` (T const & lhs, octonion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_inequality_operators operator !=]`` (octonion const & lhs, T const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_inequality_operators operator !=]`` (::std::complex const & lhs, octonion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_inequality_operators operator !=]`` (octonion const & lhs, ::std::complex const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_inequality_operators operator !=]`` (::boost::math::quaternion const & lhs, octonion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_inequality_operators operator !=]`` (octonion const & lhs, ::boost::math::quaternion const & rhs); + template bool ``[link boost_math.octonions.octonion_non_member_operators.binary_inequality_operators operator !=]`` (octonion const & lhs, octonion const & rhs); + + template + ::std::basic_istream & ``[link boost_math.octonions.octonion_non_member_operators.stream_extractor operator >>]`` (::std::basic_istream & is, octonion & o); + + template + ::std::basic_ostream & ``[link boost_math.octonions.octonion_non_member_operators.stream_inserter operator <<]`` (::std::basic_ostream & os, octonion const & o); + + // values + + template T ``[link boost_math.octonions.octonion_value_operations.real_and_unreal real]``(octonion const & o); + template octonion ``[link boost_math.octonions.octonion_value_operations.real_and_unreal unreal]``(octonion const & o); + + template T ``[link boost_math.octonions.octonion_value_operations.sup sup]``(octonion const & o); + template T ``[link boost_math.octonions.octonion_value_operations.l1 l1]``(octonionconst & o); + template T ``[link boost_math.octonions.octonion_value_operations.abs abs]``(octonion const & o); + template T ``[link boost_math.octonions.octonion_value_operations.norm norm]``(octonionconst & o); + template octonion ``[link boost_math.octonions.octonion_value_operations.conj conj]``(octonion const & o); + + template octonion ``[link boost_math.octonions.quaternion_creation_functions 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 octonion ``[link boost_math.octonions.quaternion_creation_functions 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 octonion ``[link boost_math.octonions.quaternion_creation_functions 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 octonion ``[link boost_math.octonions.octonions_transcendentals.exp exp]``(octonion const & o); + template octonion ``[link boost_math.octonions.octonions_transcendentals.cos cos]``(octonion const & o); + template octonion ``[link boost_math.octonions.octonions_transcendentals.sin sin]``(octonion const & o); + template octonion ``[link boost_math.octonions.octonions_transcendentals.tan tan]``(octonion const & o); + template octonion ``[link boost_math.octonions.octonions_transcendentals.cosh cosh]``(octonion const & o); + template octonion ``[link boost_math.octonions.octonions_transcendentals.sinh sinh]``(octonion const & o); + template octonion ``[link boost_math.octonions.octonions_transcendentals.tanh tanh]``(octonion const & o); + + template octonion ``[link boost_math.octonions.octonions_transcendentals.pow pow]``(octonion const & o, int n); + + } } // namespaces + +[endsect] + +[section Template Class octonion] + + namespace boost{ namespace math { + + template + class octonion + { + public: + typedef T value_type; + + explicit ``[link boost_math.octonions.octonion_member_functions.constructors 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 ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(::std::complex const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(::boost::math::quaternion const & q0, ::boost::math::quaternion const & q1 = ::boost::math::quaternion()); + template + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(octonion const & a_recopier); + + T ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts real]``() const; + octonion ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts unreal]``() const; + + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_1]``() const; + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_2]``() const; + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_3]``() const; + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_4]``() const; + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_5]``() const; + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_6]``() const; + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_7]``() const; + T ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_8]``() const; + + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_1]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_2]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_3]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_4]``() const; + + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_1]``() const; + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_2]``() const; + + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (T const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::std::complex const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::boost::math::quaternion const & a_affecter); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (T const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (T const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (T const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (T const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (octonion const & rhs); + }; + + } } // namespaces + +[endsect] + +[section Octonion Specializations] + + namespace boost{ namespace math{ + + template<> + class octonion + { + public: + typedef float value_type; + + explicit ``[link boost_math.octonions.octonion_member_functions.constructors 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 ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(::std::complex const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(::boost::math::quaternion const & q0, ::boost::math::quaternion const & q1 = ::boost::math::quaternion()); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(octonion const & a_recopier); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(octonion const & a_recopier); + + float ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts real]``() const; + octonion ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts unreal]``() const; + + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_1]``() const; + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_2]``() const; + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_3]``() const; + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_4]``() const; + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_5]``() const; + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_6]``() const; + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_7]``() const; + float ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_8]``() const; + + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_1]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_2]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_3]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_4]``() const; + + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_1]``() const; + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_2]``() const; + + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (float const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::std::complex const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::boost::math::quaternion const & a_affecter); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (float const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (float const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (float const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (float const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (octonion const & rhs); + }; + +[#boost_math.octonion_double] + + template<> + class octonion + { + public: + typedef double value_type; + + explicit ``[link boost_math.octonions.octonion_member_functions.constructors 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 ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(::std::complex const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(::boost::math::quaternion const & q0, ::boost::math::quaternion const & q1 = ::boost::math::quaternion()); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(octonion const & a_recopier); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(octonion const & a_recopier); + + double ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts real]``() const; + octonion ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts unreal]``() const; + + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_1]``() const; + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_2]``() const; + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_3]``() const; + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_4]``() const; + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_5]``() const; + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_6]``() const; + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_7]``() const; + double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_8]``() const; + + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_1]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_2]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_3]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_4]``() const; + + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_1]``() const; + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_2]``() const; + + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (double const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::std::complex const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::boost::math::quaternion const & a_affecter); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (octonion const & rhs); + }; + +[#boost_math.octonion_long_double] + + template<> + class octonion + { + public: + typedef long double value_type; + + explicit ``[link boost_math.octonions.octonion_member_functions.constructors 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 ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``( ::std::complex const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``( ::boost::math::quaternion const & q0, ::boost::math::quaternion const & z1 = ::boost::math::quaternion()); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(octonion const & a_recopier); + explicit ``[link boost_math.octonions.octonion_member_functions.constructors octonion]``(octonion const & a_recopier); + + long double ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts real]``() const; + octonion ``[link boost_math.octonions.octonion_member_functions.real_and_unreal_parts unreal]``() const; + + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_1]``() const; + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_2]``() const; + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_3]``() const; + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_4]``() const; + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_5]``() const; + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_6]``() const; + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_7]``() const; + long double ``[link boost_math.octonions.octonion_member_functions.individual_real_components R_component_8]``() const; + + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_1]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_2]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_3]``() const; + ::std::complex ``[link boost_math.octonions.octonion_member_functions.individual_complex_components C_component_4]``() const; + + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_1]``() const; + ::boost::math::quaternion ``[link boost_math.octonions.octonion_member_functions.individual_quaternion_components H_component_2]``() const; + + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (octonion const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (long double const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::std::complex const & a_affecter); + octonion & ``[link boost_math.octonions.octonion_member_functions.assignment_operators operator =]`` (::boost::math::quaternion const & a_affecter); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (long double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator +=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (long double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator -=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (long double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator *=]`` (octonion const & rhs); + + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (long double const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::std::complex const & rhs); + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (::boost::math::quaternion const & rhs); + template + octonion & ``[link boost_math.octonions.octonion_member_functions.other_member_operators operator /=]`` (octonion const & rhs); + }; + + } } // namespaces + +[endsect] + +[section Octonion Member Typedefs] + +[*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. + +[endsect] + +[section Octonion Member Functions] + +[h3 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 const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit octonion(::boost::math::quaternion const & q0, ::boost::math::quaternion const & q1 = ::boost::math::quaternion()); + template + explicit octonion(octonion 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 const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit octonion(::boost::math::quaternion const & q0, ::boost::math::quaternion const & q1 = ::boost::math::quaternion()); + explicit octonion(octonion const & a_recopier); + explicit octonion(octonion 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 const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit octonion(::boost::math::quaternion const & q0, ::boost::math::quaternion const & q1 = ::boost::math::quaternion()); + explicit octonion(octonion const & a_recopier); + explicit octonion(octonion 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 const & z0, ::std::complex const & z1 = ::std::complex(), ::std::complex const & z2 = ::std::complex(), ::std::complex const & z3 = ::std::complex()); + explicit octonion(::boost::math::quaternion const & q0, ::boost::math::quaternion const & q1 = ::boost::math::quaternion()); + explicit octonion(octonion const & a_recopier); + explicit octonion(octonion 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. + +[h3 Other member functions] + +[h4 Real and Unreal Parts] + + T real() const; + octonion 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. + +[h4 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. + +[h4 Individual Complex Components] + + ::std::complex C_component_1() const; + ::std::complex C_component_2() const; + ::std::complex C_component_3() const; + ::std::complex 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 __oct_formula we also have __oct_complex_formula +(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')]]. + +[h4 Individual Quaternion Components] + + ::boost::math::quaternion H_component_1() const; + ::boost::math::quaternion H_component_2() const; + +Likewise, for any octonion __oct_formula we also have __oct_quat_formula, 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. + +[h3 Octonion Member Operators] +[h4 Assignment Operators] + + octonion & operator = (octonion const & a_affecter); + template + octonion & operator = (octonion const & a_affecter); + octonion & operator = (T const & a_affecter); + octonion & operator = (::std::complex const & a_affecter); + octonion & operator = (::boost::math::quaternion 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. + +[h4 Other Member Operators] + + octonion & operator += (T const & rhs) + octonion & operator += (::std::complex const & rhs); + octonion & operator += (::boost::math::quaternion const & rhs); + template + octonion & operator += (octonion 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 & operator -= (T const & rhs) + octonion & operator -= (::std::complex const & rhs); + octonion & operator -= (::boost::math::quaternion const & rhs); + template + octonion & operator -= (octonion 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 & operator *= (T const & rhs) + octonion & operator *= (::std::complex const & rhs); + octonion & operator *= (::boost::math::quaternion const & rhs); + template + octonion & operator *= (octonion 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 & operator /= (T const & rhs) + octonion & operator /= (::std::complex const & rhs); + octonion & operator /= (::boost::math::quaternion const & rhs); + template + octonion & operator /= (octonion 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. + +[endsect] + +[section Octonion Non-Member Operators] + +[h4 Unary Plus and Minus Operators] + + template octonion operator + (octonion const & o); + +This unary operator simply returns o. + + template octonion operator - (octonion const & o); + +This unary operator returns the opposite of o. + +[h4 Binary Addition Operators] + + template octonion operator + (T const & lhs, octonion const & rhs); + template octonion operator + (octonion const & lhs, T const & rhs); + template octonion operator + (::std::complex const & lhs, octonion const & rhs); + template octonion operator + (octonion const & lhs, ::std::complex const & rhs); + template octonion operator + (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion operator + (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion operator + (octonion const & lhs, octonion const & rhs); + +These operators return `octonion(lhs) += rhs`. + +[h4 Binary Subtraction Operators] + + template octonion operator - (T const & lhs, octonion const & rhs); + template octonion operator - (octonion const & lhs, T const & rhs); + template octonion operator - (::std::complex const & lhs, octonion const & rhs); + template octonion operator - (octonion const & lhs, ::std::complex const & rhs); + template octonion operator - (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion operator - (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion operator - (octonion const & lhs, octonion const & rhs); + +These operators return `octonion(lhs) -= rhs`. + +[h4 Binary Multiplication Operators] + + template octonion operator * (T const & lhs, octonion const & rhs); + template octonion operator * (octonion const & lhs, T const & rhs); + template octonion operator * (::std::complex const & lhs, octonion const & rhs); + template octonion operator * (octonion const & lhs, ::std::complex const & rhs); + template octonion operator * (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion operator * (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion operator * (octonion const & lhs, octonion const & rhs); + +These operators return `octonion(lhs) *= rhs`. + +[h4 Binary Division Operators] + + template octonion operator / (T const & lhs, octonion const & rhs); + template octonion operator / (octonion const & lhs, T const & rhs); + template octonion operator / (::std::complex const & lhs, octonion const & rhs); + template octonion operator / (octonion const & lhs, ::std::complex const & rhs); + template octonion operator / (::boost::math::quaternion const & lhs, octonion const & rhs); + template octonion operator / (octonion const & lhs, ::boost::math::quaternion const & rhs); + template octonion operator / (octonion const & lhs, octonion const & rhs); + +These operators return `octonion(lhs) /= rhs`. It is of course still an +error to divide by zero... + +[h4 Binary Equality Operators] + + template bool operator == (T const & lhs, octonion const & rhs); + template bool operator == (octonion const & lhs, T const & rhs); + template bool operator == (::std::complex const & lhs, octonion const & rhs); + template bool operator == (octonion const & lhs, ::std::complex const & rhs); + template bool operator == (::boost::math::quaternion const & lhs, octonion const & rhs); + template bool operator == (octonion const & lhs, ::boost::math::quaternion const & rhs); + template bool operator == (octonion const & lhs, octonion const & rhs); + +These return true if and only if the four components of `octonion(lhs)` +are equal to their counterparts in `octonion(rhs)`. As with any +floating-type entity, this is essentially meaningless. + +[h4 Binary Inequality Operators] + + template bool operator != (T const & lhs, octonion const & rhs); + template bool operator != (octonion const & lhs, T const & rhs); + template bool operator != (::std::complex const & lhs, octonion const & rhs); + template bool operator != (octonion const & lhs, ::std::complex const & rhs); + template bool operator != (::boost::math::quaternion const & lhs, octonion const & rhs); + template bool operator != (octonion const & lhs, ::boost::math::quaternion const & rhs); + template bool operator != (octonion const & lhs, octonion const & rhs); + +These return true if and only if `octonion(lhs) == octonion(rhs)` +is false. As with any floating-type entity, this is essentially meaningless. + +[h4 Stream Extractor] + + template + ::std::basic_istream & operator >> (::std::basic_istream & is, octonion & 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`. + +[h4 Stream Inserter] + + template + ::std::basic_ostream & operator << (::std::basic_ostream & os, octonion const & o); + +Inserts the octonion `o` onto the stream `os` as if it were implemented as follows: + + template + ::std::basic_ostream & operator << ( ::std::basic_ostream & os, + octonion const & o) + { + ::std::basic_ostringstream 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(); + } + +[endsect] + +[section Octonion Value Operations] + +[h4 Real and Unreal] + + template T real(octonion const & o); + template octonion unreal(octonion const & o); + +These return `o.real()` and `o.unreal()` respectively. + +[h4 conj] + + template octonion conj(octonion const & o); + +This returns the conjugate of the octonion. + +[h4 sup] + + template T sup(octonion const & o); + +This return the sup norm (the greatest among +`abs(o.R_component_1())...abs(o.R_component_8()))` of the octonion. + +[h4 l1] + + template T l1(octonion const & o); + +This return the l1 norm (`abs(o.R_component_1())+...+abs(o.R_component_8())`) +of the octonion. + +[h4 abs] + + template T abs(octonion const & o); + +This return the magnitude (Euclidian norm) of the octonion. + +[h4 norm] + + template T norm(octonionconst & 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. + +[endsect] + +[section Quaternion Creation Functions] + + template octonion 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 octonion 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 octonion 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 __R3). 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 __R3, 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. + +[endsect] + +[section Octonions Transcendentals] + +There is no `log` or `sqrt` provided for octonions in this implementation, +and `pow` is likewise restricted to integral powers of the exponent. +There are several reasons to this: on the one hand, the equivalent of +analytic continuation for octonions ("branch cuts") remains to be +investigated thoroughly (by me, at any rate...), and we wish to avoid +the nonsense introduced in the standard by exponentiations of +complexes by complexes (which is well defined, but not in the standard...). +Talking of nonsense, saying that `pow(0,0)` is "implementation defined" is +just plain brain-dead... + +We do, however provide several transcendentals, chief among which is +the exponential. That it allows for a "closed formula" is a result +of the author (the existence and definition of the exponential, on the +octonions among others, on the other hand, is a few centuries old). +Basically, any converging power series with real coefficients which +allows for a closed formula in __C can be transposed to __O. More +transcendentals of this type could be added in a further revision upon +request. It should be noted that it is these functions which force the +dependency upon the +[@../../boost/math/special_functions/sinc.hpp boost/math/special_functions/sinc.hpp] +and the +[@../../boost/math/special_functions/sinhc.hpp boost/math/special_functions/sinhc.hpp] +headers. + +[h4 exp] + + template + octonion exp(octonion const & o); + +Computes the exponential of the octonion. + +[h4 cos] + + template + octonion cos(octonion const & o); + +Computes the cosine of the octonion + +[h4 sin] + + template + octonion sin(octonion const & o); + +Computes the sine of the octonion. + +[h4 tan] + + template + octonion tan(octonion const & o); + +Computes the tangent of the octonion. + +[h4 cosh] + + template + octonion cosh(octonion const & o); + +Computes the hyperbolic cosine of the octonion. + +[h4 sinh] + + template + octonion sinh(octonion const & o); + +Computes the hyperbolic sine of the octonion. + +[h4 tanh] + + template + octonion tanh(octonion const & o); + +Computes the hyperbolic tangent of the octonion. + +[h4 pow] + + template + octonion pow(octonion const & o, int n); + +Computes the n-th power of the octonion q. + +[endsect] + +[section Test Program] + +The [@../../libs/math/octonion/octonion_test.cpp octonion_test.cpp] +test program tests octonions specialisations for float, double and long double +([@../../libs/math/octonion/output.txt sample output]). + +If you define the symbol BOOST_OCTONION_TEST_VERBOSE, you will get additional +output ([@../../libs/math/octonion/output_more.txt verbose output]); this will +only be helpfull if you enable message output at the same time, of course +(by uncommenting the relevant line in the test or by adding --log_level=messages +to your command line,...). In that case, and if you are running interactively, +you may in addition define the symbol BOOST_INTERACTIVE_TEST_INPUT_ITERATOR to +interactively test the input operator with input of your choice from the +standard input (instead of hard-coding it in the test). + +[endsect] + +[section Acknowledgements] + +The mathematical text has been typeset with +[@http://www.nisus-soft.com/ Nisus Writer]. +Jens Maurer has helped with portability and standard adherence, and was the +Review Manager for this library. More acknowledgements in the +History section. Thank you to all who contributed to the discussion about this library. + +[endsect] + +[section History] + +* 1.5.8 - 17/12/2005: Converted documentation to Quickbook Format. +* 1.5.7 - 25/02/2003: transitionned to the unit test framework; now included by the library header (rather than the test files), via . +* 1.5.6 - 15/10/2002: Gcc2.95.x and stlport on linux compatibility by Alkis Evlogimenos (alkis@routescience.com). +* 1.5.5 - 27/09/2002: Microsoft VCPP 7 compatibility, by Michael Stevens (michael@acfr.usyd.edu.au); requires the /Za compiler option. +* 1.5.4 - 19/09/2002: fixed problem with multiple inclusion (in different translation units); attempt at an improved compatibility with Microsoft compilers, by Michael Stevens (michael@acfr.usyd.edu.au) and Fredrik Blomqvist; other compatibility fixes. +* 1.5.3 - 01/02/2002: bugfix and Gcc 2.95.3 compatibility by Douglas Gregor (gregod@cs.rpi.edu). +* 1.5.2 - 07/07/2001: introduced namespace math. +* 1.5.1 - 07/06/2001: (end of Boost review) now includes and instead of ; corrected bug in sin (Daryle Walker); removed check for self-assignment (Gary Powel); made converting functions explicit (Gary Powel); added overflow guards for division operators and abs (Peter Schmitteckert); added sup and l1; used Vesa Karvonen's CPP metaprograming technique to simplify code. +* 1.5.0 - 23/03/2001: boostification, inlining of all operators except input, output and pow, fixed exception safety of some members (template version). +* 1.4.0 - 09/01/2001: added tan and tanh. +* 1.3.1 - 08/01/2001: cosmetic fixes. +* 1.3.0 - 12/07/2000: pow now uses Maarten Hilferink's (mhilferink@tip.nl) algorithm. +* 1.2.0 - 25/05/2000: fixed the division operators and output; changed many signatures. +* 1.1.0 - 23/05/2000: changed sinc into sinc_pi; added sin, cos, sinh, cosh. +* 1.0.0 - 10/08/1999: first public version. + +[endsect] + +[section To Do] + +* Improve testing. +* Rewrite input operatore using Spirit (creates a dependency). +* Put in place an Expression Template mechanism (perhaps borrowing from uBlas). + +[endsect] + +[endsect] diff --git a/doc/math-quaternion.qbk b/doc/math-quaternion.qbk new file mode 100644 index 000000000..4971c35b9 --- /dev/null +++ b/doc/math-quaternion.qbk @@ -0,0 +1,899 @@ + +[def __R ['[*R]]] +[def __C ['[*C]]] +[def __H ['[*H]]] +[def __O ['[*O]]] +[def __R3 ['[*'''R3''']]] +[def __R4 ['[*'''R4''']]] +[def __quadrulple ('''α,β,γ,δ''')] +[def __quat_formula ['[^q = '''α + βi + γj + δk''']]] +[def __quat_complex_formula ['[^q = ('''α + βi) + (γ + δi)j''' ]]] +[def __not_equal ['[^xy '''≠''' yx]]] + + +[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 [@../../libs/math/quaternion/TQE.pdf document] +(with [@../../libs/math/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 class ``[link boost_math.quaternions.template_class_quaternion quaternion]``; + template<> class ``[link boost_math.quaternions.quaternion_specializations quaternion]``; + template<> class ``[link boost_math.quaternion_double quaternion]``; + template<> class ``[link boost_math.quaternion_long_double quaternion]``; + + // operators + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_addition_operators operator +]`` (T const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_addition_operators operator +]`` (quaternion const & lhs, T const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_addition_operators operator +]`` (::std::complex const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_addition_operators operator +]`` (quaternion const & lhs, ::std::complex const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_addition_operators operator +]`` (quaternion const & lhs, quaternion const & rhs); + + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_subtraction_operators operator -]`` (T const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_subtraction_operators operator -]`` (quaternion const & lhs, T const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_subtraction_operators operator -]`` (::std::complex const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_subtraction_operators operator -]`` (quaternion const & lhs, ::std::complex const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_subtraction_operators operator -]`` (quaternion const & lhs, quaternion const & rhs); + + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_multiplication_operators operator *]`` (T const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_multiplication_operators operator *]`` (quaternion const & lhs, T const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_multiplication_operators operator *]`` (::std::complex const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_multiplication_operators operator *]`` (quaternion const & lhs, ::std::complex const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_multiplication_operators operator *]`` (quaternion const & lhs, quaternion const & rhs); + + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_division_operators operator /]`` (T const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_division_operators operator /]`` (quaternion const & lhs, T const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_division_operators operator /]`` (::std::complex const & lhs, quaternion const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_division_operators operator /]`` (quaternion const & lhs, ::std::complex const & rhs); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.binary_division_operators operator /]`` (quaternion const & lhs, quaternion const & rhs); + + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.unary_plus operator +]`` (quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_non_member_operators.unary_minus operator -]`` (quaternion const & q); + + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.equality_operators operator ==]`` (T const & lhs, quaternion const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.equality_operators operator ==]`` (quaternion const & lhs, T const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.equality_operators operator ==]`` (::std::complex const & lhs, quaternion const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.equality_operators operator ==]`` (quaternion const & lhs, ::std::complex const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.equality_operators operator ==]`` (quaternion const & lhs, quaternion const & rhs); + + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.inequality_operators operator !=]`` (T const & lhs, quaternion const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.inequality_operators operator !=]`` (quaternion const & lhs, T const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.inequality_operators operator !=]`` (::std::complex const & lhs, quaternion const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.inequality_operators operator !=]`` (quaternion const & lhs, ::std::complex const & rhs); + template bool ``[link boost_math.quaternions.quaternion_non_member_operators.inequality_operators operator !=]`` (quaternion const & lhs, quaternion const & rhs); + + template + ::std::basic_istream& ``[link boost_math.quaternions.quaternion_non_member_operators.stream_extractor operator >>]`` (::std::basic_istream & is, quaternion & q); + + template + ::std::basic_ostream& operator ``[link boost_math.quaternions.quaternion_non_member_operators.stream_inserter operator <<]`` (::std::basic_ostream & os, quaternion const & q); + + // values + template T ``[link boost_math.quaternions.quaternion_value_operations.real_and_unreal real]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_value_operations.real_and_unreal unreal]``(quaternion const & q); + + template T ``[link boost_math.quaternions.quaternion_value_operations.sup sup]``(quaternion const & q); + template T ``[link boost_math.quaternions.quaternion_value_operations.l1 l1]``(quaternion const & q); + template T ``[link boost_math.quaternions.quaternion_value_operations.abs abs]``(quaternion const & q); + template T ``[link boost_math.quaternions.quaternion_value_operations.norm norm]``(quaternionconst & q); + template quaternion ``[link boost_math.quaternions.quaternion_value_operations.conj conj]``(quaternion const & q); + + template quaternion ``[link boost_math.quaternions.creation_spherical spherical]``(T const & rho, T const & theta, T const & phi1, T const & phi2); + template quaternion ``[link boost_math.quaternions.creation_semipolar semipolar]``(T const & rho, T const & alpha, T const & theta1, T const & theta2); + template quaternion ``[link boost_math.quaternions.creation_multipolar multipolar]``(T const & rho1, T const & theta1, T const & rho2, T const & theta2); + template quaternion ``[link boost_math.quaternions.creation_cylindrospherical cylindrospherical]``(T const & t, T const & radius, T const & longitude, T const & latitude); + template quaternion ``[link boost_math.quaternions.creation_cylindrical cylindrical]``(T const & r, T const & angle, T const & h1, T const & h2); + + // transcendentals + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.exp exp]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.cos cos]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.sin sin]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.tan tan]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.cosh cosh]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.sinh sinh]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.tanh tanh]``(quaternion const & q); + template quaternion ``[link boost_math.quaternions.quaternion_transcendentals.pow pow]``(quaternion const & q, int n); + + } // namespace math + } // namespace boost + +[endsect] + +[section Template Class quaternion] + + namespace boost{ namespace math{ + + template + class quaternion + { + public: + + typedef T ``[link boost_math.quaternions.quaternion_member_typedefs value_type]``; + + explicit ``[link boost_math.quaternions.quaternion_member_functions.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_math.quaternions.quaternion_member_functions.constructors quaternion]``(::std::complex const & z0, ::std::complex const & z1 = ::std::complex()); + template + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(quaternion const & a_recopier); + + T ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts real]``() const; + quaternion ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts unreal]``() const; + T ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_1]``() const; + T ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_2]``() const; + T ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_3]``() const; + T ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_4]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_1]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_2]``() const; + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(T const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(::std::complex const & a_affecter); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(T const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(T const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(T const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(T const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(quaternion const & rhs); + }; + + } // namespace math + } // namespace boost + +[endsect] + +[section Quaternion Specializations] + + namespace boost{ namespace math{ + + template<> + class quaternion + { + public: + typedef float ``[link boost_math.quaternions.quaternion_member_typedefs value_type]``; + + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(float const & requested_a = 0.0f, float const & requested_b = 0.0f, float const & requested_c = 0.0f, float const & requested_d = 0.0f); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(::std::complex const & z0, ::std::complex const & z1 = ::std::complex()); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(quaternion const & a_recopier); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(quaternion const & a_recopier); + + float ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts real]``() const; + quaternion ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts unreal]``() const; + float ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_1]``() const; + float ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_2]``() const; + float ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_3]``() const; + float ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_4]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_1]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_2]``() const; + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(float const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(::std::complex const & a_affecter); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(float const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(float const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(float const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(float const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(quaternion const & rhs); + }; + +[#boost_math.quaternion_double] + + template<> + class quaternion + { + public: + typedef double ``[link boost_math.quaternions.quaternion_member_typedefs value_type]``; + + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(double const & requested_a = 0.0, double const & requested_b = 0.0, double const & requested_c = 0.0, double const & requested_d = 0.0); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(::std::complex const & z0, ::std::complex const & z1 = ::std::complex()); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(quaternion const & a_recopier); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(quaternion const & a_recopier); + + double ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts real]``() const; + quaternion ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts unreal]``() const; + double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_1]``() const; + double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_2]``() const; + double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_3]``() const; + double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_4]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_1]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_2]``() const; + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(double const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(::std::complex const & a_affecter); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(quaternion const & rhs); + }; + +[#boost_math.quaternion_long_double] + + template<> + class quaternion + { + public: + typedef long double ``[link boost_math.quaternions.quaternion_member_typedefs value_type]``; + + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(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); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(::std::complex const & z0, ::std::complex const & z1 = ::std::complex()); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(quaternion const & a_recopier); + explicit ``[link boost_math.quaternions.quaternion_member_functions.constructors quaternion]``(quaternion const & a_recopier); + + long double ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts real]``() const; + quaternion ``[link boost_math.quaternions.quaternion_member_functions.real_and_unreal_parts unreal]``() const; + long double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_1]``() const; + long double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_2]``() const; + long double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_3]``() const; + long double ``[link boost_math.quaternions.quaternion_member_functions.individual_real_components R_component_4]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_1]``() const; + ::std::complex ``[link boost_math.quaternions.quaternion_member_functions.individual_complex__components C_component_2]``() const; + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(quaternion const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(long double const & a_affecter); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.assignment_operators operator = ]``(::std::complex const & a_affecter); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(long double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.addition_operators operator += ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(long double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.subtraction_operators operator -= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(long double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.multiplication_operators operator *= ]``(quaternion const & rhs); + + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(long double const & rhs); + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(::std::complex const & rhs); + template + quaternion& ``[link boost_math.quaternions.quaternion_member_functions.division_operators operator /= ]``(quaternion const & rhs); + }; + + } // namespace math + } // namespace boost + +[endsect] + +[section Quaternion Member Typedefs] + +[*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. + +[endsect] + +[section Quaternion Member Functions] +[h3 Constructors] + +Template version: + + explicit quaternion(T const & requested_a = T(), T const & requested_b = T(), T const & requested_c = T(), T const & requested_d = T()); + explicit quaternion(::std::complex const & z0, ::std::complex const & z1 = ::std::complex()); + template + explicit quaternion(quaternion const & a_recopier); + +Float specialization version: + + explicit quaternion(float const & requested_a = 0.0f, float const & requested_b = 0.0f, float const & requested_c = 0.0f, float const & requested_d = 0.0f); + explicit quaternion(::std::complex const & z0,::std::complex const & z1 = ::std::complex()); + explicit quaternion(quaternion const & a_recopier); + explicit quaternion(quaternion const & a_recopier); + +Double specialization version: + + explicit quaternion(double const & requested_a = 0.0, double const & requested_b = 0.0, double const & requested_c = 0.0, double const & requested_d = 0.0); + explicit quaternion(::std::complex const & z0, ::std::complex const & z1 = ::std::complex()); + explicit quaternion(quaternion const & a_recopier); + explicit quaternion(quaternion const & a_recopier); + +Long double specialization version: + + explicit quaternion(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); + explicit quaternion( ::std::complex const & z0, ::std::complex const & z1 = ::std::complex()); + explicit quaternion(quaternion const & a_recopier); + explicit quaternion(quaternion 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 four base type arguments. A constructor is also provided to +build quaternions from one or two complex numbers 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. + +[h3 Other member functions] +[h4 Real and Unreal Parts] + + T real() const; + quaternion unreal() const; + +Like complex number, quaternions 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 quaternion, +and usually nothing simpler (as opposed to the complex number case). +These are returned by the first two functions. + +[h4 Individual Real Components] + + T R_component_1() const; + T R_component_2() const; + T R_component_3() const; + T R_component_4() const; + +A quaternion having four real components, these are returned by these four +functions. Hence real and R_component_1 return the same value. + +[h4 Individual Complex Components] + + ::std::complex C_component_1() const; + ::std::complex C_component_2() const; + +A quaternion likewise has two complex components, and as we have seen above, +for any quaternion __quat_formula we also have __quat_complex_formula. These functions return them. +The real part of `q.C_component_1()` is the same as `q.real()`. + +[h3 Quaternion Member Operators] +[h4 Assignment Operators] + + quaternion& operator = (quaternion const & a_affecter); + template + quaternion& operator = (quaternion const& a_affecter); + quaternion& operator = (T const& a_affecter); + quaternion& operator = (::std::complex 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. + +[h4 Addition Operators] + + quaternion& operator += (T const & rhs) + quaternion& operator += (::std::complex const & rhs); + template + quaternion& operator += (quaternion 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. + +[h4 Subtraction Operators] + + quaternion& operator -= (T const & rhs) + quaternion& operator -= (::std::complex const & rhs); + template + quaternion& operator -= (quaternion 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. + +[h4 Multiplication Operators] + + quaternion& operator *= (T const & rhs) + quaternion& operator *= (::std::complex const & rhs); + template + quaternion& operator *= (quaternion const & rhs); + +These perform the mathematical operation `(*this)*rhs` [*in this order] +(order is important as multiplication is not commutative for quaternions) +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. + +[h4 Division Operators] + + quaternion& operator /= (T const & rhs) + quaternion& operator /= (::std::complex const & rhs); + template + quaternion& operator /= (quaternion const & rhs); + +These perform the mathematical operation `(*this)*inverse_of(rhs)` [*in this +order] (order is important as multiplication is not commutative for quaternions) +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. + +[endsect] +[section Quaternion Non-Member Operators] + +[h4 Unary Plus] + + template + quaternion operator + (quaternion const & q); + +This unary operator simply returns q. + +[h4 Unary Minus] + + template + quaternion operator - (quaternion const & q); + +This unary operator returns the opposite of q. + +[h4 Binary Addition Operators] + + template quaternion operator + (T const & lhs, quaternion const & rhs); + template quaternion operator + (quaternion const & lhs, T const & rhs); + template quaternion operator + (::std::complex const & lhs, quaternion const & rhs); + template quaternion operator + (quaternion const & lhs, ::std::complex const & rhs); + template quaternion operator + (quaternion const & lhs, quaternion const & rhs); + +These operators return `quaternion(lhs) += rhs`. + +[h4 Binary Subtraction Operators] + + template quaternion operator - (T const & lhs, quaternion const & rhs); + template quaternion operator - (quaternion const & lhs, T const & rhs); + template quaternion operator - (::std::complex const & lhs, quaternion const & rhs); + template quaternion operator - (quaternion const & lhs, ::std::complex const & rhs); + template quaternion operator - (quaternion const & lhs, quaternion const & rhs); + +These operators return `quaternion(lhs) -= rhs`. + +[h4 Binary Multiplication Operators] + + template quaternion operator * (T const & lhs, quaternion const & rhs); + template quaternion operator * (quaternion const & lhs, T const & rhs); + template quaternion operator * (::std::complex const & lhs, quaternion const & rhs); + template quaternion operator * (quaternion const & lhs, ::std::complex const & rhs); + template quaternion operator * (quaternion const & lhs, quaternion const & rhs); + +These operators return `quaternion(lhs) *= rhs`. + +[h4 Binary Division Operators] + + template quaternion operator / (T const & lhs, quaternion const & rhs); + template quaternion operator / (quaternion const & lhs, T const & rhs); + template quaternion operator / (::std::complex const & lhs, quaternion const & rhs); + template quaternion operator / (quaternion const & lhs, ::std::complex const & rhs); + template quaternion operator / (quaternion const & lhs, quaternion const & rhs); + +These operators return `quaternion(lhs) /= rhs`. It is of course still an +error to divide by zero... + +[h4 Equality Operators] + + template bool operator == (T const & lhs, quaternion const & rhs); + template bool operator == (quaternion const & lhs, T const & rhs); + template bool operator == (::std::complex const & lhs, quaternion const & rhs); + template bool operator == (quaternion const & lhs, ::std::complex const & rhs); + template bool operator == (quaternion const & lhs, quaternion const & rhs); + +These return true if and only if the four components of `quaternion(lhs)` +are equal to their counterparts in `quaternion(rhs)`. As with any +floating-type entity, this is essentially meaningless. + +[h4 Inequality Operators] + + template bool operator != (T const & lhs, quaternion const & rhs); + template bool operator != (quaternion const & lhs, T const & rhs); + template bool operator != (::std::complex const & lhs, quaternion const & rhs); + template bool operator != (quaternion const & lhs, ::std::complex const & rhs); + template bool operator != (quaternion const & lhs, quaternion const & rhs); + +These return true if and only if `quaternion(lhs) == quaternion(rhs)` is +false. As with any floating-type entity, this is essentially meaningless. + +[h4 Stream Extractor] + + template + ::std::basic_istream& operator >> (::std::basic_istream & is, quaternion & q); + +Extracts a quaternion q of one of the following forms +(with a, b, c and d of type `T`): + +[^a (a), (a,b), (a,b,c), (a,b,c,d) (a,(c)), (a,(c,d)), ((a)), ((a),c), ((a),(c)), ((a),(c,d)), ((a,b)), ((a,b),c), ((a,b),(c)), ((a,b),(c,d))] + +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`. + +The rationale for the list of accepted formats is that either we have a +list of up to four reals, or else we have a couple of complex numbers, +and in that case if it formated as a proper complex number, then it should +be accepted. Thus potential ambiguities are lifted (for instance (a,b) is +(a,b,0,0) and not (a,0,b,0), i.e. it is parsed as a list of two real numbers +and not two complex numbers which happen to have imaginary parts equal to zero). + +[h4 Stream Inserter] + + template + ::std::basic_ostream& operator << (::std::basic_ostream & os, quaternion const & q); + +Inserts the quaternion q onto the stream `os` as if it were implemented as follows: + + template + ::std::basic_ostream& operator << ( + ::std::basic_ostream & os, + quaternion const & q) + { + ::std::basic_ostringstream s; + + s.flags(os.flags()); + s.imbue(os.getloc()); + s.precision(os.precision()); + + s << '(' << q.R_component_1() << ',' + << q.R_component_2() << ',' + << q.R_component_3() << ',' + << q.R_component_4() << ')'; + + return os << s.str(); + } + +[endsect] + +[section Quaternion Value Operations] + +[h4 real and unreal] + + template T real(quaternion const & q); + template quaternion unreal(quaternion const & q); + +These return `q.real()` and `q.unreal()` respectively. + +[h4 conj] + + template quaternion conj(quaternion const & q); + +This returns the conjugate of the quaternion. + +[h4 sup] + +template T sup(quaternion const & q); + +This return the sup norm (the greatest among +`abs(q.R_component_1())...abs(q.R_component_4()))` of the quaternion. + +[h4 l1] + + template T l1(quaternion const & q); + +This return the l1 norm `(abs(q.R_component_1())+...+abs(q.R_component_4()))` +of the quaternion. + +[h4 abs] + + template T abs(quaternion const & q); + +This return the magnitude (Euclidian norm) of the quaternion. + +[h4 norm] + + template T norm(quaternionconst & q); + +This return the (Cayley) norm of the quaternion. +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) quaternions, the Euclidian norm +(also known as magnitude) is the square root of the Cayley norm. + +[endsect] + +[section Quaternion Creation Functions] + + template quaternion spherical(T const & rho, T const & theta, T const & phi1, T const & phi2); + template quaternion semipolar(T const & rho, T const & alpha, T const & theta1, T const & theta2); + template quaternion multipolar(T const & rho1, T const & theta1, T const & rho2, T const & theta2); + template quaternion cylindrospherical(T const & t, T const & radius, T const & longitude, T const & latitude); + template quaternion cylindrical(T const & r, T const & angle, T const & h1, T const & h2); + +These build quaternions in a way similar to the way polar builds complex +numbers, as there is no strict equivalent to polar coordinates for quaternions. + +[#boost_math.quaternions.creation_spherical] `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 __R3). 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. + +[#boost_math.quaternions.creation_cylindrical] `cylindrical` is likewise a simple transposition of the usual +cylindrical coordinates in __R3, 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 quaternion. The third and fourth inputs +are placed into the third and fourth __R components of the quaternion, +respectively. + +[#boost_math.quaternions.creation_multipolar] `multipolar` is yet another simple generalization of polar coordinates. +This time, both __C components of the quaternion are given in polar coordinates. + +[#boost_math.quaternions.creation_cylindrospherical] `cylindrospherical` is specific to quaternions. It is often interesting to +consider __H as the cartesian product of __R by __R3 (the quaternionic +multiplication as then a special form, as given here). This function +therefore builds a quaternion from this representation, with the __R3 +component given in usual __R3 spherical coordinates. + +[#boost_math.quaternions.creation_semipolar] `semipolar` is another generator which is specific to quaternions. +It takes as a first input the magnitude of the quaternion, as a +second input an angle in the range `0` to `+pi/2` such that magnitudes +of the first two __C components of the quaternion are the product of the +first input and the sine and cosine of this angle, respectively, and finally +as third and fourth inputs angles in the range `-pi/2` to `+pi/2` which +represent the arguments of the first and second __C components of +the quaternion, respectively. As usual, nothing untoward happens if +what should be magnitudes are negative numbers or angles are out of their +natural ranges, as symmetries and periodicities kick in. + +In this version of our implementation of quaternions, there is no +analogue of the complex value operation `arg` as the situation is +somewhat more complicated. Unit quaternions are linked both to +rotations in __R3 and in __R4, and the correspondences are not too complicated, +but there is currently a lack of standard (de facto or de jure) matrix +library with which the conversions could work. This should be remedied in +a further revision. In the mean time, an example of how this could be +done is presented here for +[@../../libs/math/quaternion/HSO3.hpp __R3], and here for +[@../../libs/math/quaternion/HSO4.hpp __R4] +([@../../libs/math/quaternion/HSO3SO4.cpp example test file]). + +[endsect] + +[section Quaternion Transcendentals] + +There is no `log` or `sqrt` provided for quaternions in this implementation, +and `pow` is likewise restricted to integral powers of the exponent. +There are several reasons to this: on the one hand, the equivalent of +analytic continuation for quaternions ("branch cuts") remains to be +investigated thoroughly (by me, at any rate...), and we wish to avoid the +nonsense introduced in the standard by exponentiations of complexes by +complexes (which is well defined, but not in the standard...). +Talking of nonsense, saying that `pow(0,0)` is "implementation defined" is just +plain brain-dead... + +We do, however provide several transcendentals, chief among which is the +exponential. This author claims the complete proof of the "closed formula" +as his own, as well as its independant invention (there are claims to prior +invention of the formula, such as one by Professor Shoemake, and it is +possible that the formula had been known a couple of centuries back, but in +absence of bibliographical reference, the matter is pending, awaiting further +investigation; on the other hand, the definition and existence of the +exponential on the quaternions, is of course a fact known for a very long time). +Basically, any converging power series with real coefficients which allows for a +closed formula in __C can be transposed to __H. More transcendentals of this +type could be added in a further revision upon request. It should be +noted that it is these functions which force the dependency upon the +[@../../boost/math/special_functions/sinc.hpp boost/math/special_functions/sinc.hpp] and the +[@../../boost/math/special_functions/sinhc.hpp boost/math/special_functions/sinhc.hpp] headers. + +[h4 exp] + + template quaternion exp(quaternion const & q); + +Computes the exponential of the quaternion. + +[h4 cos] + + template quaternion cos(quaternion const & q); + +Computes the cosine of the quaternion + +[h4 sin] + + template quaternion sin(quaternion const & q); + +Computes the sine of the quaternion. + +[h4 tan] + + template quaternion tan(quaternion const & q); + +Computes the tangent of the quaternion. + +[h4 cosh] + + template quaternion cosh(quaternion const & q); + +Computes the hyperbolic cosine of the quaternion. + +[h4 sinh] + + template quaternion sinh(quaternion const & q); + +Computes the hyperbolic sine of the quaternion. + +[h4 tanh] + + template quaternion tanh(quaternion const & q); + +Computes the hyperbolic tangent of the quaternion. + +[h4 pow] + + template quaternion pow(quaternion const & q, int n); + +Computes the n-th power of the quaternion q. + +[endsect] + +[section Test Program] + +The [@../../libs/math/quaternion/quaternion_test.cpp quaternion_test.cpp] +test program tests quaternions specializations for float, double and long double +([@../../libs/math/quaternion/output.txt sample output], with message output +enabled). + +If you define the symbol BOOST_QUATERNION_TEST_VERBOSE, you will get +additional output ([@../../libs/math/quaternion/output_more.txt verbose output]); +this will only be helpfull if you enable message output at the same time, +of course (by uncommenting the relevant line in the test or by adding +[^--log_level=messages] to your command line,...). In that case, and if you +are running interactively, you may in addition define the symbol +BOOST_INTERACTIVE_TEST_INPUT_ITERATOR to interactively test the input +operator with input of your choice from the standard input +(instead of hard-coding it in the test). + +[endsect] + +[section Acknowledgements] + +The mathematical text has been typeset with +[@http://www.nisus-soft.com/ Nisus Writer]. Jens Maurer has helped with +portability and standard adherence, and was the Review Manager +for this library. More acknowledgements in the History section. +Thank you to all who contributed to the discution about this library. + +[endsect] + +[section History] + +* 1.5.8 - 17/12/2005: Converted documentation to Quickbook Format. +* 1.5.7 - 24/02/2003: transitionned to the unit test framework; now included by the library header (rather than the test files). +* 1.5.6 - 15/10/2002: Gcc2.95.x and stlport on linux compatibility by Alkis Evlogimenos (alkis@routescience.com). +* 1.5.5 - 27/09/2002: Microsoft VCPP 7 compatibility, by Michael Stevens (michael@acfr.usyd.edu.au); requires the /Za compiler option. +* 1.5.4 - 19/09/2002: fixed problem with multiple inclusion (in different translation units); attempt at an improved compatibility with Microsoft compilers, by Michael Stevens (michael@acfr.usyd.edu.au) and Fredrik Blomqvist; other compatibility fixes. +* 1.5.3 - 01/02/2002: bugfix and Gcc 2.95.3 compatibility by Douglas Gregor (gregod@cs.rpi.edu). +* 1.5.2 - 07/07/2001: introduced namespace math. +* 1.5.1 - 07/06/2001: (end of Boost review) now includes and instead of ; corrected bug in sin (Daryle Walker); removed check for self-assignment (Gary Powel); made converting functions explicit (Gary Powel); added overflow guards for division operators and abs (Peter Schmitteckert); added sup and l1; used Vesa Karvonen's CPP metaprograming technique to simplify code. +* 1.5.0 - 26/03/2001: boostification, inlining of all operators except input, output and pow, fixed exception safety of some members (template version) and output operator, added spherical, semipolar, multipolar, cylindrospherical and cylindrical. +* 1.4.0 - 09/01/2001: added tan and tanh. +* 1.3.1 - 08/01/2001: cosmetic fixes. +* 1.3.0 - 12/07/2000: pow now uses Maarten Hilferink's (mhilferink@tip.nl) algorithm. +* 1.2.0 - 25/05/2000: fixed the division operators and output; changed many signatures. +* 1.1.0 - 23/05/2000: changed sinc into sinc_pi; added sin, cos, sinh, cosh. +* 1.0.0 - 10/08/1999: first public version. + +[endsect] +[section To Do] + +* Improve testing. +* Rewrite input operatore using Spirit (creates a dependency). +* Put in place an Expression Template mechanism (perhaps borrowing from uBlas). +* Use uBlas for the link with rotations (and move from the +[@../../libs/math/quaternion/HSO3SO4.cpp example] +implementation to an efficient one). + +[endsect] +[endsect] diff --git a/doc/math-sf.qbk b/doc/math-sf.qbk new file mode 100644 index 000000000..1f99fc5fe --- /dev/null +++ b/doc/math-sf.qbk @@ -0,0 +1,314 @@ + +[def __asinh [link boost_math.math_special_functions.asinh asinh]] +[def __acosh [link boost_math.math_special_functions.acosh acosh]] +[def __atanh [link boost_math.math_special_functions.atanh atanh]] +[def __sinc_pi [link boost_math.math_special_functions.sinc_pi sinc_pi]] +[def __sinhc_pi [link boost_math.math_special_functions.sinhc_pi sinhc_pi]] + +[def __log1p [link boost_math.math_special_functions.log1p log1p]] +[def __expm1 [link boost_math.math_special_functions.expm1 expm1]] +[def __hypot [link boost_math.math_special_functions.hypot hypot]] + +[def __form1 [^\[0;+'''∞'''\[]] +[def __form2 [^\]-'''∞''';+1\[]] +[def __form3 [^\]-'''∞''';-1\[]] +[def __form4 [^\]+1;+'''∞'''\[]] +[def __form5 `[^\[-1;-1+'''ε'''\[]] +[def __form6 '''ε'''] +[def __form7 [^\]+1-'''ε''';+1\]]] + +[def __effects [*Effects: ]] +[def __formula [*Formula: ]] +[def __exm1 '''ex - 1'''] +[def __ex '''ex'''] +[def __te '''2ε'''] + + +[section Math Special Functions] + +[section Overview] + +The Special Functions library currently provides eight templated special functions, +in namespace boost. Two of these (__sinc_pi and __sinhc_pi) are needed by our +implementation of quaternions and octonions. + +The functions __acosh, __asinh and __atanh are entirely classical, +the function __sinc_pi sees heavy use in signal processing tasks, +and the function __sinhc_pi is an ad'hoc function whose naming is modelled on +__sinc_pi and hyperbolic functions. + +The functions __log1p, __expm1 and __hypot are all part of the C99 standard +but not yet C++. Two of these (__log1p and __hypot) were needed for the +[link boost_math.inverse_complex complex number inverse trigonometric functions]. + +The functions implemented here can throw standard exceptions, but no +exception specification has been made. + +[endsect] + +[section Header Files] + +The interface and implementation for each function (or forms of a function) +are both supplied by one header file: + +* [@../../boost/math/special_functions/acosh.hpp acosh.hpp] +* [@../../boost/math/special_functions/asinh.hpp asinh.hpp] +* [@../../boost/math/special_functions/atanh.hpp atanh.hpp] +* [@../../boost/math/special_functions/expm1.hpp expm1.hpp] +* [@../../boost/math/special_functions/hypot.hpp hypot.hpp] +* [@../../boost/math/special_functions/log1p.hpp log1p.hpp] +* [@../../boost/math/special_functions/sinc.hpp sinc.hpp] +* [@../../boost/math/special_functions/sinhc.hpp sinhc.hpp] + +[endsect] + +[section Synopsis] + + namespace boost{ namespace math{ + + template + T __acosh(const T x); + + template + T __asinh(const T x); + + template + T __atanh(const T x); + + template + T __expm1(const T x); + + template + T __hypot(const T x); + + template + T __log1p(const T x); + + template + T __sinc_pi(const T x); + + template class U> + U __sinc_pi(const U x); + + template + T __sinhc_pi(const T x); + + template class U> + U __sinhc_pi(const U x); + + } + } + +[endsect] + +[section acosh] + + template + T acosh(const T x); + +Computes the reciprocal of (the restriction to the range of __form1) +[link boost_math.background_information_and_white_papers.the_inverse_hyperbolic_functions +the hyperbolic cosine function], at x. Values returned are positive. Generalised +Taylor series are used near 1 and Laurent series are used near the +infinity to ensure accuracy. + +If x is in the range __form2 a quiet NaN is returned (if the system allows, +otherwise a `domain_error` exception is generated). + +[endsect] + +[section asinh] + + template + T asinh(const T x); + +Computes the reciprocal of +[link boost_math.background_information_and_white_papers.the_inverse_hyperbolic_functions +the hyperbolic sine function]. +Taylor series are used at the origin and Laurent series are used near the +infinity to ensure accuracy. + +[endsect] + +[section atanh] + + template + T atanh(const T x); + +Computes the reciprocal of +[link boost_math.background_information_and_white_papers.the_inverse_hyperbolic_functions +the hyperbolic tangent function], at x. +Taylor series are used at the origin to ensure accuracy. + +If x is in the range +__form3 +or in the range +__form4 +a quiet NaN is returned +(if the system allows, otherwise a `domain_error` exception is generated). + +If x is in the range +__form5, +minus infinity is returned +(if the system allows, otherwise an `out_of_range` exception +is generated), with +__form6 +denoting numeric_limits::epsilon(). + +If x is in the range +__form7, +plus infinity is returned (if the system allows, +otherwise an `out_of_range` exception is generated), with +__form6 +denoting +numeric_limits::epsilon(). + +[endsect] + +[section:expm1 expm1] + + template + T expm1(T t); + +__effects returns __exm1. + +For small x, then __ex is very close to 1, as a result calculating __exm1 results +in catastrophic cancellation errors when x is small. `expm1` calculates __exm1 using +a series expansion when x is small (giving an accuracy of less than __te). + +Finally when BOOST_HAS_EXPM1 is defined then the `float/double/long double` +specializations of this template simply forward to the platform's +native implementation of this function. + +[endsect] + +[section:hypot hypot] + + template + T hypot(T x, T y); + +__effects computes [$../../libs/math/doc/images/hypot.png] in such a way as to avoid undue underflow and overflow. + +When calculating [$../../libs/math/doc/images/hypot.png] it's quite easy for the intermediate terms to either +overflow or underflow, even though the result is in fact perfectly representable. +One possible alternative form is [$../../libs/math/doc/images/hypot2.png], but that can overflow or underflow +if x and y are of very differing magnitudes. The `hypot` function takes care of +all the special cases for you, so you don't have to. + +[endsect] + +[section:log1p log1p] + + template + T log1p(T x); + +__effects returns the natural logarithm of `x+1`. + +There are many situations where it is desirable to compute `log(x+1)`. +However, for small `x` then `x+1` suffers from catastrophic cancellation errors +so that `x+1 == 1` and `log(x+1) == 0`, when in fact for very small x, the +best approximation to `log(x+1)` would be `x`. `log1p` calculates the best +approximation to `log(1+x)` using a Taylor series expansion for accuracy +(less than __te). +Note that there are faster methods available, for example using the equivalence: + + log(1+x) == (log(1+x) * x) / ((1-x) - 1) + +However, experience has shown that these methods tend to fail quite spectacularly +once the compiler's optimizations are turned on. In contrast, the series expansion +method seems to be reasonably immune optimizer-induced errors. + +Finally when BOOST_HAS_LOG1P is defined then the `float/double/long double` +specializations of this template simply forward to the platform's +native implementation of this function. + +[endsect] + +[section sinc_pi] + + template + T sinc_pi(const T x); + + template class U> + U sinc_pi(const U x); + +Computes +[link boost_math.background_information_and_white_papers.sinus_cardinal_and_hyperbolic_sinus_cardinal_functions +the Sinus Cardinal] of x. The second form is for complexes, +quaternions, octonions... Taylor series are used at the origin +to ensure accuracy. + +[endsect] + +[section sinhc_pi] + + template + T sinhc_pi(const T x); + + template class U> + U sinhc_pi(const U x); + +Computes +[link boost_math.background_information_and_white_papers.sinus_cardinal_and_hyperbolic_sinus_cardinal_functions +the Hyperbolic Sinus Cardinal] of x. The second form is for +complexes, quaternions, octonions... Taylor series are used at the origin +to ensure accuracy. + +[endsect] + +[section Test Programs] + +The [@../../libs/math/special_functions/special_functions_test.cpp +special_functions_test.cpp] +and [@../../libs/math/test/log1p_expm1_test.cpp log1p_expm1_test.cpp] test programs test the functions for +float, double and long double arguments ([@../../libs/math/special_functions/output.txt sample output], with message +output enabled). + +If you define the symbol BOOST_SPECIAL_FUNCTIONS_TEST_VERBOSE, you will +get additional output +([@../../libs/math/special_functions/output_more.txt verbose output]), +which may prove useful for +tuning on your platform (the library use "reasonable" tolerances, +which may prove to be too strict for your platform); this will only be +helpfull if you enable message output at the same time, of course +(by uncommenting the relevant line in the test or by adding `--log_level=messages` +to your command line,...). + +[endsect] + +[section Acknowledgements] + +The mathematical text has been typeset with [@http://www.nisus-soft.com/ +Nisus Writer], and the +illustrations have been made with [@http://www.pacifict.com/ +Graphing Calculator]. Jens Maurer +was the Review Manager for this library. More acknowledgements in the +History section. Thank you to all who contributed to the discution +about this library. + +[endsect] + +[section History] + +* 1.5.0 - 17/12/2005: John Maddock added __log1p, __expm1 and __hypot. Converted documentation to Quickbook Format. +* 1.4.2 - 03/02/2003: transitionned to the unit test framework; now included by the library headers (rather than the test files). +* 1.4.1 - 18/09/2002: improved compatibility with Microsoft compilers. +* 1.4.0 - 14/09/2001: added (after rewrite) __acosh and __asinh, which were submited by Eric Ford; applied changes for Gcc 2.9.x suggested by John Maddock; improved accuracy; sanity check for test file, related to accuracy. +* 1.3.2 - 07/07/2001: introduced namespace math. +* 1.3.1 - 07/06/2001:(end of Boost review) split special_functions.hpp into atanh.hpp, sinc.hpp and sinhc.hpp; improved efficiency of __atanh with compile-time technique (Daryle Walker); improved accuracy of all functions near zero (Peter Schmitteckert). +* 1.3.0 - 26/03/2001: support for complexes & all, for cardinal functions. +* 1.2.0 - 31/01/2001: minor modifications for Koenig lookup. +* 1.1.0 - 23/01/2001: boostification. +* 1.0.0 - 10/08/1999: first public version. + +[endsect] + +[section To Do] + +* Add more functions. +* Improve test of each function. + +[endsect] +[endsect] + + diff --git a/doc/math-tr1.qbk b/doc/math-tr1.qbk new file mode 100644 index 000000000..6287a7de3 --- /dev/null +++ b/doc/math-tr1.qbk @@ -0,0 +1,142 @@ + +[def __effects [*Effects: ]] +[def __formula [*Formula: ]] +[def __exm1 '''ex - 1'''] +[def __ex '''ex'''] +[def __te '''2ε'''] + +[section:inverse_complex Complex Number Inverse Trigonometric Functions] + +The following complex number algorithms are the inverses of trigonometric functions currently +present in the C++ standard. Equivalents to these functions are part of the C99 standard, and +will be part of the forthcoming Technical Report on C++ Standard Library Extensions. + +[section Implementation and Accuracy] + +Although there are deceptively simple formulae available for all of these functions, a naive +implementation that used these formulae would fail catastrophically for some input +values. The Boost versions of these functions have been implemented using the methodology +described in "Implementing the Complex Arcsine and Arccosine Functions Using Exception Handling" +by T. E. Hull Thomas F. Fairgrieve and Ping Tak Peter Tang, ACM Transactions on Mathematical Software, +Vol. 23, No. 3, September 1997. This means that the functions are well defined over the entire +complex number range, and produce accurate values even at the extremes of that range, where as a naive +formula would cause overflow or underflow to occur during the calculation, even though the result is +actually a representable value. The maximum theoretical relative error for all of these functions +is less than 9.5E for every machine-representable point in the complex plane. Please refer to +comments in the header files themselves and to the above mentioned paper for more information +on the implementation methodology. + +[endsect] +[section:asin asin] + +[h4 Header:] + + #include + +[h4 Synopsis:] + + template + std::complex asin(const std::complex& z); + +__effects returns the inverse sine of the complex number z. + +__formula [$../../libs/math/doc/images/asin.png] + +[endsect] + +[section:acos acos] + +[h4 Header:] + + #include + +[h4 Synopsis:] + + template + std::complex acos(const std::complex& z); + +__effects returns the inverse cosine of the complex number z. + +__formula [$../../libs/math/doc/images/acos.png] + +[endsect] + +[section:atan atan] + +[h4 Header:] + + #include + +[h4 Synopsis:] + + template + std::complex atan(const std::complex& z); + +__effects returns the inverse tangent of the complex number z. + +__formula [$../../libs/math/doc/images/atan.png] + +[endsect] + +[section:asinh asinh] + +[h4 Header:] + + #include + +[h4 Synopsis:] + + template + std::complex asinh(const std::complex& z); + +__effects returns the inverse hyperbolic sine of the complex number z. + +__formula [$../../libs/math/doc/images/asinh.png] + +[endsect] + +[section:acosh acosh] + +[h4 Header:] + + #include + +[h4 Synopsis:] + + template + std::complex acosh(const std::complex& z); + +__effects returns the inverse hyperbolic cosine of the complex number z. + +__formula [$../../libs/math/doc/images/acosh.png] + +[endsect] + +[section:atanh atanh] + +[h4 Header:] + + #include + +[h4 Synopsis:] + + template + std::complex atanh(const std::complex& z); + +__effects returns the inverse hyperbolic tangent of the complex number z. + +__formula [$../../libs/math/doc/images/atanh.png] + +[endsect] + +[section History] + +* 2005/12/17: Added support for platforms with no meaningful numeric_limits<>::infinity(). +* 2005/12/01: Initial version, added as part of the TR1 library. + + +[endsect] + +[endsect] + + diff --git a/doc/math.qbk b/doc/math.qbk index e17807db4..5fa2fc52f 100644 --- a/doc/math.qbk +++ b/doc/math.qbk @@ -1,240 +1,63 @@ -[library Boost.Math TR1 Additions - [copyright 2005 John Maddock] - [purpose Various special functions and complex number algorithms] +[library Boost.Math + [quickbook 1.3] + [copyright 2001-2002 Daryle Walker, 2001-2003 Hubert Holin, 2005 John Maddock] + [purpose Various mathematical functions and data types] [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 http://www.boost.org/LICENSE_1_0.txt]) ] - [authors [Maddock, John]] + [authors [Holin, Hubert], [Maddock, John], [Walker, Daryle]] [category math] [last-revision $Date$] ] -[def __effects [*Effects: ]] -[def __formula [*Formula: ]] -[def __exm1 '''ex - 1'''] -[def __ex '''ex'''] -[def __te '''2ɛ'''] +[def __asinh [link boost_math.math_special_functions.asinh asinh]] +[def __acosh [link boost_math.math_special_functions.acosh acosh]] +[def __atanh [link boost_math.math_special_functions.atanh atanh]] +[def __sinc_pi [link boost_math.math_special_functions.sinc_pi sinc_pi]] +[def __sinhc_pi [link boost_math.math_special_functions.sinhc_pi sinhc_pi]] -[section:intro Introduction] +[def __log1p [link boost_math.math_special_functions.log1p log1p]] +[def __expm1 [link boost_math.math_special_functions.expm1 expm1]] +[def __hypot [link boost_math.math_special_functions.hypot hypot]] -This addition to the Boost.Math library provides two features which are part of -the forthcoming Technical Report on C++ Standard Library Extensions: -* Additional real number special functions (log1p, expm1 and hypot). -* The complex number inverse trigonometric and inverse hyper-trigonometric functions. +[section Overview] -Both of these features are also part of the existing C99 standard, but not the current -C++ standard. +The [link boost_math.greatest_common_divisor_and_least_common_multiple Greatest Common Divisor and Least Common Multiple library] +provides run-time and compile-time evaluation of the greatest common divisor (GCD) +or least common multiple (LCM) of two integers. -[endsect] +The [link boost_math.math_special_functions Special Functions library] currently provides eight templated special functions, +in namespace boost. Two of these (__sinc_pi and __sinhc_pi) are needed by our +implementation of quaternions and octonions. The functions __acosh, +__asinh and __atanh are entirely classical, +the function __sinc_pi sees heavy use in signal processing tasks, +and the function __sinhc_pi is an ad'hoc function whose naming is modelled on +__sinc_pi and hyperbolic functions. The functions __log1p, __expm1 and __hypot are all part of the C99 standard +but not yet C++. Two of these (__log1p and __hypot) were needed for the +[link boost_math.inverse_complex complex number inverse trigonometric functions]. -[section:C99 Selected C99 Special Functions] - -[section:log1p log1p] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - T log1p(T x); - -__effects returns the natural logarithm of `x+1`. - -There are many situations where it is desirable to compute `log(x+1)`. -However, for small `x` then `x+1` suffers from catastrophic cancellation errors -so that `x+1 == 1` and `log(x+1) == 0`, when in fact for very small x, the -best approximation to `log(x+1)` would be `x`. `log1p` calculates the best -approximation to `log(1+x)` using a Taylor series expansion for accuracy -(less than __te). -Note that there are faster methods available, for example using the equivalence: - - log(1+x) == (log(1+x) * x) / ((1-x) - 1) - -However, experience has shown that these methods tend to fail quite spectacularly -once the compiler's optimizations are turned on. In contrast, the series expansion -method seems to be reasonably immune optimizer-induced errors. - -Finally when BOOST_HAS_LOG1P is defined then the `float/double/long double` -specializations of this template simply forward to the platform's -native implementation of this function. - -[endsect] - -[section:expm1 expm1] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - T expm1(T t); - -__effects returns __exm1. - -For small x, then __ex is very close to 1, as a result calculating __exm1 results -in catastrophic cancellation errors when x is small. `expm1` calculates __exm1 using -a series expansion when x is small (giving an accuracy of less than __te). - -Finally when BOOST_HAS_EXPM1 is defined then the `float/double/long double` -specializations of this template simply forward to the platform's -native implementation of this function. - -[endsect] - -[section:hypot hypot] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - T hypot(T x, T y); - -__effects computes [$../../libs/math/doc/images/hypot.png] in such a way as to avoid undue underflow and overflow. - -When calculating [$../../libs/math/doc/images/hypot.png] it's quite easy for the intermediate terms to either -overflow or underflow, even though the result is in fact perfectly representable. -One possible alternative form is [$../../libs/math/doc/images/hypot2.png], but that can overflow or underflow -if x and y are of very differing magnitudes. The `hypot` function takes care of -all the special cases for you, so you don't have to. - -[endsect] - -[endsect] - -[section:inverse_complex Complex Number Inverse Trigonometric Functions] - -The following complex number algorithms are the inverses of trigonometric functions currently -present in the C++ standard. Equivalents to these functions are part of the C99 standard, and +The [link boost_math.inverse_complex Complex Number Inverse Trigonometric Functions] +are the inverses of trigonometric functions currently present in the C++ standard. +Equivalents to these functions are part of the C99 standard, and they will be part of the forthcoming Technical Report on C++ Standard Library Extensions. -Although there are deceptively simple formulae available for all of these functions, a naive -implementation that used these formulae would fail catastrophically for some input -values. The Boost versions of these functions have been implemented using the methodology -described in "Implementing the Complex Arcsine and Arccosine Functions Using Exception Handling" -by T. E. Hull Thomas F. Fairgrieve and Ping Tak Peter Tang, ACM Transactions on Mathematical Software, -Vol. 23, No. 3, September 1997. This means that the functions are well defined over the entire -complex number range, and produce accurate values even at the extremes of that range, where as a naive -formula would cause overflow or underflow to occur during the calculation, even though the result is -actually a representable value. The maximum theoretical relative error for all of these functions -is less than 9.5E for every machine-representable point in the complex plane. Please refer to -comments in the header files themselves and to the above mentioned paper for more information -on the implementation methodology. +[link boost_math.quaternions Quaternions] are a relative of +complex numbers often used to parameterise rotations in three +dimentional space. -[section:asin asin] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - std::complex asin(const std::complex& z); - -__effects returns the inverse sine of the complex number z. - -__formula [$../../libs/math/doc/images/asin.png] +[link boost_math.octonions Octonions], like [link boost_math.quaternions quaternions], +are a relative of complex numbers. [link boost_math.octonions Octonions] +see some use in theoretical physics. [endsect] -[section:acos acos] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - std::complex acos(const std::complex& z); - -__effects returns the inverse cosine of the complex number z. - -__formula [$../../libs/math/doc/images/acos.png] - -[endsect] - -[section:atan atan] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - std::complex atan(const std::complex& z); - -__effects returns the inverse tangent of the complex number z. - -__formula [$../../libs/math/doc/images/atan.png] - -[endsect] - -[section:asinh asinh] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - std::complex asinh(const std::complex& z); - -__effects returns the inverse hyperbolic sine of the complex number z. - -__formula [$../../libs/math/doc/images/asinh.png] - -[endsect] - -[section:acosh acosh] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - std::complex acosh(const std::complex& z); - -__effects returns the inverse hyperbolic cosine of the complex number z. - -__formula [$../../libs/math/doc/images/acosh.png] - -[endsect] - -[section:atanh atanh] - -[h4 Header:] - - #include - -[h4 Synopsis:] - - template - std::complex atanh(const std::complex& z); - -__effects returns the inverse hyperbolic tangent of the complex number z. - -__formula [$../../libs/math/doc/images/atanh.png] - -[endsect] - -[endsect] - - +[include math-gcd.qbk] +[include math-sf.qbk] +[include math-tr1.qbk] +[include math-quaternion.qbk] +[include math-octonion.qbk] +[include math-background.qbk]