Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Cayley/polishing doc #32

Merged
merged 24 commits into from
Sep 30, 2023
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
98 changes: 79 additions & 19 deletions doc/index.md
Original file line number Diff line number Diff line change
Expand Up @@ -58,9 +58,15 @@ Higher are the dimensions weirder are these algebras
- quaternion is a non-commutative field
- octonion is a non associative (but alternative) division algebra

The functions [commutator](@ref kyosu::commutator ) (resp. [associator](@ref kyosu::associator ))
can be used to see if two (resp. three) Cayley-Dickson value commute (resp. associate).

Greater dimensions are not even alternative but keep power-associativity which allows
to define most elementary functions.

@note Let us recall that alternative means that every subalgrebra generated by
two elements is associative.


What does this implementation provide
======================================
Expand All @@ -69,32 +75,48 @@ All operators and functions implemented can receive a mix of scalar or simd of c
dimensionnality and are defined in the namespace kyosu.

Of course the algebra operation +, -, * and / are provided, but as \ is not an usable **C++**
character as an operator, the left division a\b is provided as the call ldiv(a,b).
character as an operator, the left division `a \ b` is provided as the call ldiv(a,b).

Constructors
------------

complex and quaternion can be constructed using callables facilities `complex` and `quaternion`.

complex can also be constructed from their polar representation
complex can also be constructed from their polar representation\n
quaternion from various parametrizations of \f$\mathbb{R}^4\f$ or from \f$\mathbb{R}^3\f$ rotations:

* angle and axis
* cylindrical
* cylindricospherical
* euler
* multipolar
* rotation_matrix
* semipolar
* spherical
| | | |
|-------------------------|-----------------------------------------------------------------|-------------------------------------------------------------|
| angle and axis | [from_angle_axis](@ref kyosu::from_angle_axis ) | [to_angle_axis](@ref kyosu::to_angle_axis ) |
| cylindrical | [from_cylindrical](@ref kyosu::from_cylindrical ) | [to_cylindrical](@ref kyosu::to_cylindrical ) |
| cylindrospherical | [from_cylindrospherical](@ref kyosu::from_cylindrospherical ) | [to_cylindrospherical](@ref kyosu::to_cylindrospherical ) |
| euler | [from_euler](@ref kyosu::from_euler ) | [to_euler](@ref kyosu::to_euler ) |
| multipolar | [from_multipolar](@ref kyosu::from_multipolar ) | [to_multipolar](@ref kyosu::to_multipolar ) |
| rotation matrix | [from_rotation_matrix](@ref kyosu::from_rotation_matrix ) | [to_rotation_matrix](@ref kyosu::to_rotation_matrix ) |
| semipolar | [from_semipolar](@ref kyosu::from_semipolar ) | [to_semipolar](@ref kyosu::to_semipolar ) |
| spherical | [from_spherical](@ref kyosu::from_spherical ) | [to_spherical](@ref kyosu::to_spherical ) |
| two vectors | [align](@ref kyosu::align ) | |

The third column references to the corresponding to_xxx version that gives back the
chosen representation from a quaternion input.

TODO cayley_dickson<N> construction by a function.

Operators
---------

TODO cayley_dickson<N>
Operators (as said before) `+`, `-`, `*` and `/` can be used in infix form and can mix cayley-dickson values of
different dimensinalities. Of course the biggest dimensionlity is recovered in the output.

Prefix forms are also provided as `add`, `sub`, `multiply` and `div`. Also plus and minus for unary versions.

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

Functions
---------

Most **KYOSU** callables are usable with all cayley_dickson types. The exception being mainly special
complex functions and rotation related quaternion usage.
complex functions and rotation related quaternion usage.

@warning: **EVE** callables that correspond to mathematical functions that
are only defined on a proper part of the real axis as, for example, `acos` DOES NOT ever provide the same result
Expand All @@ -107,10 +129,48 @@ Most **KYOSU** callables are usable with all cayley_dickson types. The exception

* callables usable with all cayley_dickson types

Most **EVE** arithmetic functions are provided.

* callables usable with complex only

* callables usable with quaternion (and complex) only

Most **EVE** arithmetic functions are provided.
Most **EVE** arithmetic and math functions are provided.

