Klein 2.0 commit (see commit body for details).

- Entity type has been removed due to compiler inability to properly constant-fold interior expressions. - Operators have been promoted to first-order types. - A number of operators have been specialized for various types for improved throughput/latency. - Perf analysis has been updated. - Motors can now be constructed from a screw axis, angle, and displacement. - A preliminary dual number type as been added. - The exp/log methods have been promoted to free functions and now have strongly typed return values. - The project function has been added to simplify various projections.
jeremyong · Mar 4, 2020 · d447c5d · d447c5d
1 parent 9aa59b9
commit d447c5d
Show file tree

Hide file tree

Showing 68 changed files with 5,637 additions and 4,748 deletions.
diff --git a/Doxyfile b/Doxyfile
@@ -1531,7 +1531,7 @@ FORMULA_MACROFILE      =
 # The default value is: NO.
 # This tag requires that the tag GENERATE_HTML is set to YES.
 
-USE_MATHJAX            = NO
+USE_MATHJAX            = YES
 
 # When MathJax is enabled you can set the default output format to be used for
 # the MathJax output. See the MathJax site (see:

diff --git a/c_src/klein_c.cpp b/c_src/klein_c.cpp
@@ -64,19 +64,19 @@ kln_motor const& convert(kln::motor const& motor)
 
 void kln_plane_init(kln_plane* plane, float a, float b, float c, float d)
 {
-    plane->p0 = kln::plane{a, b, c, d}.p0();
+    plane->p0 = kln::plane{a, b, c, d}.p0_;
 }
 
 void kln_line_init(kln_line* line, float a, float b, float c, float d, float e, float f)
 {
     kln::line tmp{a, b, c, d, e, f};
-    line->p1 = tmp.p1();
-    line->p2 = tmp.p2();
+    line->p1 = tmp.p1_;
+    line->p2 = tmp.p2_;
 }
 
 void kln_point_init(kln_point* point, float x, float y, float z)
 {
-    point->p3 = kln::point{x, y, z}.p3();
+    point->p3 = kln::point{x, y, z}.p3_;
 }
 
 kln_point kln_reflect_point(kln_plane const* plane, kln_point const* point)
@@ -171,10 +171,10 @@ kln_motor kln_compose_motors(kln_motor const* motor1, kln_motor const* motor2)
 
 kln_line motor_log(kln_motor const* motor)
 {
-    return convert(kln::line{convert(*motor).log()});
+    return convert(kln::line{log(convert(*motor))});
 }
 
 kln_motor line_exp(kln_line const* line)
 {
-    return convert(kln::motor{convert(*line).exp()});
+    return convert(kln::motor{exp(convert(*line))});
 }
