yk_solution_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 {
 
 
    const int yask_numa_local = -1;
 
 
    const int yask_numa_interleave = -2;
 
 
    const int yask_numa_none = -9;
 
 
    const int yask_numa_offload = -11;
 
 
    class yk_solution {
    public:
        virtual ~yk_solution() {}
 
 
        virtual const std::string&
        get_name() const =0;
 
 
        virtual const std::string&
        get_description() const =0;
 
 
        virtual std::string
        get_target() const =0;
 
 
        virtual bool
        is_offloaded() const =0;
 
 
        virtual int
        get_element_bytes() const =0;
 
 
        virtual std::string
        get_step_dim_name() const =0;
 
 
        virtual int
        get_num_domain_dims() const =0;
 
 
        virtual string_vec
        get_domain_dim_names() const =0;
 
 
        virtual string_vec
        get_misc_dim_names() const =0;
 
 
        virtual void
        set_rank_domain_size(const std::string& dim,
                             idx_t size  ) =0;
 
 
        virtual void
        set_rank_domain_size_vec(const idx_t_vec& vals) = 0;
 
        #ifndef SWIG
 
        virtual void
        set_rank_domain_size_vec(const idx_t_init_list& vals) = 0;
        #endif
 
 
        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 void
        set_overall_domain_size(const std::string& dim,
                                idx_t size  ) =0;
 
 
        virtual void
        set_overall_domain_size_vec(const idx_t_vec& vals) = 0;
 
        #ifndef SWIG
 
        virtual void
        set_overall_domain_size_vec(const idx_t_init_list& vals) = 0;
        #endif
 
 
        virtual idx_t
        get_overall_domain_size(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_overall_domain_size_vec() const =0;
 
 
        virtual void
        set_block_size(const std::string& dim,
                       idx_t size ) =0;
 
 
        virtual void
        set_block_size_vec(const idx_t_vec& vals) = 0;
 
        #ifndef SWIG
 
        virtual void
        set_block_size_vec(const idx_t_init_list& vals) = 0;
        #endif
 
 
        virtual idx_t
        get_block_size(const std::string& dim) const =0;
 
 
        virtual idx_t_vec
        get_block_size_vec() const =0;
 
 
        virtual void
        set_num_ranks(const std::string& dim,
                      idx_t num  ) =0;
 
 
        virtual void
        set_num_ranks_vec(const idx_t_vec& vals) = 0;
 
        #ifndef SWIG
 
        virtual void
        set_num_ranks_vec(const idx_t_init_list& vals) = 0;
        #endif
 
 
        virtual idx_t
        get_num_ranks(const std::string& dim) const =0;
 
 
        virtual idx_t_vec
        get_num_ranks_vec() const =0;
 
 
        virtual void
        set_rank_index(const std::string& dim,
                       idx_t num  ) =0;
 
 
        virtual void
        set_rank_index_vec(const idx_t_vec& vals) = 0;
 
        #ifndef SWIG
 
        virtual void
        set_rank_index_vec(const idx_t_init_list& vals) = 0;
        #endif
 
 
        virtual idx_t
        get_rank_index(const std::string& dim ) const =0;
 
 
        virtual idx_t_vec
        get_rank_index_vec() const =0;
 
 
        virtual int
        get_num_outer_threads() const =0;
 
 
        virtual int
        get_num_inner_threads() const =0;
 
 
        virtual std::string
        apply_command_line_options(const std::string& args ) =0;
 
 
        virtual std::string
        apply_command_line_options(int argc, char* argv[]) =0;
 
 
        virtual std::string
        apply_command_line_options(const string_vec& args) =0;
 
 
        virtual std::string
        get_command_line_help() =0;
 
 
        virtual std::string
        get_command_line_values() =0;
 
 
        virtual int
        get_num_vars() const =0;
 
 
        virtual yk_var_ptr
        get_var(const std::string& name ) =0;
 
 
        virtual std::vector<yk_var_ptr>
        get_vars() =0;
 
 
        virtual void
        prepare_solution() =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 void
        run_solution(idx_t first_step_index ,
                     idx_t last_step_index  ) =0;
 
 
        virtual void
        run_solution(idx_t step_index  ) =0;
 
 
        virtual void
        copy_vars_to_device() const =0;
 
 
        virtual void
        copy_vars_from_device() const =0;
 
 
        virtual void
        exchange_halos() =0;
 
 
        virtual void
        end_solution() =0;
 
 
        virtual yk_stats_ptr
        get_stats() =0;
 
        virtual void
        clear_stats() =0;
 
 
        virtual void
        reset_auto_tuner(bool enable,
                         bool verbose = false ) =0;
 
 
        virtual bool
        is_auto_tuner_enabled() const =0;
 
 
        virtual void
        run_auto_tuner_now(bool verbose = true ) =0;
 
        /* Advanced APIs for yk_solution found below are not needed for most applications. */
 
 
        virtual void
        set_min_pad_size(const std::string& dim,
                         idx_t size ) =0;
 
 
        virtual idx_t
        get_min_pad_size(const std::string& dim) const =0;
 
 
        virtual yk_var_ptr
        new_var(const std::string& name,
                const string_vec& dims ) =0;
 
        #ifndef SWIG
 
        virtual yk_var_ptr
        new_var(const std::string& name,
                const std::initializer_list<std::string>& dims ) =0;
        #endif
 
 
        virtual yk_var_ptr
        new_fixed_size_var(const std::string& name,
                           const string_vec& dims,
                           const idx_t_vec& dim_sizes ) =0;
 
        #ifndef SWIG
 
        virtual yk_var_ptr
        new_fixed_size_var(const std::string& name,
                           const std::initializer_list<std::string>& dims,
                           const idx_t_init_list& dim_sizes ) =0;
        #endif
 
 
        virtual bool
        set_default_numa_preferred(int numa_node) =0;
 
 
        virtual int
        get_default_numa_preferred() const =0;
 
        #ifndef SWIG
        typedef std::function<void(yk_solution&)> hook_fn_t;
        
        typedef std::function<void(yk_solution& soln,
                                   idx_t first_step_index,
                                   idx_t last_step_index)> hook_fn_2idx_t;
 
 
        virtual void
        call_before_prepare_solution(hook_fn_t hook_fn) =0;
 
 
        virtual void
        call_after_prepare_solution(hook_fn_t hook_fn) =0;
 
 
        virtual void
        call_before_run_solution(hook_fn_2idx_t hook_fn) =0;
 
 
        virtual void
        call_after_run_solution(hook_fn_2idx_t hook_fn) =0;
        #endif
        
 
        virtual void
        fuse_vars(yk_solution_ptr source) =0;
 
        virtual void
        set_step_wrap(bool do_wrap) =0;
 
 
        virtual bool
        get_step_wrap() const =0;
 
        YASK_DEPRECATED
        virtual void
        set_debug_output(yask_output_ptr debug) =0;
 
        YASK_DEPRECATED
        inline int
        get_num_grids() const {
            return get_num_vars();
        }
 
        YASK_DEPRECATED
        inline yk_var_ptr
        get_grid(const std::string& name) {
            return get_var(name);
        }
                
        YASK_DEPRECATED
        inline std::vector<yk_var_ptr>
        get_grids() {
            return get_vars();
        }
 
        YASK_DEPRECATED
        inline yk_var_ptr
        new_grid(const std::string& name,
                 const string_vec& dims) {
            return new_var(name, dims);
        }
 
        #ifndef SWIG
        YASK_DEPRECATED
        inline yk_var_ptr
        new_grid(const std::string& name,
                 const std::initializer_list<std::string>& dims) {
            return new_var(name, dims);
        }
        #endif
 
        YASK_DEPRECATED
        inline yk_var_ptr
        new_fixed_size_grid(const std::string& name,
                            const string_vec& dims,
                            const idx_t_vec& dim_sizes) {
            return new_fixed_size_var(name, dims, dim_sizes);
        }
 
        #ifndef SWIG
        YASK_DEPRECATED
        inline yk_var_ptr
        new_fixed_size_grid(const std::string& name,
                            const std::initializer_list<std::string>& dims,
                            const idx_t_vec& dim_sizes) {
            return new_fixed_size_var(name, dims, dim_sizes);
        }
        #endif
        
        YASK_DEPRECATED
        inline void
        fuse_grids(yk_solution_ptr source) {
            fuse_vars(source);
        }
    };                          // yk_solution.
 
 
    class yk_stats {
    public:
        virtual ~yk_stats() {}
 
 
        virtual idx_t
        get_num_elements() =0;
 
 
        virtual idx_t
        get_num_steps_done() =0;
 
 
        virtual idx_t
        get_num_writes_done() =0;
 
 
        virtual idx_t
        get_est_fp_ops_done() =0;
 
 
        virtual double
        get_elapsed_secs() =0;
    };                          // yk_stats.
 
} // namespace yask.