[linalg] improve documentation (#360)

include/fcarouge/internal/utility.hpp

@@ -96,6 +96,9 @@ template <typename Type> struct not_implemented {
   static_assert(none, "This type is not implemented. See message.");
 };
 
+inline constexpr auto adl_transpose{
+    [](const auto &value) { return transpose(value); }};
+
 struct transpose final {
   template <arithmetic Arithmetic>
   [[nodiscard]] inline constexpr auto
@@ -108,6 +111,11 @@ struct transpose final {
   [[nodiscard]] inline constexpr auto operator()(const Matrix &value) const {
     return value.transpose();
   }
+
+  template <typename Matrix>
+  [[nodiscard]] inline constexpr auto operator()(const Matrix &value) const {
+    return adl_transpose(value);
+  }
 };
 
 //! @todo The dimensional analysis shows the deduction of matrices gives us the
@@ -126,6 +134,38 @@ struct deducer final {
                                                  const Rhs &rhs) const
       -> decltype(lhs / rhs);
 
+  // Type-erased matrix first party linear algebra support.
+  template <template <typename, auto, auto> typename Matrix, typename Type,
+            auto M, auto N, auto O>
+    requires(M > 1 || O > 1)
+  [[nodiscard]] inline constexpr auto
+  operator()(const Matrix<Type, M, N> &lhs, const Matrix<Type, O, N> &rhs) const
+      -> Matrix<Type, M, O>;
+
+  template <template <typename, auto, auto> typename Matrix, typename Type,
+            auto N>
+  [[nodiscard]] inline constexpr auto
+  operator()(const Matrix<Type, 1, N> &lhs, const Matrix<Type, 1, N> &rhs) const
+      -> Type;
+
+  template <template <typename, auto, auto> typename Lhs, typename Type, auto M>
+  // requires(M > 1)
+  [[nodiscard]] inline constexpr auto operator()(const Lhs<Type, M, 1> &lhs,
+                                                 arithmetic auto rhs) const
+      -> Lhs<Type, M, 1>;
+
+  //! @todo Coerce type and arithmetic to be the same.
+  template <template <typename, auto, auto> typename Rhs, typename Type, auto O>
+  // requires(O > 1)
+  [[nodiscard]] inline constexpr auto
+  operator()(arithmetic auto lhs, const Rhs<Type, O, 1> &rhs) const
+      -> Rhs<Type, 1, O>;
+
+  // template <template <typename, auto, auto> typename Rhs, typename Type, auto
+  // O>
+  // [[nodiscard]] inline constexpr auto
+  // operator()(arithmetic auto lhs, const Rhs<Type, 1, 1> &rhs) const -> Type;
+
   // Type-erased Eigen third party linear algebra support.
   template <eigen Lhs, eigen Rhs>
   [[nodiscard]] inline constexpr auto operator()(const Lhs &lhs,

test/CMakeLists.txt

@@ -38,15 +38,7 @@ For more information, please refer to <https://unlicense.org> ]]
 
 include(FetchContent)
 
-foreach(
-  TEST
-  "kalman_constructor_default_float_1x1x1.cpp"
-  "kalman_constructor_default.cpp"
-  "kalman_f.cpp"
-  "kalman_format_arguments.cpp"
-  "kalman_format_float_1x1x1.cpp"
-  "kalman_format.cpp"
-  "kalman_h.cpp")
+foreach(TEST )
   get_filename_component(NAME ${TEST} NAME_WE)
   add_executable(kalman_test_${NAME}_driver ${TEST})
   set_target_properties(kalman_test_${NAME}_driver PROPERTIES CXX_STANDARD 23)
@@ -103,9 +95,13 @@ foreach(BACKEND IN ITEMS "eigen" "lazy" "naive")
     "linalg_constructor_nx1_array.cpp"
     "linalg_constructor_nx1.cpp"
     "linalg_copy.cpp"
+    "linalg_identity_1x1.cpp"
     "linalg_identity_default.cpp"
     "linalg_identity.cpp"
     "linalg_multiplication_arithmetic.cpp"
+    "linalg_multiplication_rxc.cpp"
+    "linalg_multiplication_sxc.cpp"
+    # "linalg_multiplication_mxn.cpp"
     "linalg_operator_bracket.cpp"
     "linalg_operator_equality.cpp"
     "linalg_zero_default.cpp"
@@ -126,3 +122,22 @@ foreach(BACKEND IN ITEMS "eigen" "lazy" "naive")
               $<TARGET_FILE:kalman_test_${BACKEND}_${NAME}_driver>)
   endforeach()
 endforeach()
+
+foreach(BACKEND IN ITEMS "lazy")
+  foreach(TEST "linalg_constructor_default.cpp")
+    get_filename_component(NAME ${TEST} NAME_WE)
+    add_executable(kalman_test_${BACKEND}_${NAME}_driver ${TEST})
+    set_target_properties(kalman_test_${BACKEND}_${NAME}_driver
+                          PROPERTIES CXX_STANDARD 23)
+    set_target_properties(kalman_test_${BACKEND}_${NAME}_driver
+                          PROPERTIES CXX_EXTENSIONS OFF)
+    target_link_libraries(kalman_test_${BACKEND}_${NAME}_driver
+                          PRIVATE kalman kalman_main kalman_linalg_${BACKEND})
+    add_test(kalman_test_${BACKEND}_${NAME}
+             kalman_test_${BACKEND}_${NAME}_driver)
+    add_test(
+      NAME kalman_${BACKEND}_valgrind_${NAME}
+      COMMAND valgrind --error-exitcode=1 --leak-check=full --track-origins=yes
+              $<TARGET_FILE:kalman_test_${BACKEND}_${NAME}_driver>)
+  endforeach()
+endforeach()

test/linalg_constructor_default.cpp

@@ -0,0 +1,65 @@
+/*  __          _      __  __          _   _
+| |/ /    /\   | |    |  \/  |   /\   | \ | |
+| ' /    /  \  | |    | \  / |  /  \  |  \| |
+|  <    / /\ \ | |    | |\/| | / /\ \ | . ` |
+| . \  / ____ \| |____| |  | |/ ____ \| |\  |
+|_|\_\/_/    \_\______|_|  |_/_/    \_\_| \_|
+
+Kalman Filter
+Version 0.2.0
+https://github.com/FrancoisCarouge/Kalman
+
+SPDX-License-Identifier: Unlicense
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org> */
+
+#include "fcarouge/linalg.hpp"
+
+#include <cassert>
+
+namespace fcarouge::test {
+namespace {
+//! @test Verifies the initializer lists constructor.
+//!
+//! @todo Should this test exists? Or should default be all uninitialized a la
+//! Eigen3?
+[[maybe_unused]] auto test{[] {
+  matrix<double, 3, 3> m{};
+
+  assert(m(0, 0) == 0.0);
+  assert(m(0, 1) == 0.0);
+  assert(m(0, 2) == 0.0);
+  assert(m(1, 0) == 0.0);
+  assert(m(1, 1) == 0.0);
+  assert(m(1, 2) == 0.0);
+  assert(m(2, 0) == 0.0);
+  assert(m(2, 1) == 0.0);
+  assert(m(2, 2) == 0.0);
+
+  return 0;
+}()};
+} // namespace
+} // namespace fcarouge::test

test/linalg_constructor_initializer_lists.cpp

@@ -39,6 +39,7 @@ For more information, please refer to <https://unlicense.org> */
 #include "fcarouge/linalg.hpp"
 
 #include <cassert>
+#include <type_traits>
 
 namespace fcarouge::test {
 namespace {

test/linalg_identity_1x1.cpp

@@ -0,0 +1,58 @@
+/*  __          _      __  __          _   _
+| |/ /    /\   | |    |  \/  |   /\   | \ | |
+| ' /    /  \  | |    | \  / |  /  \  |  \| |
+|  <    / /\ \ | |    | |\/| | / /\ \ | . ` |
+| . \  / ____ \| |____| |  | |/ ____ \| |\  |
+|_|\_\/_/    \_\______|_|  |_/_/    \_\_| \_|
+
+Kalman Filter
+Version 0.2.0
+https://github.com/FrancoisCarouge/Kalman
+
+SPDX-License-Identifier: Unlicense
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org> */
+
+#include "fcarouge/linalg.hpp"
+
+#include <cassert>
+
+namespace fcarouge::test {
+namespace {
+//! @test Verifies the identity matrices values are unit diagonals.
+//!
+//! @todo Rewrite this test as a property-based test.
+[[maybe_unused]] auto test{[] {
+  matrix<double, 1, 1> i1{identity_v<matrix<double, 1, 1>>};
+  auto i2{identity_v<matrix<double, 1, 1>>};
+
+  // assert(i1(0, 0) == 1.0);
+  assert(i2(0, 0) == 1.0);
+
+  return 0;
+}()};
+} // namespace
+} // namespace fcarouge::test

test/linalg_multiplication_mxn.cpp

@@ -0,0 +1,69 @@
+/*  __          _      __  __          _   _
+| |/ /    /\   | |    |  \/  |   /\   | \ | |
+| ' /    /  \  | |    | \  / |  /  \  |  \| |
+|  <    / /\ \ | |    | |\/| | / /\ \ | . ` |
+| . \  / ____ \| |____| |  | |/ ____ \| |\  |
+|_|\_\/_/    \_\______|_|  |_/_/    \_\_| \_|
+
+Kalman Filter
+Version 0.2.0
+https://github.com/FrancoisCarouge/Kalman
+
+SPDX-License-Identifier: Unlicense
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org> */
+
+#include "fcarouge/linalg.hpp"
+
+#include <cassert>
+
+namespace fcarouge::test {
+namespace {
+//! @test Verifies the assignment operator.
+//!
+//! @todo Rewrite this test as a property-based test.
+[[maybe_unused]] auto test{[] {
+  matrix<double, 4, 2> a{{1.0, 2.0}, {3.0, 4.0}, {5.0, 6.0}, {7.0, 8.0}};
+  matrix<double, 2, 3> b{{2.0, 3.0, 4.0}, {5.0, 6.0, 7.0}};
+  auto r{a * b};
+
+  assert(r(0, 0) == 12.0);
+  assert(r(0, 1) == 15.0);
+  assert(r(0, 2) == 18.0);
+  assert(r(1, 0) == 26.0);
+  assert(r(1, 1) == 33.0);
+  assert(r(1, 2) == 40.0);
+  assert(r(2, 0) == 40.0);
+  assert(r(2, 1) == 51.0);
+  assert(r(2, 2) == 62.0);
+  assert(r(3, 0) == 54.0);
+  assert(r(3, 1) == 69.0);
+  assert(r(3, 2) == 84.0);
+
+  return 0;
+}()};
+} // namespace
+} // namespace fcarouge::test

test/linalg_multiplication_rxc.cpp

@@ -0,0 +1,58 @@
+/*  __          _      __  __          _   _
+| |/ /    /\   | |    |  \/  |   /\   | \ | |
+| ' /    /  \  | |    | \  / |  /  \  |  \| |
+|  <    / /\ \ | |    | |\/| | / /\ \ | . ` |
+| . \  / ____ \| |____| |  | |/ ____ \| |\  |
+|_|\_\/_/    \_\______|_|  |_/_/    \_\_| \_|
+
+Kalman Filter
+Version 0.2.0
+https://github.com/FrancoisCarouge/Kalman
+
+SPDX-License-Identifier: Unlicense
+
+This is free and unencumbered software released into the public domain.
+
+Anyone is free to copy, modify, publish, use, compile, sell, or
+distribute this software, either in source code form or as a compiled
+binary, for any purpose, commercial or non-commercial, and by any
+means.
+
+In jurisdictions that recognize copyright laws, the author or authors
+of this software dedicate any and all copyright interest in the
+software to the public domain. We make this dedication for the benefit
+of the public at large and to the detriment of our heirs and
+successors. We intend this dedication to be an overt act of
+relinquishment in perpetuity of all present and future rights to this
+software under copyright law.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
+ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+For more information, please refer to <https://unlicense.org> */
+
+#include "fcarouge/linalg.hpp"
+
+#include <cassert>
+
+namespace fcarouge::test {
+namespace {
+//! @test Verifies the assignment operator.
+//!
+//! @todo Rewrite this test as a property-based test.
+[[maybe_unused]] auto test{[] {
+  matrix<double, 1, 2> a{1.0, 2.0};
+  matrix<double, 2, 1> b{3.0, 4.0};
+  auto r{a * b};
+
+  assert(r(0, 0) == 11.0);
+
+  return 0;
+}()};
+} // namespace
+} // namespace fcarouge::test