library_interface.hpp

Go to the documentation of this file.

/* This file is part of OpenKalman, a header-only C++ library for
 * Kalman filters and other recursive filters.
 *
 * Copyright (c) 2022-2025 Christopher Lee Ogden <ogden@gatech.edu>
 *
 * This Source Code Form is subject to the terms of the Mozilla Public
 * License, v. 2.0. If a copy of the MPL was not distributed with this
 * file, You can obtain one at https://mozilla.org/MPL/2.0/.
 */

#ifndef OPENKALMAN_LIBRARY_INTERFACE_HPP
#define OPENKALMAN_LIBRARY_INTERFACE_HPP

#ifdef DOXYGEN_SHOULD_SKIP_THIS
#include "coordinates/coordinates.hpp"
#include "linear-algebra/enumerations.hpp"
#include "linear-algebra/traits/element_type_of.hpp"
#include "linear-algebra/concepts/internal/layout_mapping_policy.hpp"
#include "linear-algebra/concepts/internal/slice_specifier.hpp"
#endif

namespace OpenKalman::interface
{
#ifdef __cpp_concepts
  template<typename T>
#else
  template<typename T, typename = void>
#endif
  struct library_interface
  {
#ifdef DOXYGEN_SHOULD_SKIP_THIS

    template<typename Derived>
    using library_base = std::monostate;


    static constexpr auto
    copy_from = [](T& t, indexible auto&& other) -> void
    {
      // ...
    };


    static constexpr auto
    make_constant = [](const values::scalar auto& c, coordinates::euclidean_pattern_collection auto&& d)
      -> constexpr_matrix auto
    {
      // ...
    };


    static constexpr auto
    to_diagonal = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> diagonal_matrix auto
    {
      // ...
    };


    static constexpr auto
    conjugate = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> constexpr patterns_may_match_with<Arg>
    {
      // ...
    };


    static constexpr auto
    transpose = []<typename Arg> requires
        std::same_as<std::remove_cvref_t<Arg>, T> and
        dimension_size_of_index_is<0, index_dimension_of_v<T, 1>, &stdex::is_eq, applicability::permitted>
      (Arg&& arg) -> dimension_size_of_index_is<0, index_dimension_of_v<T, 1>, &stdex::is_eq, applicability::permitted> decltype(auto)
    {
      // ...
    };


    template<std::size_t indexa, std::size_t indexb>
    static constexpr auto
    transpose = []<typename Arg> requires
        std::same_as<std::remove_cvref_t<Arg>, T> and
        dimension_size_of_index_is<indexa, index_dimension_of_v<T, indexb>, &stdex::is_eq, applicability::permitted>
      (Arg&& arg) -> dimension_size_of_index_is<indexa, index_dimension_of_v<T, indexb>, &stdex::is_eq, applicability::permitted> decltype(auto)
    {
      // ...
    };


    static constexpr auto
    adjoint = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> dimension_size_of_index_is<0, index_dimension_of_v<T, 1>, &stdex::is_eq, applicability::permitted> decltype(auto)
    {
      // ...
    };


    template<std::size_t indexa, std::size_t indexb>
    static constexpr auto
    adjoint = []<typename Arg> requires
        std::same_as<std::remove_cvref_t<Arg>, T> and
        dimension_size_of_index_is<indexa, index_dimension_of_v<T, indexb>, &stdex::is_eq, applicability::permitted>
      (Arg&& arg) -> dimension_size_of_index_is<indexa, index_dimension_of_v<T, indexb>, &stdex::is_eq, applicability::permitted> decltype(auto)
    {
      // ...
    };


    template<values::number Scalar>
    static constexpr auto
    make_identity_matrix = [](coordinates::euclidean_pattern_collection auto&& d) -> identity_matrix auto
    {
      // ...
    };


    template<triangle_type tri>
    static constexpr auto
    make_triangular_matrix = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> triangular_matrix<tri> decltype(auto)
    {
      // ...
    };


    template<HermitianAdapterType h>
    static constexpr auto
    make_hermitian_adapter = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> hermitian_matrix<h> decltype(auto)
    {
      // ...
    };


    //template<internal::layout_mapping_policy layout, values::number Scalar> requires
    //  std::same_as<layout, stdex::layout_left> or std::same_as<layout, stdex::layout_right>
    //static constexpr auto
    //make_default = [](const coordinates::euclidean_pattern_collection auto& descriptors) -> indexible auto
    //{
    //  // ...
    //};


    //template<internal::layout_mapping_policy layout> requires
    //  (std::same_as<layout, stdex::layout_left> or std::same_as<layout, stdex::layout_right>) and writable<T>
    //static constexpr auto
    //fill_components = []<typename Scalars> requires std::convertible_to<collections::common_collection_type_t<Scalars>, element_type_of_t<T>>
    //  (T& t, const collections::collection auto& scalars) -> void
    //{
    //  // ...
    //};


    static constexpr auto
    to_euclidean = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> has_untyped_index<0> decltype(auto)
    {
      // ...
    };


    static constexpr auto
    from_euclidean = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T> and all_fixed_indices_are_euclidean<T>
      (Arg&& arg, const has_untyped_index<0> auto& v) -> indexible decltype(auto)
    {
      // ...
    };


    static constexpr auto
    wrap_angles = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> std::convertible_to<const T&> decltype(auto)
    {
      // ...
    };


    static constexpr auto
    slice = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg, const index_collection_for<Arg> auto& begin, const collections::index_collection auto& size)
      -> indexible decltype(auto)
    {
      // ...
    };