| | | | | |
|--------------|---------------|-----------------|------------|-----------------|
| [abs](@ref kyosu::abs ) | [acos](@ref kyosu::acos ) | [acosh](@ref kyosu::acosh ) | [acospi](@ref kyosu::acospi ) | [acot](@ref kyosu::acot ) |
| [acotpi](@ref kyosu::acotpi ) | [atanpi](@ref kyosu::atanpi ) | [acoth](@ref kyosu::acoth ) | [arg](@ref kyosu::arg ) | [acsc](@ref kyosu::acsc ) |
| [acscpi](@ref kyosu::acscpi ) | [acsch](@ref kyosu::acsch ) | [asec](@ref kyosu::asec ) | [asecpi](@ref kyosu::asecpi ) | [asech](@ref kyosu::asech ) |
| [asin](@ref kyosu::asin ) | [asinpi](@ref kyosu::asinpi ) | [asinh](@ref kyosu::asinh ) | [atan](@ref kyosu::atan ) | [atanh](@ref kyosu::atanh ) |
| [average](@ref kyosu::average ) | [ceil](@ref kyosu::ceil ) | [conj](@ref kyosu::conj ) | [cos](@ref kyosu::cos ) | [cosh](@ref kyosu::cosh ) |
| [cospi](@ref kyosu::cospi ) | [cot](@ref kyosu::cot ) | [cotpi](@ref kyosu::cotpi ) | [coth](@ref kyosu::coth ) | [convert](@ref kyosu::convert ) |
| [csc](@ref kyosu::csc ) | [cscpi](@ref kyosu::cscpi ) | [csch](@ref kyosu::csch ) | [dec](@ref kyosu::dec ) | [dist](@ref kyosu::dist ) |
| [dot](@ref kyosu::dot ) | [exp](@ref kyosu::exp ) | [exp10](@ref kyosu::exp10 ) | [exp2](@ref kyosu::exp2 ) | [exp_i](@ref kyosu::exp_i ) |
| [exp_ipi](@ref kyosu::exp_ipi ) | [expm1](@ref kyosu::expm1 ) | [expmx2](@ref kyosu::expmx2 ) | [expx2](@ref kyosu::expx2 ) | [floor](@ref kyosu::floor ) |
| [frac](@ref kyosu::frac ) | [from_polar](@ref kyosu::from_polar ) | [hypot](@ref kyosu::hypot ) | [if_else](@ref kyosu::if_else )| [inc](@ref kyosu::inc ) |
| [ipart](@ref kyosu::ipart ) | [is_denormal](@ref kyosu::is_denormal ) | [is_equal](@ref kyosu::is_equal ) | [is_eqz](@ref kyosu::is_eqz ) | [is_finite](@ref kyosu::is_finite ) |
| [is_infinite](@ref kyosu::is_infinite ) | [is_imag](@ref kyosu::is_imag ) | [is_nan](@ref kyosu::is_nan ) | [is_nez](@ref kyosu::is_nez ) | [is_not_denormal](@ref kyosu::is_not_denormal ) |
| [is_not_equal](@ref kyosu::is_not_equal ) | [is_not_finite](@ref kyosu::is_not_finite ) | [is_not_infinite](@ref kyosu::is_not_finite ) | [is_not_nan](@ref kyosu::is_not_nan ) | [is_not_real](@ref kyosu::is_not_real ) |
| [is_pure](@ref kyosu::is_pure ) | [is_real](@ref kyosu::is_real ) | [is_unitary](@ref kyosu::is_unitary ) | [jpart](@ref kyosu::jpart ) | [kpart](@ref kyosu::kpart ) |
| [ldiv](@ref kyosu::ldiv ) | [lerp](@ref kyosu::lerp ) | [log](@ref kyosu::log ) | [log10](@ref kyosu::log10 ) | [log1p](@ref kyosu::log1p ) |
| [log_abs](@ref kyosu::log_abs ) | [log2](@ref kyosu::log2 ) | [lpnorm](@ref kyosu::lpnorm ) | [manhattan](@ref kyosu::manhattan ) | [minus](@ref kyosu::minus ) |
| [lpart](@ref kyosu::lpart ) | [lipart](@ref kyosu::lipart ) | [ljpart](@ref kyosu::ljpart ) | [lkpart](@ref kyosu::lkpart ) | |
| [nearest](@ref kyosu::nearest ) | [oneminus](@ref kyosu::oneminus ) | [pow](@ref kyosu::pow ) | [pow1p](@ref kyosu::pow1p ) | [pow_abs](@ref kyosu::pow_abs ) |
| [powm1](@ref kyosu::powm1 ) | [proj](@ref kyosu::proj ) | [pure](@ref kyosu::imag ) | [radinpi](@ref kyosu::radinpi )| [real](@ref kyosu::real ) |
| [rec](@ref kyosu::rec ) | [reldist](@ref kyosu::reldist ) | [sec](@ref kyosu::sec ) | [secpi](@ref kyosu::secpi ) | [sech](@ref kyosu::sech ) |
| [sign](@ref kyosu::sign ) | [sin](@ref kyosu::sin ) | [sinc](@ref kyosu::sinc ) | [sincos](@ref kyosu::sincos ) | [sinpi](@ref kyosu::sinpi ) |
| [sinpicospi](@ref kyosu::sinpicospi ) | [sinh](@ref kyosu::sinh ) | [sinhcosh](@ref kyosu::sinhcosh ) | [slerp](@ref kyosu::slerp ) | [sqr](@ref kyosu::sqr ) |
| [sqr_abs](@ref kyosu::sqr_abs ) | [sqrt](@ref kyosu::sqrt ) | [tan](@ref kyosu::tan ) | [tanpi](@ref kyosu::tanpi ) | [tanh](@ref kyosu::tanh ) |
| [to_polar](@ref kyosu::to_polar ) | [trunc](@ref kyosu::trunc ) | | | |

