permutation.hpp

// SPDX-FileCopyrightText: 2017 - 2025 The Ginkgo authors
//
// SPDX-License-Identifier: BSD-3-Clause
 
#ifndef GKO_PUBLIC_CORE_MATRIX_PERMUTATION_HPP_
#define GKO_PUBLIC_CORE_MATRIX_PERMUTATION_HPP_
 
 
#include <algorithm>
#include <memory>
#include <numeric>
#include <vector>
 
#include <ginkgo/core/base/array.hpp>
#include <ginkgo/core/base/exception.hpp>
#include <ginkgo/core/base/exception_helpers.hpp>
#include <ginkgo/core/base/executor.hpp>
#include <ginkgo/core/base/lin_op.hpp>
#include <ginkgo/core/base/types.hpp>
#include <ginkgo/core/base/utils.hpp>
 
 
namespace gko {
namespace matrix {
 
 
enum class permute_mode : unsigned {
    none = 0b000u,
    rows = 0b001u,
    columns = 0b010u,
    symmetric = 0b011u,
    inverse = 0b100u,
    inverse_rows = 0b101u,
    inverse_columns = 0b110u,
    inverse_symmetric = 0b111u
};
 
 
permute_mode operator|(permute_mode a, permute_mode b);
 
 
permute_mode operator&(permute_mode a, permute_mode b);
 
 
permute_mode operator^(permute_mode a, permute_mode b);
 
 
std::ostream& operator<<(std::ostream& stream, permute_mode mode);
 
 
using mask_type = gko::uint64;
 
static constexpr mask_type row_permute = mask_type{1};
GKO_DEPRECATED("permute mask is no longer supported")
static constexpr mask_type column_permute = mask_type{1 << 2};
GKO_DEPRECATED("permute mask is no longer supported")
static constexpr mask_type inverse_permute = mask_type{1 << 3};
 
template <typename IndexType = int32>
class Permutation : public EnableLinOp<Permutation<IndexType>>,
                    public WritableToMatrixData<default_precision, IndexType> {
    friend class EnablePolymorphicObject<Permutation, LinOp>;
 
public:
    // value_type is only available to enable the usage of gko::write
    using value_type = default_precision;
    using index_type = IndexType;
 
    index_type* get_permutation() noexcept { return permutation_.get_data(); }
 
    const index_type* get_const_permutation() const noexcept
    {
        return permutation_.get_const_data();
    }
 
    GKO_DEPRECATED("use get_size()[0] instead")
    size_type get_permutation_size() const noexcept;
 
    GKO_DEPRECATED("permute mask is no longer supported")
    mask_type get_permute_mask() const;
 
    GKO_DEPRECATED("permute mask is no longer supported")
    void set_permute_mask(mask_type permute_mask);
 
    std::unique_ptr<Permutation> compute_inverse() const;
 
    std::unique_ptr<Permutation> compose(
        ptr_param<const Permutation> other) const;
 
    void write(gko::matrix_data<value_type, index_type>& data) const override;
 
    static std::unique_ptr<Permutation> create(
        std::shared_ptr<const Executor> exec, size_type size = 0);
 
    static std::unique_ptr<Permutation> create(
        std::shared_ptr<const Executor> exec,
        array<IndexType> permutation_indices);
 
    GKO_DEPRECATED(
        "dim<2> is no longer supported as a dimension parameter, use size_type "
        "instead")
    static std::unique_ptr<Permutation> create(
        std::shared_ptr<const Executor> exec, const dim<2>& size);
 
    GKO_DEPRECATED("permute mask is no longer supported")
    static std::unique_ptr<Permutation> create(
        std::shared_ptr<const Executor> exec, const dim<2>& size,
        const mask_type& enabled_permute);
 
    GKO_DEPRECATED("use the overload without dimensions")
    static std::unique_ptr<Permutation> create(
        std::shared_ptr<const Executor> exec, const dim<2>& size,
        array<IndexType> permutation_indices);
 
    GKO_DEPRECATED("permute mask is no longer supported")
    static std::unique_ptr<Permutation> create(
        std::shared_ptr<const Executor> exec, const dim<2>& size,
        array<index_type> permutation_indices,
        const mask_type& enabled_permute);
 
    GKO_DEPRECATED("use create_const without size and permute mask")
    static std::unique_ptr<const Permutation> create_const(
        std::shared_ptr<const Executor> exec, size_type size,
        gko::detail::const_array_view<IndexType>&& perm_idxs,
        mask_type enabled_permute = row_permute);
    static std::unique_ptr<const Permutation> create_const(
        std::shared_ptr<const Executor> exec,
        gko::detail::const_array_view<IndexType>&& perm_idxs);
 
protected:
    Permutation(std::shared_ptr<const Executor> exec, size_type = 0);
 
    Permutation(std::shared_ptr<const Executor> exec,
                array<IndexType> permutation_indices);
 
    void apply_impl(const LinOp* in, LinOp* out) const override;
 
    void apply_impl(const LinOp*, const LinOp* in, const LinOp*,
                    LinOp* out) const override;
 
private:
    array<index_type> permutation_;
};
 
 
}  // namespace matrix
}  // namespace gko
 
 
#endif  // GKO_PUBLIC_CORE_MATRIX_PERMUTATION_HPP_