    static constexpr auto
    set_slice = [] requires writable<T>
      (T& t, indexible auto&& block, const index_collection_for<T> auto& offsets) -> void
    {
      // ...
    };


    template<triangle_type tri>
    static constexpr auto
    set_triangle = [] requires writable<T>
      (T& t, patterns_may_match_with<T> auto&& b) -> void
    {
      // ...
    };


    static constexpr auto
    diagonal_of = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> indexible auto
    {
      // ...
    };


    static constexpr auto
    broadcast = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg, const collections::index_collection auto& factors) -> indexible auto
    {
      // ...
    };


    static constexpr auto
    n_ary_operation = []<coordinates::pattern_collection Patterns, typename Operation,
        compares_with_pattern_collection<Patterns>...Args>
      requires
        std::invocable<Operation&&, element_type_of_t<Args>...> or
        std::invocable<Operation&&, std::array<std::size_t, collections::size_of_v<Patterns>>, element_type_of_t<Args>...> or
        std::invocable<Operation&&, std::vector<std::size_t>, element_type_of_t<Args>...>
      (const Patterns& patterns, Operation&& op, Args&&...args)
        -> compares_with_pattern_collection<Patterns> auto
    {
      // ...
    };


    template<std::size_t...indices, typename BinaryFunction>
    static constexpr auto
    reduce = []<typename Arg, typename BinaryFunction>
      requires std::same_as<std::remove_cvref_t<Arg>, T> and
        std::invocable<BinaryFunction, element_type_of_t<Arg>, element_type_of_t<Arg>>
      (Arg&& arg, BinaryFunction&& binary_function)
    {
      // ...
    };


    static constexpr auto
    determinant = [] requires square_shaped<T, applicability::permitted>
      (const T& t) -> std::convertible_to<element_type_of_t<T>> auto
    {
      // ...
    };


    static constexpr auto
    sum = []<typename...Args> requires patterns_may_match_with<Args...>
      (Args&&...args) -> patterns_may_match_with<Args...> decltype(auto)
    {
      // ...
    };


    static constexpr auto
    scalar_product = [](const T& t, std::convertible_to<element_type_of_t<T>> const auto& s)
      -> patterns_may_match_with<T> decltype(auto)
    {
      // ...
    };


    static constexpr auto
    scalar_quotient = [](const T& t, std::convertible_to<element_type_of_t<T>> const auto& s)
      -> patterns_may_match_with<T> decltype(auto)
    {
      // ...
    };


    static constexpr auto
    contract = []
      (const T& a, const dimension_size_of_index_is<0, index_dimension_of<T, 1>, &stdex::is_eq, applicability::permitted> auto& b)
      -> dimension_size_of_index_is<0, index_dimension_of_v<T, 0>, &stdex::is_eq, applicability::permitted> auto
    {
      // ...
    };


    template<bool on_the_right>
    static constexpr auto
    contract_in_place = [](T& t, patterns_may_match_with<T> auto&& b) -> void
    {
      // ...
    };


    template<triangle_type tri>
    static constexpr auto
    cholesky_factor = [](const T& t) -> triangular_matrix<tri> auto
    {
      // ...
    };


    template<HermitianAdapterType significant_triangle>
    static constexpr auto
    rank_update_hermitian = []<typename A, typename U>
      requires std::same_as<std::remove_cvref_t<A>, T> and
        dimension_size_of_index_is<U, 0, index_dimension_of_v<A, 0>, &stdex::is_eq, applicability::permitted> and
        dimension_size_of_index_is<U, 0, index_dimension_of_v<A, 1>, &stdex::is_eq, applicability::permitted> and
        std::convertible_to<element_type_of_t<U>, const element_type_of_t<A>>
      (A&& a, const U& u, const element_type_of_t<A>& alpha)
      -> hermitian_matrix decltype(auto)
    {
      // ...
    };


    template<triangle_type triangle> requires (triangle == triangle_type::lower) or (triangle == triangle_type::upper)
    static constexpr auto
    rank_update_triangular = []<typename A, typename U>
      requires std::same_as<std::remove_cvref_t<A>, T> and
        dimension_size_of_index_is<U, 0, index_dimension_of_v<A, 0>, &stdex::is_eq, applicability::permitted> and
        dimension_size_of_index_is<U, 0, index_dimension_of_v<A, 1>, &stdex::is_eq, applicability::permitted> and
        std::convertible_to<element_type_of_t<U>, const element_type_of_t<A>>
      (A&& a, const U& u, const element_type_of_t<decltype(a)>& alpha)
      -> triangular_matrix<triangle> decltype(auto)
    {
      // ...
    };


    template<bool must_be_unique = false, bool must_be_exact = false>
    static constexpr auto
    solve = []
      (const T& a, const dimension_size_of_index_is<0, index_dimension_of_v<A, 0>, &stdex::is_eq, applicability::permitted> auto& b)
        -> indexible auto
    {
      // ...
    };


    static constexpr auto
    LQ_decomposition = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> triangular_matrix<triangle_type::lower> auto
    {
      // ...
    };


    static constexpr auto
    QR_decomposition = []<typename Arg> requires std::same_as<std::remove_cvref_t<Arg>, T>
      (Arg&& arg) -> triangular_matrix<triangle_type::upper> auto
    {
      // ...
    };

#endif // DOXYGEN_SHOULD_SKIP_THIS
  };


}


#endif