|
| 1 | +// -*-C++-*- |
| 2 | +//@HEADER |
| 3 | +//---------------------------------------------------------------------------- |
| 4 | +// Copyright (C) 2021 NumGeom Group at Stony Brook University |
| 5 | +//---------------------------------------------------------------------------- |
| 6 | +//@HEADER |
| 7 | + |
| 8 | +/*! \page _params Control Parameters |
| 9 | +
|
| 10 | +\addindex parameters |
| 11 | +\tableofcontents |
| 12 | +
|
| 13 | +In this section, we discuss control parameters in HIFIR package. To create an |
| 14 | +instance of parameter structure, use the following |
| 15 | +
|
| 16 | +\code{.cpp} |
| 17 | + auto params = hif::get_default_params(); |
| 18 | +\endcode |
| 19 | +
|
| 20 | +or equivalently |
| 21 | +
|
| 22 | +\code{.cpp} |
| 23 | + auto params = hif::DEFAULT_PARAMS; |
| 24 | +\endcode |
| 25 | +
|
| 26 | +The instance \a params is a C++ structure whose fields are different control |
| 27 | +parameters for computing HIF preconditioners. In the following, we will address |
| 28 | +commonly-used parameters categorized in different groups. |
| 29 | +
|
| 30 | +\section _params_basic Essential Parameters |
| 31 | +
|
| 32 | +We summary several essential control parameters used in HIF. |
| 33 | +
|
| 34 | +- \ref hif::Params::tau_L and \ref hif::Params::tau_U are *drop tolerance* (or |
| 35 | + \a droptol or \f$\tau\f$in short) for L and U factors during fan-in (aka |
| 36 | + Crout-version) ILUs, respectively. The default values are 1e-4 for robustness. |
| 37 | + For most PDE-based systems (i.e., nearly (pattern) symmetric systems), then |
| 38 | + can be increased to 1e-2. In general, we recommend |
| 39 | + \f$\tau\in [10^{-4},10^{-2}]\f$. |
| 40 | +- \ref hif::Params::alpha_L and \ref hif::Params::alpha_U are *fill-in factors* |
| 41 | + for *scalability-oriented dropping* for L and U, respectively. The default |
| 42 | + values are 10 for robustness. For 3D PDE systems, \f$\alpha=3\f$ usually works |
| 43 | + very well. For 2D PDE systems, \f$\alpha=5\f$ works well. In general, we |
| 44 | + recommend \f$\alpha\in [2,20]\f$. |
| 45 | +- \ref hif::Params::kappa_d and \ref hif::Params::kappa are |
| 46 | + \a conditioning \a thresholds for D and L/U factors, respectively. Their |
| 47 | + default values are 3, which can be enlarged to 5 for efficiency for most |
| 48 | + PDE-based systems, i.e., \f$\kappa\in [3,5]\f$. |
| 49 | +- \ref hif::Params::dense_thres controls the final Schur complement size, which |
| 50 | + by default is 2000. Note that the final Schur complement may be larger than |
| 51 | + this threshold, but it plays the most important role in determing the final |
| 52 | + Schur complement sizes. The default value 2000 is for robustness, especially |
| 53 | + for highly assymetric ill-conditioned systems. In general, 500 is sufficient |
| 54 | + for most PDE-based systems. |
| 55 | +
|
| 56 | +In summary, for relatively well-posed PDE-based systems, we recommend the |
| 57 | +following settings |
| 58 | +
|
| 59 | +\code{.cpp} |
| 60 | + auto params = hif::DEFAULT_PARAMS; |
| 61 | + params.tau_L = params.tau_U = 1e-2; // droptol |
| 62 | + params.alpha_L = params.alpha_U = 3; // fill-in factor |
| 63 | + params.kappa_d = params.kappa = 5; // conditioning |
| 64 | + params.dense_thres = 500; |
| 65 | +\endcode |
| 66 | +
|
| 67 | +\section _params_system System Parameters |
| 68 | +
|
| 69 | +- \ref hif::Params::verbose controls the verbose levels during factorizations. |
| 70 | + By default, \ref hif::VERBOSE_INFO is enabled. A new level can be enabled via |
| 71 | + bit-wise add options, e.g., `params.verbose |= hif::VERBOSE_PRE` also enables |
| 72 | + verbose information for preprocessing steps. To disbale verbose printing, set |
| 73 | + the verbose level to \ref hif::VERBOSE_NONE. |
| 74 | +- \ref hif::Params::threads controls the parallel threads for computing Schur |
| 75 | + complements. The default value is 0, which inherits the setting from the |
| 76 | + system via envrionment variable `OMP_NUM_THREADS` or function |
| 77 | + `omp_get_max_threads`. |
| 78 | +
|
| 79 | +\section _params_adv Advanced Parameters |
| 80 | +
|
| 81 | +In this section, we address some advanced parameters, which may become useful. |
| 82 | +
|
| 83 | +- \ref hif::Params::rrqr_cond controls the condition number threshold for |
| 84 | + truncating QRCP for the final Schur complement. The default value is |
| 85 | + \f$\epsilon_{\textrm{mach}}^{-2/3}\f$. For some extremely |
| 86 | + ill-conditioned but not singular systems, we may need to enlarge it. |
| 87 | +- \ref hif::Params::beta is the safeguard for preventing abnormally large or |
| 88 | + small scaling factors from equilibration. The default value is 1000. |
| 89 | +- \ref hif::Params::pivot controls the dynamic pivoting strategies. By default, |
| 90 | + it is set to be \ref hif::PIVOTING_AUTO, which automatically switches to use |
| 91 | + inverse-based rook pivoting in fan-in ILUs for the coarse levels if necessary. |
| 92 | + To enforce using or disable rook pivoting, use \ref hif::PIVOTING_ON and |
| 93 | + \ref hif::PIVOTING_OFF, respectively. |
| 94 | +
|
| 95 | +\section _params_pre Preprocessing Parameters |
| 96 | +
|
| 97 | +- \ref hif::Params::reorder is for choosing different fill-reduction reordering |
| 98 | + schemes, and we use AMD (\ref hif::REORDER_AMD) by default for its robustness. |
| 99 | + Other options \ref hif::REORDER_RCM and \ref hif::REORDER_AUTO are available. |
| 100 | +- \ref hif::Params::symm_pre_lvls controls number of levels for performing |
| 101 | + symmetric preprocessing. Let \f$ T=\textrm{symm\_pre\_lvls}\f$. If \f$ T\ge 0\f$, |
| 102 | + then we always perform exactly \f$ T\f$ levels of symmetric preprocessing. |
| 103 | + If \f$ T<0\f$, then we perform **at most** \f$\vert T\vert\f$ levels of |
| 104 | + symmetric preprocessing. For the latter, in particular, if the inputs of all |
| 105 | + levels are nearly pattern symmetric, then symmetric preprocessing is used for |
| 106 | + these levels. As far as "near pattern symmetry," the following parameter is |
| 107 | + used to control it. By default, \f$ T=-2\f$. |
| 108 | +- \ref hif::Params::nzp_thres controls the nonzero pattern (nzp) symmetry |
| 109 | + threshold, which is then used to determine near pattern symmetry. By default, |
| 110 | + it is 0.65, i.e., if 65% entries are pattern symmetric, then a symmetric |
| 111 | + preprocessing is used. Note that this parameter is only used if symm_pre_lvls |
| 112 | + is negative. |
| 113 | +
|
| 114 | +*/ |
0 commit comments