* callables usable with complex or real only. These are mainly implementation of some classical meromorphic functions.

| | | | | |
|------------------|------------------|--------------------|------------------|---------------|
| [beta](@ref kyosu::beta ) | [deta](@ref kyosu::deta ) | [digamma](@ref kyosu::digamma ) | [erf](@ref kyosu::erf ) | [erfcx](@ref kyosu::erfcx ) |
| [erfi](@ref kyosu::erfi ) | [eta](@ref kyosu::eta ) | [faddeeva](@ref kyosu::faddeeva ) | [lambda](@ref kyosu::lambda ) | [lbeta](@ref kyosu::lbeta ) |
| [log_abs_gamma](@ref kyosu::log_abs_gamma ) | [log_gamma](@ref kyosu::log_gamma ) | [lrising_factorial](@ref kyosu::lrising_factorial ) | [rising_factorial](@ref kyosu::rising_factorial ) | [tgamma](@ref kyosu::tgamma ) |
| [zeta](@ref kyosu::zeta ) | | | | |

* callables usable with quaternion complex and real only

These functions are related to \f$\mathbb{R}^3\f$ rotations

| | | |
|-----------|------------|------------|
| [rot_angle](@ref kyosu::rot_angle) | [rot_axis](@ref kyosu::rot_axis) | [rotate_vec](@ref kyosu::rotate_vec) |
24 changes: 8 additions & 16 deletions include/kyosu/complex/beta.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -23,7 +23,8 @@ namespace kyosu::tags
return fn(complex(v), w); }

