StrumpackOptions.hpp

Go to the documentation of this file.

/*
 * STRUMPACK -- STRUctured Matrices PACKage, Copyright (c) 2014, The
 * Regents of the University of California, through Lawrence Berkeley
 * National Laboratory (subject to receipt of any required approvals
 * from the U.S. Dept. of Energy).  All rights reserved.
 *
 * If you have questions about your rights to use or distribute this
 * software, please contact Berkeley Lab's Technology Transfer
 * Department at TTD@lbl.gov.
 *
 * NOTICE. This software is owned by the U.S. Department of Energy. As
 * such, the U.S. Government has been granted for itself and others
 * acting on its behalf a paid-up, nonexclusive, irrevocable,
 * worldwide license in the Software to reproduce, prepare derivative
 * works, and perform publicly and display publicly.  Beginning five
 * (5) years after the date permission to assert copyright is obtained
 * from the U.S. Department of Energy, and subject to any subsequent
 * five (5) year renewals, the U.S. Government is granted for itself
 * and others acting on its behalf a paid-up, nonexclusive,
 * irrevocable, worldwide license in the Software to reproduce,
 * prepare derivative works, distribute copies to the public, perform
 * publicly and display publicly, and to permit others to do so.
 *
 * Developers: Pieter Ghysels, Francois-Henry Rouet, Xiaoye S. Li.
 *             (Lawrence Berkeley National Lab, Computational Research
 *             Division).
 */
#ifndef SPOPTIONS_HPP
#define SPOPTIONS_HPP
 
#include <limits>
 
#include "dense/BLASLAPACKWrapper.hpp"
#include "HSS/HSSOptions.hpp"
#include "BLR/BLROptions.hpp"
#include "HODLR/HODLROptions.hpp"
// #include "sparse/ordering/spectral/NDOptions.hpp"
 
namespace strumpack {
 
  enum class ProportionalMapping {
    FLOPS,          
    FACTOR_MEMORY,  
    PEAK_MEMORY     
  };
 
  enum class ReorderingStrategy {
    NATURAL,    
    METIS,      
    PARMETIS,   
    SCOTCH,     
    PTSCOTCH,   
    RCM,        
    GEOMETRIC,  
    AMD,        
    MMD,        
    AND,        
    MLF,        
    SPECTRAL    
  };
 
  std::string get_name(ReorderingStrategy method);
 
  bool is_parallel(ReorderingStrategy method);
 
  enum class CompressionType {
    NONE,      
    HSS,       
    BLR,       
    HODLR,     
    BLR_HODLR, 
    ZFP_BLR_HODLR, 
    LOSSLESS,  
    LOSSY      
  };
 
  std::string get_name(CompressionType comp);
 
 
  enum class MatchingJob {
    NONE,                         
    MAX_CARDINALITY,              
    MAX_SMALLEST_DIAGONAL,        
    MAX_SMALLEST_DIAGONAL_2,      
    MAX_DIAGONAL_SUM,             
    MAX_DIAGONAL_PRODUCT_SCALING, 
    COMBBLAS                      
  };
 
  enum class EquilibrationType : char
    { NONE='N', ROW='R', COLUMN='C', BOTH='B' };
 
 
  MatchingJob get_matching(int job);
 
  int get_matching(MatchingJob job);
 
  std::string get_description(MatchingJob job);
 
 
  enum class GramSchmidtType {
    CLASSICAL,   
    MODIFIED     
  };
 
  enum class KrylovSolver {
    AUTO,           
    DIRECT,         
    REFINE,         
    PREC_GMRES,     
    GMRES,          
    PREC_BICGSTAB,  
    BICGSTAB        
  };
 
  template<typename real_t> inline real_t default_rel_tol()
  { return real_t(1.e-6); }
  template<typename real_t> inline real_t default_abs_tol()
  { return real_t(1.e-10); }
  template<> inline float default_rel_tol() { return 1.e-4; }
  template<> inline float default_abs_tol() { return 1.e-6; }
 
  inline int default_gpu_streams() { return 4; }
 
