[linalg] improve documentation (#360)

benchmark/CMakeLists.txt

@@ -70,7 +70,7 @@ foreach(BENCHMARK "baseline.cpp" "predict_1x1x0.cpp" "predict_1x1x1.cpp"
            "--benchmark_out=${NAME}.json")
 endforeach()
 
-foreach(BACKEND IN ITEMS "eigen")
+foreach(BACKEND IN ITEMS "eigen" "lazy")
   foreach(STATE_SIZE RANGE 1 2)
     foreach(INPUT_SIZE RANGE 1 2)
       configure_file(predict_linalg_x1x.cpp

linalg/lazy/fcarouge/linalg.hpp

@@ -101,11 +101,12 @@ inline constexpr auto make_generator(Type element) -> std::generator<Type> {
 //! @note A design decision for the composed generator to be mutable, traded
 //! off for const member function API. Similar to the mutable mutex member
 //! practice.
-//! @note Why genie? Because genies generate on demand.
+//! @note Why genie? Because genies generate on demand...
 //!
 //! @todo Explore and compare performance.
 //! @todo Explore optimization of heap allocations?
 //! @todo Explore constexpr support?
+//! @todo Explore an implementation where each element is a generator?
 //! @todo Explore verification of lazy evaluation?
 //! @todo Remove unecessary empty paramaters when MSVC supports lambda without
 //! them.
@@ -155,7 +156,8 @@ struct matrix {
     return *this;
   }
 
-  inline constexpr explicit matrix(const std::same_as<Type> auto &...elements)
+  inline constexpr explicit(false)
+      matrix(const std::same_as<Type> auto &...elements)
     requires(sizeof...(elements) == Row * Column)
       : genie{[](auto... elements_copy) -> std::generator<Type> {
           (co_yield elements_copy, ...);
@@ -370,6 +372,15 @@ operator==(matrix<Type, Row, Column, CopyableOrNot1> lhs,
   return lhs_elements == rhs_elements;
 }
 
+template <typename Type, auto Row, auto Column>
+[[nodiscard]] inline matrix<Type, Row, Column>
+operator*(matrix<Type, Row, Column> lhs, arithmetic auto rhs) {
+  auto next{lhs.begin()};
+  for (auto k{Row * Column}; k > 0; --k, ++next) {
+    co_yield *next *rhs;
+  }
+}
+
 template <typename Type, auto Row, auto Size>
 [[nodiscard]] inline matrix<Type, Row, 1> operator*(matrix<Type, Row, Size> lhs,
                                                     matrix<Type, Size, 1> rhs) {
@@ -386,12 +397,14 @@ template <typename Type, auto Row, auto Size>
   }
 }
 
-template <typename Type, auto Row, auto Column>
+//! @todo Implement me.
+template <typename Type, auto Row, auto Size, auto Column>
 [[nodiscard]] inline matrix<Type, Row, Column>
-operator*(matrix<Type, Row, Column> lhs, arithmetic auto rhs) {
-  auto next{lhs.begin()};
-  for (auto k{Row * Column}; k > 0; --k, ++next) {
-    co_yield *next *rhs;
+operator*(matrix<Type, Row, Size> lhs, matrix<Type, Size, Column> rhs) {
+  static_cast<void>(lhs);
+  static_cast<void>(rhs);
+  for (auto k{Row * Column}; k > 0; --k) {
+    co_yield Type{};
   }
 }
 
@@ -410,6 +423,16 @@ operator+(matrix<Type, Row, Column> lhs, matrix<Type, Row, Column> rhs) {
     co_yield *next1 + *next2;
   }
 }
+
+//! @todo Implement me.
+template <typename Type, auto Row, auto Column>
+[[nodiscard]] inline matrix<Type, Column, Row>
+transpose(matrix<Type, Row, Column> other) {
+  static_cast<void>(other);
+  for (auto k{Row * Column}; k > 0; --k) {
+    co_yield Type{};
+  }
+}
 } // namespace fcarouge
 
 #endif // FCAROUGE_LINALG_HPP

test/CMakeLists.txt

@@ -122,11 +122,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"
@@ -147,3 +149,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_zero.cpp

@@ -44,17 +44,32 @@ namespace fcarouge::test {
 namespace {
 //! @test Verifies the zero matrices values are null.
 [[maybe_unused]] auto test{[] {
-  auto zero{zero_v<matrix<double, 3, 3>>};
-
-  assert(zero(0, 0) == 0.0);
-  assert(zero(0, 1) == 0.0);
-  assert(zero(0, 2) == 0.0);
-  assert(zero(1, 0) == 0.0);
-  assert(zero(1, 1) == 0.0);
-  assert(zero(1, 2) == 0.0);
-  assert(zero(2, 0) == 0.0);
-  assert(zero(2, 1) == 0.0);
-  assert(zero(2, 2) == 0.0);
+  auto zero1{zero_v<matrix<double, 2, 2>>};
+  auto zero2{zero1};
+  auto zero3{zero_v<matrix<double, 2, 2>>};
+  matrix<double, 2, 2> zero4{zero2};
+  matrix<double, 2, 2> zero5{zero_v<matrix<double, 2, 2>>};
+
+  // assert(zero1(0, 0) == 0.0);
+  // assert(zero1(0, 1) == 0.0);
+  // assert(zero1(1, 0) == 0.0);
+  // assert(zero1(1, 1) == 0.0);
+  // assert(zero2(0, 0) == 0.0);
+  // assert(zero2(0, 1) == 0.0);
+  // assert(zero2(1, 0) == 0.0);
+  // assert(zero2(1, 1) == 0.0);
+  // assert(zero3(0, 0) == 0.0);
+  // assert(zero3(0, 1) == 0.0);
+  // assert(zero3(1, 0) == 0.0);
+  // assert(zero3(1, 1) == 0.0);
+  // assert(zero4(0, 0) == 0.0);
+  // assert(zero4(0, 1) == 0.0);
+  // assert(zero4(1, 0) == 0.0);
+  // assert(zero4(1, 1) == 0.0);
+  // assert(zero5(0, 0) == 0.0);
+  // assert(zero5(0, 1) == 0.0);
+  // assert(zero5(1, 0) == 0.0);
+  // assert(zero5(1, 1) == 0.0);
 
   return 0;
 }()};