template<typename T1, typename T2>
KYOSU_FORCEINLINE auto operator()(T1 const& target1, T2 const& target2) const noexcept -> decltype(eve::tag_invoke(*this, target1, target2))
KYOSU_FORCEINLINE auto operator()(T1 const& target1, T2 const& target2) const noexcept
-> decltype(eve::tag_invoke(*this, target1, target2))
{
return eve::tag_invoke(*this, target1, target2);
}
Expand All @@ -40,7 +41,8 @@ namespace kyosu
//! @addtogroup functions
//! @{
//! @var beta
//! @brief Computes the beta function: \f$\displaystyle \mathbf{B}(x, y) = \frac{\Gamma(x)\Gamma(y)}{\Gamma(x+y)}\f$.
//! @brief Computes the beta function: \f$\displaystyle \mathbf{B}(x, y) = \frac{\Gamma(x)\Gamma(y)}{\Gamma(x+y)}\f$
//! for real or complex entries.
//!
//! **Defined in Header**
//!
Expand All @@ -53,28 +55,18 @@ namespace kyosu
//! @code
//! namespace kyosu
//! {
//! template< eve::floating_ordered_value T, eve::floating_ordered_value U >
//! auto beta(T x,U y) noexcept; //1
//!
//! template< eve::floating_value T, eve::floating_value U >
//! auto beta(eve::complex_t<T> x, U y) noexcept; //2
//!
//! template< eve::floating_value T, eve::floating_value U >
//! auto beta(T x, eve::complex_t<U> y) noexcept; //2
//!
//! template< eve::floating_value T, eve::floating_value U >
//! auto beta(eve::complex_t<T> x, eve::complex_t<U> y) noexcept; //2
//! auto beta(auto x, auto y) noexcept;
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `x`,`y` : Values to process.
//! * `x`,`y` : Values to process. Can be a mix of complex and real floating values and complex values.
//!
//! **Return value**
//!
//! 1. \f$\displaystyle \mathbf{B}(x,y) = \int_0^1 t^{x-1}(1-t)^{y-1}\mbox{d}t\f$
//! 2. The complex \f$\displaystyle \mathbb{B}(x,y) = \frac{\Gamma(x)\Gamma(y)}{\Gamma(x+y)}\f$ is returned.
//! 1. If x and y are real typed values returns \f$\displaystyle \mathbf{B}(x,y) = \int_0^1 t^{x-1}(1-t)^{y-1}\mbox{d}t\f$
//! 2. The complex value \f$\displaystyle \mathbb{B}(x,y) = \frac{\Gamma(x)\Gamma(y)}{\Gamma(x+y)}\f$ is returned.
//!
//! @groupheader{Example}
//!
Expand Down
10 changes: 5 additions & 5 deletions include/kyosu/complex/deta.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ namespace kyosu
//! @addtogroup functions
//! @{
//! @var deta
//! @brief Computes the Dirichlet sums \f$ \displaystyle \sum_0^\infty \frac{(-1)^n}{(kn+1)^z}\f$.
//! @brief Computes the Dirichlet sums \f$ \displaystyle \sum_{n = 0}^\infty \frac{(-1)^n}{(kn+1)^z}\f$.
//!
//! **Defined in Header**
//!
Expand All @@ -56,19 +56,19 @@ namespace kyosu
//! @code
//! namespace kyosu
//! {
//! template<unsigned_scalar_value K, eve::ordered_value T> constexpr auto deta(K, k, T z) noexcept; //1
//! template<unsigned_scalar_value K, kyosu::concepts::complex T> constexpr auto deta(K, k, T z) noexcept; //2
//! template<unsigned_scalar_value K, eve::ordered_value T> constexpr auto deta(K k, T z) noexcept; //1
//! template<unsigned_scalar_value K, kyosu::concepts::complex T> constexpr auto deta(K k, T z) noexcept; //2
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `k` : scalar unsigned value, parameter of the sum.
//! * `z` : Vcomplex or real value to process.
//! * `z` : complex or real value to process.
//!
//! **Return value**
//!
//! Returns the Dirichlet sum \f$ \displaystyle \sum_0^\infty \frac{(-1)^n}{(kn+1)^z}\f$
//! Returns the Dirichlet sum \f$ \displaystyle \sum_{n = 0}^\infty \frac{(-1)^n}{(kn+1)^z}\f$
//!
//! @groupheader{Example}
//!
Expand Down
6 changes: 3 additions & 3 deletions include/kyosu/complex/digamma.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ namespace kyosu
//! @addtogroup functions
//! @{
//! @var digamma
//! @brief Computes the Digamma function i.e. the logarithmic derivative of the \f$\Gamma\f$
//! @brief Computes the Digamma function i.e. the logarithmic derivative of the \f$\Gamma\f$ function
//!
//! **Defined in Header**
//!
Expand All @@ -53,13 +53,13 @@ namespace kyosu
//! namespace kyosu
//! {
//! template<kyosu::concepts::complex T> constexpr T digamma(T z) noexcept;
//! template<eve::floatingordered_value T> constexpr T digamma(T z) noexcept;
//! template<eve::floating_ordered_value T> constexpr T digamma(T z) noexcept;
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `z` : Value to process.
//! * `z` : real or complex value to process.
//!
//! **Return value**
//!
Expand Down
2 changes: 1 addition & 1 deletion include/kyosu/complex/erf.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -68,7 +68,7 @@ namespace kyosu
//!
//! **Return value**
//!
//! 1. a real input z is treated as if complex(z) was entered.
//! 1. a real input z returns eve::erf(z).
//!
//! 2. The value of the error function in the complex plane is returned
//!
Expand Down
2 changes: 1 addition & 1 deletion include/kyosu/complex/erfcx.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ namespace kyosu
//!
//! **Return value**
//!
//! 1. a real input z is treated as if complex(z) was entered.
//! 1. a real input z return eve::erfcx(z).
//!
//! 2. The value of the normalized complementary error function is returned.
//!
Expand Down
2 changes: 1 addition & 1 deletion include/kyosu/complex/erfi.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -65,7 +65,7 @@ namespace kyosu
//!
//! **Parameters**
//!
//! * `z` : Vcomplex or real value to process.
//! * `z` : complex or real value to process.
//!
//! **Return value**
//!
Expand Down
4 changes: 2 additions & 2 deletions include/kyosu/complex/eta.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -64,11 +64,11 @@ namespace kyosu
//!
//! **Parameters**
//!
//! * `z` : Vcomplex or real value to process.
//! * `z` : complex or real value to process.
//!
//! **Return value**
//!
//! Returns the Dirichlet alternating zeta function: sum \f$ \displaystyle \sum_0^\infty \frac{(-1)^n}{(n+1)^z}\f$
//! Returns the Dirichlet alternating zeta function: \f$ \displaystyle \sum_0^\infty \frac{(-1)^n}{(n+1)^z}\f$
//!
//! @groupheader{Example}
//!
Expand Down
2 changes: 1 addition & 1 deletion include/kyosu/complex/lambda.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -67,7 +67,7 @@ namespace kyosu
//!
//! **Parameters**
//!
//! * `z` : Vcomplex or real value to process.
//! * `z` : complex or real value to process.
//!
//! **Return value**
//!
Expand Down
2 changes: 1 addition & 1 deletion include/kyosu/complex/log_abs_gamma.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -56,7 +56,7 @@ namespace kyosu
//! namespace kyosu
//! {
//! template<kyosu::concepts::complex T> constexpr T log_abs_gamma(T z) noexcept;
//! template<eve::floatingordered_value T> constexpr T log_abs_gamma(T z) noexcept;
//! template<eve::floating_ordered_value T> constexpr T log_abs_gamma(T z) noexcept;
//! }
//! @endcode
//!
Expand Down
2 changes: 1 addition & 1 deletion include/kyosu/complex/log_gamma.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -54,7 +54,7 @@ namespace kyosu
//! namespace kyosu
//! {
//! template<kyosu::concepts::complex T> constexpr T log_gamma(T z) noexcept;
//! template<eve::floatingordered_value T> constexpr T log_gamma(T z) noexcept;
//! template<eve::floating_ordered_value T> constexpr T log_gamma(T z) noexcept;
//! }
//! @endcode
//!
Expand Down
2 changes: 1 addition & 1 deletion include/kyosu/complex/lrising_factorial.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -73,7 +73,7 @@ namespace kyosu
//!
//! **Return value**
//!
//! @brief Computes the Rising Factorial function i.e. \f$\log\frac{\Gamma(x+y)}{\Gamma(x)}\f$.
//! @brief Computes the logarithm Rising Factorial function i.e. \f$\log\frac{\Gamma(x+y)}{\Gamma(x)}\f$.
//!
//! @groupheader{Example}
//!
Expand Down
4 changes: 2 additions & 2 deletions include/kyosu/complex/tgamma.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -55,7 +55,7 @@ namespace kyosu
//! namespace kyosu
//! {
//! template<kyosu::concepts::complex T> constexpr T tgamma(T z) noexcept;
//! template<eve::floatingordered_value T> constexpr T tgamma(T z) noexcept;
//! template<eve::floating_ordered_value T> constexpr T tgamma(T z) noexcept;
//! }
//! @endcode
//!
Expand All @@ -65,7 +65,7 @@ namespace kyosu
//!
//! **Return value**
//!
//! Returns \f$\Gamma(z)\f$. If z is floating the result is as if complex(z) was used in the call.
//! Returns \f$\Gamma(z)\f$.
//!
//! @groupheader{Example}
//!
Expand Down
11 changes: 5 additions & 6 deletions include/kyosu/complex/zeta.hpp
Original file line number Diff line number Diff line change
Expand Up @@ -43,7 +43,7 @@ namespace kyosu
//! @addtogroup functions
//! @{
//! @var zeta
//! @brief Computes the Riemann \f$\zeta\f$ \f$ \displaystyle \sum_0^\infty \frac{1}{(n+1)^z}\f$.
//! @brief Computes the Riemann \f$ \displaystyle\zeta(z)=\sum_0^\infty \frac{1}{(n+1)^z}\f$.
//!
//! **Defined in Header**
//!
Expand All @@ -56,19 +56,18 @@ namespace kyosu
//! @code
//! namespace kyosu
//! {
//! template<unsigned_scalar_value K, eve::ordered_value T> constexpr auto zeta(K, k, T z) noexcept; //1
//! template<unsigned_scalar_value K, kyosu::concepts::complex T> constexpr auto zeta(K, k, T z) noexcept; //2
//! template<eve::floating_ordered_value T> constexpr auto zeta(T z) noexcept;
//! template<kyosu::concepts::complex T> constexpr auto zeta(T z) noexcept;
//! }
//! @endcode
//!
//! **Parameters**
//!
//! * `k` : scalar unsigned value, parameter of the sum.
//! * `z` : Vcomplex or real value to process.
//! * `z` : complex or real value to process.
//!
//! **Return value**
//!
//! Returns the Dirichlet alternating zzeta function: sum \f$ \displaystyle \sum_0^\infty \frac{1}{(n+1)^z}\f$
//! Returns the Dirichlet zeta function: \f$ \displaystyle \sum_0^\infty \frac{1}{(n+1)^z}\f$
//!
//! @groupheader{Example}
//!
Expand Down
Loading