  template<typename scalar_t> class SPOptions {
  public:
    using real_t = typename RealType<scalar_t>::value_type;
 
    SPOptions() { hss_opts_.set_verbose(false); }
 
    SPOptions(int argc, const char* const argv[]) : argc_(argc), argv_(argv) {
      hss_opts_.set_verbose(false);
      blr_opts_.set_verbose(false);
      hodlr_opts_.set_verbose(false);
      // nd_opts_.set_verbose(false);
    }
 
    void set_verbose(bool verbose) { verbose_ = verbose; }
 
    void set_maxit(int maxit) { assert(maxit >= 1); maxit_ = maxit; }
 
    void set_rel_tol(real_t rtol) {
      assert(rtol <= real_t(1.) && rtol >= real_t(0.));
      rel_tol_ = rtol;
    }
 
    void set_abs_tol(real_t atol) {
      assert(atol >= real_t(0.));
      abs_tol_ = atol;
    }
 
    void set_Krylov_solver(KrylovSolver s) { Krylov_solver_ = s; }
 
    void set_gmres_restart(int m) { assert(m >= 1); gmres_restart_ = m; }
 
    void set_GramSchmidt_type(GramSchmidtType t) { Gram_Schmidt_type_ = t; }
 
    void set_reordering_method(ReorderingStrategy m) { reordering_method_ = m; }
 
    void set_nd_param(int nd_param)
    { assert(nd_param>=0); nd_param_ = nd_param; }
 
    void set_nd_planar_levels(int nd_planar_levels)
    { assert(nd_planar_levels>=0); nd_planar_levels_ = nd_planar_levels; }
 
    void set_dimensions(int nx, int ny=1, int nz=1) {
      assert(nx>=1 && ny>=1 && nz>=1);
      nx_ = nx; ny_ = ny; nz_ = nz;
    }
 
    void set_nx(int nx) {assert(nx>=1); nx_ = nx; }
 
    void set_ny(int ny) {assert(ny>=1); ny_ = ny; }
 
    void set_nz(int nz) { assert(nz>=1); nz_ = nz; }
 
    void set_components(int components)
    { assert(components>=1); components_ = components; }
 
    void set_separator_width(int width)
    { assert(width>=1); separator_width_ = width; }
 
    void enable_METIS_NodeNDP() { use_METIS_NodeNDP_ = true; }
 
    void disable_METIS_NodeNDP() { use_METIS_NodeNDP_ = false; }
 
 
    void enable_METIS_NodeND() { use_METIS_NodeNDP_ = false; }
 
    void disable_METIS_NodeND() { use_METIS_NodeNDP_ = true; }
 
    void enable_MUMPS_SYMQAMD() { use_MUMPS_SYMQAMD_ = true; }
 
    void disable_MUMPS_SYMQAMD() { use_MUMPS_SYMQAMD_ = false; }
 
    void enable_agg_amalg() { use_agg_amalg_ = true; }
 
    void disable_agg_amalg() { use_agg_amalg_ = false; }
 
    void set_matching(MatchingJob job) { matching_job_ = job; }
 
    void enable_assembly_tree_log() { log_assembly_tree_ = true; }
 
    void disable_assembly_tree_log() { log_assembly_tree_ = false; }
 
    void set_compression(CompressionType c) { comp_ = c; }
 
    void set_compression_rel_tol(real_t rtol) {
      hss_opts_.set_rel_tol(rtol);
      blr_opts_.set_rel_tol(rtol);
      hodlr_opts_.set_rel_tol(rtol);
    }
 
    void set_compression_abs_tol(real_t atol) {
      hss_opts_.set_abs_tol(atol);
      blr_opts_.set_abs_tol(atol);
      hodlr_opts_.set_abs_tol(atol);
    }
 
    void set_compression_min_sep_size(int s) {
      assert(s >= 0);
      hss_min_sep_size_ = s;
      blr_min_sep_size_ = s;
      hodlr_min_sep_size_ = s;
      lossy_min_sep_size_ = s;
    }
    void set_hss_min_sep_size(int s) {
      assert(s >= 0);
      hss_min_sep_size_ = s;
    }
    void set_hodlr_min_sep_size(int s) {
      assert(s >= 0);
      hodlr_min_sep_size_ = s;
    }
    void set_blr_min_sep_size(int s) {
      assert(s >= 0);
      blr_min_sep_size_ = s;
    }
    void set_lossy_min_sep_size(int s) {
      assert(s >= 0);
      lossy_min_sep_size_ = s;
    }
 
    void set_compression_min_front_size(int s) {
      assert(s >= 0);
      hss_min_front_size_ = s;
      blr_min_front_size_ = s;
      hodlr_min_front_size_ = s;
      lossy_min_front_size_ = s;
    }
    void set_hss_min_front_size(int s) {
      assert(s >= 0);
      hss_min_front_size_ = s;
    }
    void set_hodlr_min_front_size(int s) {
      assert(s >= 0);
      hodlr_min_front_size_ = s;
    }
    void set_blr_min_front_size(int s) {
      assert(s >= 0);
      blr_min_front_size_ = s;
    }
    void set_lossy_min_front_size(int s) {
      assert(s >= 0);
      lossy_min_front_size_ = s;
    }
 
    void set_compression_leaf_size(int s) {
      hss_opts_.set_leaf_size(s);
      blr_opts_.set_leaf_size(s);
      hodlr_opts_.set_leaf_size(s);
    }
 
    void set_separator_ordering_level(int l)
    { assert(l >= 0); sep_order_level_ = l; }
 
#ifndef DOXYGEN_SHOULD_SKIP_THIS
    void enable_indirect_sampling() { indirect_sampling_ = true; }
    void disable_indirect_sampling() { indirect_sampling_ = false; }
#endif // DOXYGEN_SHOULD_SKIP_THIS
 
    void enable_replace_tiny_pivots() { replace_tiny_pivots_ = true; }
 
    void disable_replace_tiny_pivots() { replace_tiny_pivots_ = false; }
 
    void set_pivot_threshold(real_t thresh) { pivot_ = thresh; }
 
    void set_write_root_front(bool b) { write_root_front_ = b; }
 
    void enable_gpu() { use_gpu_ = true; }
 
    void disable_gpu() { use_gpu_ = false; }
 
    void set_gpu_streams(int s) { gpu_streams_ = s; }
 
    void enable_openmp_tree() { use_openmp_tree_ = true; }
 
    void disable_openmp_tree() { use_openmp_tree_ = false; }
 
    void set_lossy_precision(int p) { lossy_precision_ = p; }
 
    void set_print_compressed_front_stats(bool b) { print_comp_front_stats_ = b; }
 
    void set_proportional_mapping(ProportionalMapping pmap) { prop_map_ = pmap; }
 
    bool verbose() const { return verbose_; }
 
    int maxit() const { return maxit_; }
 
    real_t rel_tol() const { return rel_tol_; }
 
    real_t abs_tol() const { return abs_tol_; }
 
    KrylovSolver Krylov_solver() const { return Krylov_solver_; }
 
    int gmres_restart() const { return gmres_restart_; }
 
    GramSchmidtType GramSchmidt_type() const { return Gram_Schmidt_type_; }
 
    ReorderingStrategy reordering_method() const { return reordering_method_; }
 
    int nd_param() const { return nd_param_; }
 
    int nd_planar_levels() const { return nd_planar_levels_; }
 
    int nx() const { return nx_; }
 
    int ny() const { return ny_; }
 
    int nz() const { return nz_; }
 
    int components() const { return components_; }
 
    int separator_width() const { return separator_width_; }
 
    bool use_METIS_NodeNDP() const { return use_METIS_NodeNDP_; }
 
    bool use_METIS_NodeND() const { return !use_METIS_NodeNDP_; }
 
    bool use_MUMPS_SYMQAMD() const { return use_MUMPS_SYMQAMD_; }
 
    bool use_agg_amalg() const { return use_agg_amalg_; }
 
    MatchingJob matching() const { return matching_job_; }
 
    bool log_assembly_tree() const { return log_assembly_tree_; }
 
    CompressionType compression() const { return comp_; }
 
 
    real_t compression_rel_tol(int l=0) const {
      switch (comp_) {
      case CompressionType::HSS:
        return hss_opts_.rel_tol();
      case CompressionType::BLR:
        return blr_opts_.rel_tol();
      case CompressionType::HODLR:
        return hodlr_opts_.rel_tol();
      case CompressionType::BLR_HODLR:
        if (l==0) return hodlr_opts_.rel_tol();
        else return blr_opts_.rel_tol();
      case CompressionType::ZFP_BLR_HODLR:
        if (l==0) return hodlr_opts_.rel_tol();
        else return blr_opts_.rel_tol();
      case CompressionType::LOSSY:
      case CompressionType::LOSSLESS:
      case CompressionType::NONE:
      default: return 0.;
      }
    }
 
    real_t compression_abs_tol(int l=0) const {
      switch (comp_) {
      case CompressionType::HSS:
        return hss_opts_.abs_tol();
      case CompressionType::BLR:
        return blr_opts_.abs_tol();
      case CompressionType::HODLR:
        return hodlr_opts_.abs_tol();
      case CompressionType::BLR_HODLR:
        if (l==0) return hodlr_opts_.abs_tol();
        else return blr_opts_.abs_tol();
      case CompressionType::ZFP_BLR_HODLR:
        if (l==0) return hodlr_opts_.abs_tol();
        else return blr_opts_.abs_tol();
      case CompressionType::LOSSY:
      case CompressionType::LOSSLESS:
      case CompressionType::NONE:
      default: return 0.;
      }
    }
 
    int compression_min_sep_size(int l=0) const {
      switch (comp_) {
      case CompressionType::HSS:
        return hss_min_sep_size_;
      case CompressionType::BLR:
        return blr_min_sep_size_;
      case CompressionType::HODLR:
        return hodlr_min_sep_size_;
      case CompressionType::BLR_HODLR:
        if (l==0) return hodlr_min_sep_size_;
        else return blr_min_sep_size_;
      case CompressionType::ZFP_BLR_HODLR:
        if (l==0) return hodlr_min_sep_size_;
        else if (l==1) return blr_min_sep_size_;
        else return lossy_min_sep_size_;
      case CompressionType::LOSSY:
      case CompressionType::LOSSLESS:
        return lossy_min_sep_size_;
      case CompressionType::NONE:
      default:
        return std::numeric_limits<int>::max();
      }
    }
    int hss_min_sep_size() const {
      return hss_min_sep_size_;
    }
    int hodlr_min_sep_size() const {
      return hodlr_min_sep_size_;
    }
    int blr_min_sep_size() const {
      return blr_min_sep_size_;
    }
    int lossy_min_sep_size() const {
      return lossy_min_sep_size_;
    }
 
    int compression_min_front_size(int l=0) const {
      switch (comp_) {
      case CompressionType::HSS:
        return hss_min_front_size_;
      case CompressionType::BLR:
        return blr_min_front_size_;
      case CompressionType::HODLR:
        return hodlr_min_front_size_;
      case CompressionType::BLR_HODLR:
        if (l==0) return hodlr_min_front_size_;
        else return blr_min_front_size_;
      case CompressionType::ZFP_BLR_HODLR:
        if (l==0) return hodlr_min_front_size_;
        else if (l==1) return blr_min_front_size_;
        else return lossy_min_front_size_;
      case CompressionType::LOSSY:
      case CompressionType::LOSSLESS:
        return lossy_min_front_size_;
      case CompressionType::NONE:
      default:
        return std::numeric_limits<int>::max();
      }
    }
    int hss_min_front_size() const {
      return hss_min_front_size_;
    }
    int hodlr_min_front_size() const {
      return hodlr_min_front_size_;
    }
    int blr_min_front_size() const {
      return blr_min_front_size_;
    }
    int lossy_min_front_size() const {
      return lossy_min_front_size_;
    }
 
    int compression_leaf_size(int l=0) const {
      switch (comp_) {
      case CompressionType::HSS:
        return hss_opts_.leaf_size();
      case CompressionType::BLR:
        return blr_opts_.leaf_size();
      case CompressionType::HODLR:
        return hodlr_opts_.leaf_size();
      case CompressionType::BLR_HODLR:
        if (l==0) return hodlr_opts_.leaf_size();
        else return blr_opts_.leaf_size();
      case CompressionType::ZFP_BLR_HODLR:
        if (l==0) return hodlr_opts_.leaf_size();
        else if (l==1) return blr_opts_.leaf_size();
        else return 4;
      case CompressionType::LOSSY:
      case CompressionType::LOSSLESS:
        return 4;
      case CompressionType::NONE:
      default:
        return std::numeric_limits<int>::max();
      }
    }
 
    int separator_ordering_level() const { return sep_order_level_; }
 
    bool indirect_sampling() const { return indirect_sampling_; }
 
    bool replace_tiny_pivots() const { return replace_tiny_pivots_; }
 
    real_t pivot_threshold() const { return pivot_; }
 
    bool write_root_front() const { return write_root_front_; }
 
    bool use_gpu() const { return use_gpu_; }
 
    bool use_openmp_tree() const { return use_openmp_tree_; }
 
    int gpu_streams() const { return gpu_streams_; }
 
    int lossy_precision() const {
      return (compression() == CompressionType::LOSSLESS) ?
        -1 : lossy_precision_;
    }
 
    bool print_compressed_front_stats() const { return print_comp_front_stats_; }
 
    ProportionalMapping proportional_mapping() const { return prop_map_; }
 
    const HSS::HSSOptions<scalar_t>& HSS_options() const { return hss_opts_; }
 
    HSS::HSSOptions<scalar_t>& HSS_options() { return hss_opts_; }
 
    const BLR::BLROptions<scalar_t>& BLR_options() const { return blr_opts_; }
 
    BLR::BLROptions<scalar_t>& BLR_options() { return blr_opts_; }
 
    const HODLR::HODLROptions<scalar_t>& HODLR_options() const { return hodlr_opts_; }
 
    HODLR::HODLROptions<scalar_t>& HODLR_options() { return hodlr_opts_; }
 
    // /**
    //  * Get a (const) reference to an object holding various options
    //  * pertaining to the spectral nested dissection code.
    //  */
    // const ordering::NDOptions& ND_options() const { return nd_opts_; }
 
    // /**
    //  * Get a reference to an object holding various options pertaining
    //  * to the spectral nested dissection code.
    //  */
    // ordering::NDOptions& ND_options() { return nd_opts_; }
 
    void set_from_command_line() { set_from_command_line(argc_, argv_); }
 
    void set_from_command_line(int argc, const char* const* cargv);
 
    void describe_options() const;
 
  private:
    bool verbose_ = true;
    int maxit_ = 5000;
    real_t rel_tol_ = default_rel_tol<real_t>();
    real_t abs_tol_ = default_abs_tol<real_t>();
    KrylovSolver Krylov_solver_ = KrylovSolver::AUTO;
    int gmres_restart_ = 30;
    GramSchmidtType Gram_Schmidt_type_ = GramSchmidtType::MODIFIED;
    ReorderingStrategy reordering_method_ = ReorderingStrategy::METIS;
    int nd_planar_levels_ = 0;
    int nd_param_ = 8;
    int nx_ = 1;
    int ny_ = 1;
    int nz_ = 1;
    int components_ = 1;
    int separator_width_ = 1;
    bool use_METIS_NodeNDP_ = false;
    bool use_MUMPS_SYMQAMD_ = false;
    bool use_agg_amalg_ = false;
    MatchingJob matching_job_ = MatchingJob::MAX_DIAGONAL_PRODUCT_SCALING;
    bool log_assembly_tree_ = false;
    bool replace_tiny_pivots_ = false;
    real_t pivot_ = std::sqrt(blas::lamch<real_t>('E'));
    bool write_root_front_ = false;
    bool print_comp_front_stats_ = false;
    ProportionalMapping prop_map_ = ProportionalMapping::FLOPS;
    bool use_openmp_tree_ = true;
 
#if defined(STRUMPACK_USE_CUDA) || defined(STRUMPACK_USE_HIP) || defined(STRUMPACK_USE_SYCL)
    bool use_gpu_ = true;
#else
    bool use_gpu_ = false;
#endif
    int gpu_streams_ = default_gpu_streams();
 
    CompressionType comp_ = CompressionType::NONE;
 
    int hss_min_front_size_ = 100000;
    int hss_min_sep_size_ = 1000;
    int sep_order_level_ = 1;
    bool indirect_sampling_ = false;
    HSS::HSSOptions<scalar_t> hss_opts_;
 
    BLR::BLROptions<scalar_t> blr_opts_;
    int blr_min_front_size_ = 100000;
    int blr_min_sep_size_ = 512;
 
    HODLR::HODLROptions<scalar_t> hodlr_opts_;
    int hodlr_min_front_size_ = 100000;
    int hodlr_min_sep_size_ = 5000;
 
    int lossy_min_front_size_ = 100000;
    int lossy_min_sep_size_ = 8;
    int lossy_precision_ = 16;
 
    // ordering::NDOptions nd_opts_;
 
    int argc_ = 0;
    const char* const* argv_ = nullptr;
  };
 
} // end namespace strumpack
 
#endif // SPOPTIONS_HPP