[eigen] rename organize eigen file and documentation (#66)

Author: FrancoisCarouge

include/fcarouge/internal/kalman_eigen.hpp include/fcarouge/internal/eigen.hpp

@@ -36,8 +36,8 @@ OTHER DEALINGS IN THE SOFTWARE.
 
 For more information, please refer to <https://unlicense.org> */
 
-#ifndef FCAROUGE_INTERNAL_KALMAN_EIGEN_HPP
-#define FCAROUGE_INTERNAL_KALMAN_EIGEN_HPP
+#ifndef FCAROUGE_INTERNAL_EIGEN_HPP
+#define FCAROUGE_INTERNAL_EIGEN_HPP
 
 //! @file
 //! @brief Kalman operation for Eigen 3 types.
@@ -255,4 +255,4 @@ using kalman = fcarouge::kalman<
 
 } // namespace fcarouge::eigen::internal
 
-#endif // FCAROUGE_INTERNAL_KALMAN_EIGEN_HPP
+#endif // FCAROUGE_INTERNAL_EIGEN_HPP

include/fcarouge/internal/format.hpp

@@ -0,0 +1,42 @@
+/*_  __          _      __  __          _   _
+ | |/ /    /\   | |    |  \/  |   /\   | \ | |
+ | ' /    /  \  | |    | \  / |  /  \  |  \| |
+ |  <    / /\ \ | |    | |\/| | / /\ \ | . ` |
+ | . \  / ____ \| |____| |  | |/ ____ \| |\  |
+ |_|\_\/_/    \_\______|_|  |_/_/    \_\_| \_|
+
+Kalman Filter for C++
+Version 0.1.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> */
+
+#ifndef FCAROUGE_INTERNAL_FORMAT_HPP
+#define FCAROUGE_INTERNAL_FORMAT_HPP
+
+#endif // FCAROUGE_INTERNAL_FORMAT_HPP

include/fcarouge/kalman.hpp

@@ -42,6 +42,7 @@ For more information, please refer to <https://unlicense.org> */
 //! @file
 //! @brief The main Kalman filter class.
 
+#include "internal/format.hpp"
 #include "internal/kalman.hpp"
 
 #include <concepts>
@@ -602,6 +603,11 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
 
   //! @brief Sets the state transition matrix F function.
   //!
+  //! @details For non-linear system, or extended filter, F is the Jacobian of
+  //! the state transition function: `F = ∂f/∂X = ∂fj/∂xi` that is each row i
+  //! contains the derivatives of the state transition function for every
+  //! element j in the state vector X.
+  //!
   //! @param callable The copied target Callable object (function object,
   //! pointer to function, reference to function, pointer to member function, or
   //! pointer to data member) that will be bound to the prediction arguments and
@@ -619,6 +625,11 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
 
   //! @brief Sets the state transition matrix F function.
   //!
+  //! @details For non-linear system, or extended filter, F is the Jacobian of
+  //! the state transition function: `F = ∂f/∂X = ∂fj/∂xi` that is each row i
+  //! contains the derivatives of the state transition function for every
+  //! element j in the state vector X.
+  //!
   //! @param callable The moved target Callable object (function object,
   //! pointer to function, reference to function, pointer to member function, or
   //! pointer to data member) that will be bound to the prediction arguments and
@@ -679,6 +690,11 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
 
   //! @brief Sets the observation, measurement transition matrix H function.
   //!
+  //! @details For non-linear system, or extended filter, H is the Jacobian of
+  //! the state observation function: `H = ∂h/∂X = ∂hj/∂xi` that is each row i
+  //! contains the derivatives of the state observation function for every
+  //! element j in the state vector X.
+  //!
   //! @param callable The copied target Callable object (function object,
   //! pointer to function, reference to function, pointer to member function, or
   //! pointer to data member) that will be bound to the prediction arguments and
@@ -698,6 +714,11 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
 
   //! @brief Sets the observation, measurement transition matrix H function.
   //!
