yk_var_api.hpp

Go to the documentation of this file.

/*****************************************************************************
 
YASK: Yet Another Stencil Kit
Copyright (c) 2014-2024, Intel Corporation
 
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to
deal in the Software without restriction, including without limitation the
rights to use, copy, modify, merge, publish, distribute, sublicense, and/or
sell copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
 
* The above copyright notice and this permission notice shall be included in
  all copies or substantial portions of the Software.
 
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 OR COPYRIGHT HOLDERS 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.
 
*****************************************************************************/
 
 
// This file uses Doxygen markup for API documentation-generation.
// See https://www.doxygen.nl/manual/index.html.
#pragma once
 
#include "yask_kernel_api.hpp"
 
namespace yask {
 
 
    class yk_var {
    public:
        virtual ~yk_var() {}
 
 
        virtual const std::string& get_name() const =0;
 
 
        virtual int get_num_dims() const =0;
 
 
        virtual string_vec
        get_dim_names() const =0;
 
 
        virtual int get_num_domain_dims() const =0;
 
 
        virtual bool
        is_dim_used(const std::string& dim) const =0;
 
 
        virtual bool is_fixed_size() const =0;
 
 
        virtual idx_t
        get_first_local_index(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_first_local_index_vec() const =0;
 
 
        virtual idx_t
        get_last_local_index(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_last_local_index_vec() const =0;
 
 
        virtual idx_t
        get_alloc_size(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_alloc_size_vec() const =0;
 
 
        virtual idx_t
        get_first_valid_step_index() const =0;
 
 
        virtual idx_t
        get_last_valid_step_index() const =0;
        
 
        virtual idx_t
        get_rank_domain_size(const std::string& dim) const =0;
 
 
        virtual idx_t_vec
        get_rank_domain_size_vec() const =0;
 
 
        virtual idx_t
        get_first_rank_domain_index(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_first_rank_domain_index_vec() const =0;
 
 
        virtual idx_t
        get_last_rank_domain_index(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_last_rank_domain_index_vec() const =0;
 
 
        virtual idx_t
        get_left_halo_size(const std::string& dim ) const =0;
 
 
        virtual idx_t
        get_right_halo_size(const std::string& dim ) const =0;
 
 
        virtual idx_t
        get_first_rank_halo_index(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_first_rank_halo_index_vec() const =0;
        
 
        virtual idx_t
        get_last_rank_halo_index(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_last_rank_halo_index_vec() const =0;
 
 
        virtual idx_t
        get_left_pad_size(const std::string& dim ) const =0;
 
 
        virtual idx_t
        get_right_pad_size(const std::string& dim ) const =0;
 
 
        virtual idx_t
        get_left_extra_pad_size(const std::string& dim ) const =0;
 
 
        virtual idx_t
        get_right_extra_pad_size(const std::string& dim ) const =0;
 
 
        virtual idx_t
        get_first_misc_index(const std::string& dim ) const =0;
 
 
        virtual idx_t
        get_last_misc_index(const std::string& dim ) const =0;
 
 
        virtual bool
        are_indices_local(const idx_t_vec& indices ) const =0;
 
        #ifndef SWIG
 
        virtual bool
        are_indices_local(const idx_t_init_list& indices ) const =0;
        #endif
 
 
        virtual double
        get_element(const idx_t_vec& indices ) const =0;
 
        #ifndef SWIG
 
        virtual double
        get_element(const idx_t_init_list& indices ) const =0;
        #endif
 
 
        virtual idx_t
        set_element(double val ,
                    const idx_t_vec& indices,
                    bool strict_indices = true ) =0;
 
        #ifndef SWIG
 
        virtual idx_t
        set_element(double val ,
                    const idx_t_init_list& indices,
                    bool strict_indices = true ) =0;
 
 
        virtual idx_t
        get_elements_in_slice(float* buffer_ptr,
                              size_t buffer_size,
                              const idx_t_vec& first_indices,
                              const idx_t_vec& last_indices ) const =0;
 
 
        virtual idx_t
        get_elements_in_slice(double* buffer_ptr,
                              size_t buffer_size,
                              const idx_t_vec& first_indices,
                              const idx_t_vec& last_indices ) const =0;
        #endif
 
 
        virtual idx_t
        add_to_element(double val ,
                       const idx_t_vec& indices,
                       bool strict_indices = true ) =0;
 
        #ifndef SWIG
 
        virtual idx_t
        add_to_element(double val ,
                       const idx_t_init_list& indices,
                       bool strict_indices = true ) =0;
        #endif
 
 
        virtual void
        set_all_elements_same(double val  ) =0;
 
 
        virtual idx_t
        set_elements_in_slice_same(double val ,
                                   const idx_t_vec& first_indices,
                                   const idx_t_vec& last_indices,
                                   bool strict_indices = true ) =0;
 
        #ifndef SWIG
 
        virtual idx_t
        set_elements_in_slice(const float* buffer_ptr,
                              size_t buffer_size,
                              const idx_t_vec& first_indices,
                              const idx_t_vec& last_indices ) =0;
 
 
 
        virtual idx_t
        set_elements_in_slice(const double* buffer_ptr,
                              size_t buffer_size,
                              const idx_t_vec& first_indices,
                              const idx_t_vec& last_indices ) =0;
        #endif
 
        #ifdef COPY_SLICE_IMPLEMENTED
 
        virtual idx_t
        set_elements_in_slice(const yk_var_ptr source,
                              const idx_t_vec& first_source_indices,
                              const idx_t_vec& first_target_indices,
                              const idx_t_vec& last_target_indices ) =0;
        #endif
 
        static constexpr int yk_sum_reduction = 0x01;
        
        static constexpr int yk_sum_squares_reduction = 0x02;
        
        static constexpr int yk_product_reduction = 0x04;
        
        static constexpr int yk_max_reduction = 0x08;
        
        static constexpr int yk_min_reduction = 0x10;
        
 
        class yk_reduction_result {
        public:
 
 
            virtual int
            get_reduction_mask() const =0;
 
 
            virtual idx_t
            get_num_elements_reduced() const =0;
 
 
            virtual double
            get_sum() const =0;
 
 
            virtual double
            get_sum_squares() const =0;
 
 
            virtual double
            get_product() const =0;
 
 
            virtual double
            get_max() const =0;
 
 
            virtual double
            get_min() const =0;
        };
 
        typedef std::shared_ptr<yk_reduction_result> yk_reduction_result_ptr;
        
 
        virtual yk_reduction_result_ptr
        reduce_elements_in_slice(int reduction_mask ,
                                 const idx_t_vec& first_indices,
                                 const idx_t_vec& last_indices,
                                 bool strict_indices = true ) =0;
        
 
        virtual std::string
        format_indices(const idx_t_vec& indices ) const =0;
 
        #ifndef SWIG
 
        virtual std::string
        format_indices(const idx_t_init_list& indices ) const =0;
        #endif
 
        /* Advanced APIs for yk_var found below are not needed for most applications. */
 
 
        virtual int
        get_halo_exchange_l1_norm() const =0;
        
 
        virtual void
        set_halo_exchange_l1_norm(int norm) =0;
        
 
        virtual bool
        is_dynamic_step_alloc() const =0;
 
 
        virtual bool
        set_numa_preferred(int numa_node) =0;
 
 
        virtual int
        get_numa_preferred() const =0;
 
 
        virtual void
        set_left_min_pad_size(const std::string& dim,
                              idx_t size ) =0;
 
 
        virtual void
        set_right_min_pad_size(const std::string& dim,
                               idx_t size ) =0;
 
 
        virtual void
        set_min_pad_size(const std::string& dim,
                         idx_t size ) =0;
 
 
        virtual void
        set_left_halo_size(const std::string& dim,
                           idx_t size ) =0;
 
 
        virtual void
        set_right_halo_size(const std::string& dim,
                            idx_t size ) =0;
 
 
        virtual void
        set_halo_size(const std::string& dim,
                      idx_t size ) =0;
 
 
 
        virtual void
        set_alloc_size(const std::string& dim,
                       idx_t size  ) =0;
 
 
        virtual void
        set_first_misc_index(const std::string& dim,
                             idx_t idx  ) =0;
 
 
        virtual bool
        is_storage_allocated() const =0;
 
 
        virtual idx_t
        get_num_storage_bytes() const =0;
 
 
        virtual idx_t
        get_num_storage_elements() const =0;
 
 
        virtual void
        alloc_storage() =0;
 
 
        virtual void
        release_storage() =0;
 
 
        virtual bool
        is_storage_layout_identical(const yk_var_ptr other) const =0;
 
 
        virtual void
        fuse_vars(yk_var_ptr source) =0;
 
 
        virtual void* get_raw_storage_buffer() =0;
 
 
 
        YASK_DEPRECATED
        virtual idx_t
        get_elements_in_slice(void* buffer_ptr,
                              const idx_t_vec& first_indices,
                              const idx_t_vec& last_indices ) const =0;
 
 
        YASK_DEPRECATED
        virtual idx_t
        set_elements_in_slice(const void* buffer_ptr,
                              const idx_t_vec& first_indices,
                              const idx_t_vec& last_indices ) =0;
 
        YASK_DEPRECATED
        virtual idx_t
        get_first_rank_alloc_index(const std::string& dim) const {
            return get_first_local_index(dim);
        }
 
        YASK_DEPRECATED
        virtual idx_t
        get_last_rank_alloc_index(const std::string& dim) const {
            return get_last_local_index(dim);
        }
 
    }; // yk_var.
 
    YASK_DEPRECATED
    typedef yk_var yk_grid;
    
} // namespace yask.