diff --git a/docs/api/dir.md b/docs/api/dir.md
@@ -0,0 +1,121 @@
+## group `dir` {#group__dir}
+
+Directions in $\mathbf{P}(\mathbb{R}^3_{3, 0, 1})$ are represented using points at infinity (homogeneous coordinate 0). Having a homogeneous coordinate of zero ensures that directions are translation-invariant.
+
+### Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public  ` [`direction`](#group__dir_1gac86167cefc9b8118a8f894aaba99f9a5)`() = default`             | 
+`public  ` [`direction`](#group__dir_1ga8fc796733d32a69230136b8376003fca)`(float x,float y,float z) noexcept`             | Create a normalized direction.
+`public  ` [`direction`](#group__dir_1ga7cc439bc60bbbe279bbda37f2e0d139b)`(__m128 p3) noexcept`             | 
+`public  explicit ` [`direction`](#group__dir_1ga42ce139ace571176acabbce21d6c64b2)`(float * data) noexcept`             | Data should point to four floats with memory layout `(0.f, x, y, z)`  where the zero occupies the lowest address in memory.
+`public float ` [`x`](#group__dir_1ga721087c2056a33cd780c678ae0ec39dd)`() const noexcept`             | 
+`public float ` [`y`](#group__dir_1ga40bc7052a639d57afde7a860c1631638)`() const noexcept`             | 
+`public float ` [`z`](#group__dir_1ga1e16d3ed0ff945d0d1cbf1e6458d334b)`() const noexcept`             | 
+`public void ` [`normalize`](#group__dir_1ga143cd2cfeb94860ce1d47b9735064802)`() noexcept`             | Normalize this direction by dividing all components by the magnitude
+`public direction &KLN_VEC_CALL ` [`operator+=`](#group__dir_1gabf098bdf982bbd9572d9fb09a5f76786)`(direction b) noexcept`             | Direction addition.
+`public direction &KLN_VEC_CALL ` [`operator-=`](#group__dir_1ga4bd0650e5c363ec427a4021b678f0567)`(direction b) noexcept`             | Direction subtraction.
+`public direction & ` [`operator*=`](#group__dir_1ga8f2c363e3b6ce34e18451b6c716be97a)`(float s) noexcept`             | Direction uniform scale.
+`public direction & ` [`operator*=`](#group__dir_1ga6a07c40530461b7a4c94d2aff1371217)`(int s) noexcept`             | Direction uniform scale.
+`public direction & ` [`operator/=`](#group__dir_1ga9cac6b5beba3d2e2b0ce1e9a5158c25f)`(float s) noexcept`             | Direction uniform inverse scale.
+`public direction & ` [`operator/=`](#group__dir_1ga2717db218937fdb1b88aba24d3abd189)`(int s) noexcept`             | Direction uniform inverse scale.
+`public direction KLN_VEC_CALL ` [`operator+`](#group__dir_1ga3aa93423517b128de3d64111201220ce)`(direction a,direction b) noexcept`             | Direction addition.
+`public direction KLN_VEC_CALL ` [`operator-`](#group__dir_1gacdc4f7208ad657c450708efcc7fe27d0)`(direction a,direction b) noexcept`             | Direction subtraction.
+`public direction KLN_VEC_CALL ` [`operator*`](#group__dir_1ga5d061f57e3a9f92620f6e90d5dbcb8cb)`(direction d,float s) noexcept`             | Direction uniform scale.
+`public direction KLN_VEC_CALL ` [`operator*`](#group__dir_1ga0a2f15a137d3c9ef3e5b83e3eee71f9a)`(float s,direction d) noexcept`             | Direction uniform scale.
+`public direction KLN_VEC_CALL ` [`operator*`](#group__dir_1ga9d4aadcb32609919e0a2614b1041fdf0)`(direction d,int s) noexcept`             | Direction uniform scale.
+`public direction KLN_VEC_CALL ` [`operator*`](#group__dir_1ga0229ad2276f2d9a7f07baee7ee3d7582)`(int s,direction d) noexcept`             | Direction uniform scale.
+`public direction KLN_VEC_CALL ` [`operator/`](#group__dir_1ga4473202567a1e1bf3a0929c33d723f52)`(direction d,float s) noexcept`             | Direction uniform inverse scale.
+`public direction KLN_VEC_CALL ` [`operator/`](#group__dir_1ga2a8d9ef9111a21d1a55fe08e2c656317)`(direction d,int s) noexcept`             | Direction uniform inverse scale.
+`public direction ` [`operator-`](#group__dir_1ga65b1fe0cfac3611b65b78924cb5a61ac)`(direction d) noexcept`             | Unary minus.
+
+### Members
+
+####   [direction](#group__dir_1gac86167cefc9b8118a8f894aaba99f9a5)() = default  {#group__dir_1gac86167cefc9b8118a8f894aaba99f9a5}
+
+####   [direction](#group__dir_1ga8fc796733d32a69230136b8376003fca)(float x,float y,float z) noexcept  {#group__dir_1ga8fc796733d32a69230136b8376003fca}
+
+Create a normalized direction.
+
+####   [direction](#group__dir_1ga7cc439bc60bbbe279bbda37f2e0d139b)(__m128 p3) noexcept  {#group__dir_1ga7cc439bc60bbbe279bbda37f2e0d139b}
+
+####  explicit  [direction](#group__dir_1ga42ce139ace571176acabbce21d6c64b2)(float * data) noexcept  {#group__dir_1ga42ce139ace571176acabbce21d6c64b2}
+
+Data should point to four floats with memory layout `(0.f, x, y, z)`  where the zero occupies the lowest address in memory.
+
+#### float  [x](#group__dir_1ga721087c2056a33cd780c678ae0ec39dd)() const noexcept  {#group__dir_1ga721087c2056a33cd780c678ae0ec39dd}
+
+#### float  [y](#group__dir_1ga40bc7052a639d57afde7a860c1631638)() const noexcept  {#group__dir_1ga40bc7052a639d57afde7a860c1631638}
+
+#### float  [z](#group__dir_1ga1e16d3ed0ff945d0d1cbf1e6458d334b)() const noexcept  {#group__dir_1ga1e16d3ed0ff945d0d1cbf1e6458d334b}
+
+#### void  [normalize](#group__dir_1ga143cd2cfeb94860ce1d47b9735064802)() noexcept  {#group__dir_1ga143cd2cfeb94860ce1d47b9735064802}
+
+Normalize this direction by dividing all components by the magnitude
+
+!!! tip 
+    Direction normalization divides the coordinates by the quantity
+    $\sqrt{x^2 + y^2 + z^2}$. This is done using the `rsqrtps`
+    instruction with a maximum relative error of $1.5\times 2^{-12}$.
+
+#### direction &KLN_VEC_CALL  [operator+=](#group__dir_1gabf098bdf982bbd9572d9fb09a5f76786)(direction b) noexcept  {#group__dir_1gabf098bdf982bbd9572d9fb09a5f76786}
+
+Direction addition.
+
+#### direction &KLN_VEC_CALL  [operator-=](#group__dir_1ga4bd0650e5c363ec427a4021b678f0567)(direction b) noexcept  {#group__dir_1ga4bd0650e5c363ec427a4021b678f0567}
+
+Direction subtraction.
+
+#### direction &  [operator*=](#group__dir_1ga8f2c363e3b6ce34e18451b6c716be97a)(float s) noexcept  {#group__dir_1ga8f2c363e3b6ce34e18451b6c716be97a}
+
+Direction uniform scale.
+
+#### direction &  [operator*=](#group__dir_1ga6a07c40530461b7a4c94d2aff1371217)(int s) noexcept  {#group__dir_1ga6a07c40530461b7a4c94d2aff1371217}
+
+Direction uniform scale.
+
+#### direction &  [operator/=](#group__dir_1ga9cac6b5beba3d2e2b0ce1e9a5158c25f)(float s) noexcept  {#group__dir_1ga9cac6b5beba3d2e2b0ce1e9a5158c25f}
+
+Direction uniform inverse scale.
+
+#### direction &  [operator/=](#group__dir_1ga2717db218937fdb1b88aba24d3abd189)(int s) noexcept  {#group__dir_1ga2717db218937fdb1b88aba24d3abd189}
+
+Direction uniform inverse scale.
+
+#### direction KLN_VEC_CALL  [operator+](#group__dir_1ga3aa93423517b128de3d64111201220ce)(direction a,direction b) noexcept  {#group__dir_1ga3aa93423517b128de3d64111201220ce}
+
+Direction addition.
+
+#### direction KLN_VEC_CALL  [operator-](#group__dir_1gacdc4f7208ad657c450708efcc7fe27d0)(direction a,direction b) noexcept  {#group__dir_1gacdc4f7208ad657c450708efcc7fe27d0}
+
+Direction subtraction.
+
+#### direction KLN_VEC_CALL  [operator*](#group__dir_1ga5d061f57e3a9f92620f6e90d5dbcb8cb)(direction d,float s) noexcept  {#group__dir_1ga5d061f57e3a9f92620f6e90d5dbcb8cb}
+
+Direction uniform scale.
+
+#### direction KLN_VEC_CALL  [operator*](#group__dir_1ga0a2f15a137d3c9ef3e5b83e3eee71f9a)(float s,direction d) noexcept  {#group__dir_1ga0a2f15a137d3c9ef3e5b83e3eee71f9a}
+
+Direction uniform scale.
+
+#### direction KLN_VEC_CALL  [operator*](#group__dir_1ga9d4aadcb32609919e0a2614b1041fdf0)(direction d,int s) noexcept  {#group__dir_1ga9d4aadcb32609919e0a2614b1041fdf0}
+
+Direction uniform scale.
+
+#### direction KLN_VEC_CALL  [operator*](#group__dir_1ga0229ad2276f2d9a7f07baee7ee3d7582)(int s,direction d) noexcept  {#group__dir_1ga0229ad2276f2d9a7f07baee7ee3d7582}
+
+Direction uniform scale.
+
+#### direction KLN_VEC_CALL  [operator/](#group__dir_1ga4473202567a1e1bf3a0929c33d723f52)(direction d,float s) noexcept  {#group__dir_1ga4473202567a1e1bf3a0929c33d723f52}
+
+Direction uniform inverse scale.
+
+#### direction KLN_VEC_CALL  [operator/](#group__dir_1ga2a8d9ef9111a21d1a55fe08e2c656317)(direction d,int s) noexcept  {#group__dir_1ga2a8d9ef9111a21d1a55fe08e2c656317}
+
+Direction uniform inverse scale.
+
+#### direction  [operator-](#group__dir_1ga65b1fe0cfac3611b65b78924cb5a61ac)(direction d) noexcept  {#group__dir_1ga65b1fe0cfac3611b65b78924cb5a61ac}
+
+Unary minus.
+
diff --git a/docs/api/dot.md b/docs/api/dot.md
@@ -0,0 +1,65 @@
+## group `dot` {#group__dot}
+
+The symmetric inner product takes two arguments and contracts the lower graded element to the greater graded element. If lower graded element spans an index that is not contained in the higher graded element, the result is annihilated. Otherwise, the result is the part of the higher graded element "most unlike" the lower graded element. Thus, the symmetric inner product can be thought of as a bidirectional contraction operator.
+
+There is some merit in providing both a left and right contraction operator for explicitness. However, when using Klein, it's generally clear what the interpretation of the symmetric inner product is with respect to the projection on various entities.
+
+!!! example Angle between planes 
+    ```cpp
+        kln::plane a{x1, y1, z1, d1};
+        kln::plane b{x2, y2, z2, d2};
+
+        // Compute the cos of the angle between two planes
+        float cos_ang = a | b;
+    ```
+
+
+!!! example Line to plane through point 
+    ```cpp
+        kln::point a{x1, y1, z1};
+        kln::plane b{x2, y2, z2, d2};
+
+        // The line l contains a and the shortest path from a to plane b.
+        line l = a | b;
+    ```
+
+### Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public float ` [`operator\|`](#group__dot_1gad318da9ce7f0d17c6be4a28606f7055d)`(plane a,plane b) noexcept`             | 
+`public plane ` [`operator\|`](#group__dot_1gac5eb4e0be057f05d06fdb47af9c67884)`(plane a,line b) noexcept`             | 
+`public plane ` [`operator\|`](#group__dot_1ga6e653adaf2281eb98ea2fb859adebf91)`(line b,plane a) noexcept`             | 
+`public plane ` [`operator\|`](#group__dot_1ga95c5016a18aac7ec611fbb69ade553eb)`(plane a,ideal_line b) noexcept`             | 
+`public plane ` [`operator\|`](#group__dot_1ga3672748f41be5a0c523e0434bb48da7d)`(ideal_line b,plane a) noexcept`             | 
+`public line ` [`operator\|`](#group__dot_1gaf165d820d2709047750f9f9c4e627dc2)`(plane a,point b) noexcept`             | 
+`public line ` [`operator\|`](#group__dot_1ga21190874d649c1828316b8133c8c7ec0)`(point a,plane b) noexcept`             | 
+`public float ` [`operator\|`](#group__dot_1gab9b2443f7c67a96f08b03ce749565305)`(line a,line b) noexcept`             | 
+`public plane ` [`operator\|`](#group__dot_1ga4319b71d30d700e2579c26e181fd16fd)`(point a,line b) noexcept`             | 
+`public plane ` [`operator\|`](#group__dot_1ga36111b62f962203bb1a964cd6417b371)`(line b,point a) noexcept`             | 
+`public float ` [`operator\|`](#group__dot_1ga4ad7845d5581052aca22d5547ef7d5b1)`(point a,point b) noexcept`             | 
+
+### Members
+
+#### float  [operator|](#group__dot_1gad318da9ce7f0d17c6be4a28606f7055d)(plane a,plane b) noexcept  {#group__dot_1gad318da9ce7f0d17c6be4a28606f7055d}
+
+#### plane  [operator|](#group__dot_1gac5eb4e0be057f05d06fdb47af9c67884)(plane a,line b) noexcept  {#group__dot_1gac5eb4e0be057f05d06fdb47af9c67884}
+
+#### plane  [operator|](#group__dot_1ga6e653adaf2281eb98ea2fb859adebf91)(line b,plane a) noexcept  {#group__dot_1ga6e653adaf2281eb98ea2fb859adebf91}
+
+#### plane  [operator|](#group__dot_1ga95c5016a18aac7ec611fbb69ade553eb)(plane a,ideal_line b) noexcept  {#group__dot_1ga95c5016a18aac7ec611fbb69ade553eb}
+
+#### plane  [operator|](#group__dot_1ga3672748f41be5a0c523e0434bb48da7d)(ideal_line b,plane a) noexcept  {#group__dot_1ga3672748f41be5a0c523e0434bb48da7d}
+
+#### line  [operator|](#group__dot_1gaf165d820d2709047750f9f9c4e627dc2)(plane a,point b) noexcept  {#group__dot_1gaf165d820d2709047750f9f9c4e627dc2}
+
+#### line  [operator|](#group__dot_1ga21190874d649c1828316b8133c8c7ec0)(point a,plane b) noexcept  {#group__dot_1ga21190874d649c1828316b8133c8c7ec0}
+
+#### float  [operator|](#group__dot_1gab9b2443f7c67a96f08b03ce749565305)(line a,line b) noexcept  {#group__dot_1gab9b2443f7c67a96f08b03ce749565305}
+
+#### plane  [operator|](#group__dot_1ga4319b71d30d700e2579c26e181fd16fd)(point a,line b) noexcept  {#group__dot_1ga4319b71d30d700e2579c26e181fd16fd}
+
+#### plane  [operator|](#group__dot_1ga36111b62f962203bb1a964cd6417b371)(line b,point a) noexcept  {#group__dot_1ga36111b62f962203bb1a964cd6417b371}
+
+#### float  [operator|](#group__dot_1ga4ad7845d5581052aca22d5547ef7d5b1)(point a,point b) noexcept  {#group__dot_1ga4ad7845d5581052aca22d5547ef7d5b1}
+
diff --git a/docs/api/dual.md b/docs/api/dual.md
@@ -0,0 +1,31 @@
+## group `dual` {#group__dual}
+
+The Poincaré Dual of an element is the "subspace complement" of the argument with respect to the pseudoscalar in the exterior algebra. In practice, it is a relabeling of the coordinates to their dual-coordinates and is used most often to implement a "join" operation in terms of the exterior product of the duals of each operand.
+
+Ex: The dual of the point $\mathbf{e}_{123} + 3\mathbf{e}_{013} - 2\mathbf{e}_{021}$ (the point at $(0, 3, -2)$) is the plane $\mathbf{e}_0 + 3\mathbf{e}_2 - 2\mathbf{e}_3$.
+
+### Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public KLN_INLINE point KLN_VEC_CALL ` [`operator!`](#group__dual_1ga3a687310cf04e42ff485b03d557ed5a0)`(plane in) noexcept`             | 
+`public KLN_INLINE plane KLN_VEC_CALL ` [`operator!`](#group__dual_1ga105ff06095b7eb1fc4ab4b345d7aefb1)`(point in) noexcept`             | 
+`public KLN_INLINE line KLN_VEC_CALL ` [`operator!`](#group__dual_1gaa54dbe6355262d69f4302296708cc3fd)`(line in) noexcept`             | 
+`public KLN_INLINE branch KLN_VEC_CALL ` [`operator!`](#group__dual_1gac57689e4bf002977c93dbb5e162f7a73)`(ideal_line in) noexcept`             | 
+`public KLN_INLINE ideal_line KLN_VEC_CALL ` [`operator!`](#group__dual_1gaba4e70ba96775d4bda3676593256a6be)`(branch in) noexcept`             | 
+`public KLN_INLINE dual KLN_VEC_CALL ` [`operator!`](#group__dual_1ga322859aabdd00a64e316ef1d4923a266)`(dual in) noexcept`             | 
+
+### Members
+
+#### KLN_INLINE point KLN_VEC_CALL  [operator!](#group__dual_1ga3a687310cf04e42ff485b03d557ed5a0)(plane in) noexcept  {#group__dual_1ga3a687310cf04e42ff485b03d557ed5a0}
+
+#### KLN_INLINE plane KLN_VEC_CALL  [operator!](#group__dual_1ga105ff06095b7eb1fc4ab4b345d7aefb1)(point in) noexcept  {#group__dual_1ga105ff06095b7eb1fc4ab4b345d7aefb1}
+
+#### KLN_INLINE line KLN_VEC_CALL  [operator!](#group__dual_1gaa54dbe6355262d69f4302296708cc3fd)(line in) noexcept  {#group__dual_1gaa54dbe6355262d69f4302296708cc3fd}
+
+#### KLN_INLINE branch KLN_VEC_CALL  [operator!](#group__dual_1gac57689e4bf002977c93dbb5e162f7a73)(ideal_line in) noexcept  {#group__dual_1gac57689e4bf002977c93dbb5e162f7a73}
+
+#### KLN_INLINE ideal_line KLN_VEC_CALL  [operator!](#group__dual_1gaba4e70ba96775d4bda3676593256a6be)(branch in) noexcept  {#group__dual_1gaba4e70ba96775d4bda3676593256a6be}
+
+#### KLN_INLINE dual KLN_VEC_CALL  [operator!](#group__dual_1ga322859aabdd00a64e316ef1d4923a266)(dual in) noexcept  {#group__dual_1ga322859aabdd00a64e316ef1d4923a266}
+
diff --git a/docs/api/dualn.md b/docs/api/dualn.md
@@ -0,0 +1,26 @@
+## group `dualn` {#group__dualn}
+
+A dual number is a multivector of the form $p + q\mathbf{e}_{0123}$.
+
+### Summary
+
+ Members                        | Descriptions                                
+--------------------------------|---------------------------------------------
+`public dual KLN_VEC_CALL ` [`operator+`](#group__dualn_1gad54e557339dd7c8929fb70177ce99431)`(dual a,dual b) noexcept`             | 
+`public dual KLN_VEC_CALL ` [`operator-`](#group__dualn_1gac3c6b82d268dbc0ce92a43479952f30a)`(dual a,dual b) noexcept`             | 
+`public dual KLN_VEC_CALL ` [`operator*`](#group__dualn_1gaaad721d43b803f0bf57bc8d1454dd824)`(dual a,float s) noexcept`             | 
+`public dual KLN_VEC_CALL ` [`operator*`](#group__dualn_1ga061a15005779a7687ab40e54a3257fca)`(float s,dual a) noexcept`             | 
+`public dual KLN_VEC_CALL ` [`operator/`](#group__dualn_1ga2c6bedacc94979d14173bd340aefd6d5)`(dual a,float s) noexcept`             | 
+
+### Members
+
+#### dual KLN_VEC_CALL  [operator+](#group__dualn_1gad54e557339dd7c8929fb70177ce99431)(dual a,dual b) noexcept  {#group__dualn_1gad54e557339dd7c8929fb70177ce99431}
+
+#### dual KLN_VEC_CALL  [operator-](#group__dualn_1gac3c6b82d268dbc0ce92a43479952f30a)(dual a,dual b) noexcept  {#group__dualn_1gac3c6b82d268dbc0ce92a43479952f30a}
+
+#### dual KLN_VEC_CALL  [operator*](#group__dualn_1gaaad721d43b803f0bf57bc8d1454dd824)(dual a,float s) noexcept  {#group__dualn_1gaaad721d43b803f0bf57bc8d1454dd824}
+
+#### dual KLN_VEC_CALL  [operator*](#group__dualn_1ga061a15005779a7687ab40e54a3257fca)(float s,dual a) noexcept  {#group__dualn_1ga061a15005779a7687ab40e54a3257fca}
+
+#### dual KLN_VEC_CALL  [operator/](#group__dualn_1ga2c6bedacc94979d14173bd340aefd6d5)(dual a,float s) noexcept  {#group__dualn_1ga2c6bedacc94979d14173bd340aefd6d5}
+