+  //! @details For non-linear system, or extended filter, H is the Jacobian of
+  //! the state observation function: `H = ∂h/∂X = ∂hj/∂xi` that is each row i
+  //! contains the derivatives of the state observation function for every
+  //! element j in the state vector X.
+  //!
   //! @param callable The moved target Callable object (function object,
   //! pointer to function, reference to function, pointer to member function, or
   //! pointer to data member) that will be bound to the prediction arguments and
@@ -817,6 +838,17 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
               "discarded.")]] inline constexpr auto
   s() const -> innovation_uncertainty;
 
+  //! @brief Sets the extended state transition function f(x).
+  //!
+  //! @param callable The copied target Callable object (function object,
+  //! pointer to function, reference to function, pointer to member function, or
+  //! pointer to data member) that will be called to compute the next state X on
+  //! prediction steps. The default function `f(x) = F * X` is suitable for
+  //! linear systems. For non-linear system, or extended filter, implement a
+  //! linearization of the transition function f and the state transition F
+  //! matrix is the Jacobian of the state transition function.
+  //!
+  //! @complexity Constant.
   inline constexpr void
       transition(const auto &callable) requires std::is_invocable_r_v < state,
       std::decay_t<decltype(callable)>,
@@ -825,6 +857,17 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
     filter.transition = callable;
   }
 
+  //! @brief Sets the extended state transition function f(x).
+  //!
+  //! @param callable The moved target Callable object (function object,
+  //! pointer to function, reference to function, pointer to member function, or
+  //! pointer to data member) that will be called to compute the next state X on
+  //! prediction steps. The default function `f(x) = F * X` is suitable for
+  //! linear systems. For non-linear system, or extended filter, implement a
+  //! linearization of the transition function f and the state transition F
+  //! matrix is the Jacobian of the state transition function.
+  //!
+  //! @complexity Constant.
   inline constexpr void
       transition(auto &&callable) requires std::is_invocable_r_v < state,
       std::decay_t<decltype(callable)>,
@@ -833,6 +876,17 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
     filter.transition = std::forward<decltype(callable)>(callable);
   }
 
+  //! @brief Sets the extended state observation function h(x).
+  //!
+  //! @param callable The copied target Callable object (function object,
+  //! pointer to function, reference to function, pointer to member function, or
+  //! pointer to data member) that will be called to compute the observation Z
+  //! on update steps. The default function `h(x) = H * X` is suitable for
+  //! linear systems. For non-linear system, or extended filter, the client
+  //! implements a linearization of the observation function hand the state
+  //! observation H matrix is the Jacobian of the state observation function.
+  //!
+  //! @complexity Constant.
   inline constexpr void
       observation(const auto &callable) requires std::is_invocable_r_v < output,
       std::decay_t<decltype(callable)>,
@@ -841,6 +895,17 @@ class kalman<Type, State, Output, Input, Transpose, Symmetrize, Divide,
     filter.observation = callable;
   }
 
+  //! @brief Sets the extended state observation function h(x).
+  //!
+  //! @param callable The moved target Callable object (function object,
+  //! pointer to function, reference to function, pointer to member function, or
+  //! pointer to data member) that will be called to compute the observation Z
+  //! on update steps. The default function `h(x) = H * X` is suitable for
+  //! linear systems. For non-linear system, or extended filter, the client
+  //! implements a linearization of the observation function hand the state
+  //! observation H matrix is the Jacobian of the state observation function.
+  //!
+  //! @complexity Constant.
   inline constexpr void
       observation(auto &&callable) requires std::is_invocable_r_v < output,
       std::decay_t<decltype(callable)>,

include/fcarouge/kalman_eigen.hpp

@@ -42,7 +42,7 @@ For more information, please refer to <https://unlicense.org> */
 //! @file
 //! @brief Kalman operation for Eigen 3 types.
 
-#include "internal/kalman_eigen.hpp"
+#include "internal/eigen.hpp"
 
 #include <cstddef>
 #include <tuple>