PaStiX Handbook  6.2.1
pastix_lowrank.h
Go to the documentation of this file.
1 /**
2  * @file pastix_lowrank.h
3  *
4  * PaStiX kernel header.
5  *
6  * @copyright 2011-2021 Bordeaux INP, CNRS (LaBRI UMR 5800), Inria,
7  * Univ. Bordeaux. All rights reserved.
8  *
9  * @version 6.2.0
10  * @author Mathieu Faverge
11  * @author Pierre Ramet
12  * @author Xavier Lacoste
13  * @author Esragul Korkmaz
14  * @author Gregoire Pichon
15  * @date 2021-03-30
16  *
17  */
18 #ifndef _pastix_lowrank_h_
19 #define _pastix_lowrank_h_
20 
21 /**
22  *
23  * @addtogroup kernel_lr_null
24  * @{
25  * This module contains all the internal functions for low-rank kernels
26  */
27 
28 /**
29  * @brief List of short names for the compression kernels
30  */
31 extern const char *compmeth_shnames[PastixCompressMethodNbr];
32 
33 /**
34  * @brief List of long names for the compression kernels
35  */
36 extern const char *compmeth_lgnames[PastixCompressMethodNbr];
37 
38 /**
39  * @brief Macro to specify if the U part of a low-rank matrix is orthogonal or not (Used in LRMM functions).
40  */
41 #define PASTIX_LRM3_ORTHOU (1 << 0)
42 /**
43  * @brief Macro to specify if the U part of a low-rank matrix has been allocated and need to be freed or not (Used in LRMM functions).
44  */
45 #define PASTIX_LRM3_ALLOCU (1 << 1)
46 /**
47  * @brief Macro to specify if the V part of a low-rank matrix has been allocated and need to be freed or not (Used in LRMM functions).
48  */
49 #define PASTIX_LRM3_ALLOCV (1 << 2)
50 /**
51  * @brief Macro to specify if the the operator on B, still needs to be applied to the V part of the low-rank matrix or not (Used in LRMM functions).
52  */
53 #define PASTIX_LRM3_TRANSB (1 << 3)
54 
55 /**
56  * @brief Define the minimal ratio for which we accept to compress a matrix into a low-rank form or not.
57  * @sa core_get_rklimit()
58  */
59 extern double pastix_lr_minratio;
60 
61 /**
62  * @brief Define the orthogonalization method.
63  */
64 extern pastix_int_t pastix_lr_ortho;
65 
66 /**
67  * @brief Compute the maximal rank accepted for a given matrix size for testings
68  * @param[in] M The number of rows of the matrix
69  * @param[in] N The number of columns of the matrix
70  * @return The maximal rank accepted for this matrix size.
71  */
72 static inline pastix_int_t
73 core_get_rklimit_max( pastix_int_t M, pastix_int_t N ) {
74  return pastix_imin( M, N );
75 }
76 
77 /**
78  * @brief Compute the maximal rank accepted for a given matrix size for Just-In-Time strategy
79  * @param[in] M The number of rows of the matrix
80  * @param[in] N The number of columns of the matrix
81  * @return The maximal rank accepted for this matrix size.
82  */
83 static inline pastix_int_t
84 core_get_rklimit_end( pastix_int_t M, pastix_int_t N ) {
85  return ( pastix_lr_minratio * pastix_imin( M, N ) ) / 4;
86 }
87 
88 /**
89  * @brief Compute the maximal rank accepted for a given matrix size for Minimal-Memory strategy
90  * @param[in] M The number of rows of the matrix
91  * @param[in] N The number of columns of the matrix
92  * @return The maximal rank accepted for this matrix size.
93  */
94 static inline pastix_int_t
95 core_get_rklimit_begin( pastix_int_t M, pastix_int_t N ) {
96  return ( pastix_lr_minratio * M * N ) / ( M + N );
97 }
98 
99 static inline pastix_int_t
100 core_get_rklimit_test( pastix_int_t M, pastix_int_t N ) {
101  return pastix_imin( M, N );
102 }
103 
104 extern pastix_int_t (*core_get_rklimit)( pastix_int_t, pastix_int_t );
105 
106 struct pastix_lr_s;
107 typedef struct pastix_lr_s pastix_lr_t;
108 
109 /**
110  * @brief The block low-rank structure to hold a matrix in low-rank form
111  */
112 typedef struct pastix_lrblock_s {
113  int rk; /**< Rank of the low-rank matrix: -1 is dense, otherwise rank-rk matrix */
114  int rkmax; /**< Leading dimension of the matrix u */
115  void *u; /**< Contains the dense matrix if rk=-1, or the u factor from u vT representation */
116  void *v; /**< Not referenced if rk=-1, otherwise, the v factor */
118 
119 /**
120  * @brief Type of the functions to compress a dense block into a low-rank form.
121  */
122 typedef pastix_fixdbl_t (*fct_ge2lr_t)( int, pastix_fixdbl_t, pastix_int_t, pastix_int_t, pastix_int_t,
123  const void *, pastix_int_t, pastix_lrblock_t * );
124 
125 /**
126  * @brief Array of pointers to the multiple arithmetic and algorithmic variants of ge2lr
127  */
129 
130 /**
131  * @brief Type of the functions to add two low-rank blocks together.
132  */
133 typedef pastix_fixdbl_t (*fct_rradd_t)( const pastix_lr_t *, pastix_trans_t, const void *,
134  pastix_int_t, pastix_int_t, const pastix_lrblock_t *,
135  pastix_int_t, pastix_int_t, pastix_lrblock_t *,
136  pastix_int_t, pastix_int_t );
137 
138 /**
139  * @brief Array of pointers to the multiple arithmetic and algorithmic variants of rradd
140  */
142 
143 /**
144  * @brief Structure to define the type of function to use for the low-rank
145  * kernels and their parameters.
146  */
147 typedef struct pastix_lr_s {
148  pastix_compress_when_t compress_when; /**< When to compress in the full solver */
149  pastix_compress_method_t compress_method; /**< Compression method */
150  pastix_int_t compress_min_width; /**< Minimum width to compress a supernode */
151  pastix_int_t compress_min_height; /**< Minimum height to compress an off-diagonal block */
152  int compress_preselect; /**< Enable/disable the compression of preselected blocks */
153  int use_reltol; /**< Enable/disable relative tolerance vs absolute one */
154  int ilu_lvl; /**< The ILU levels above which the blocks are originally compressed */
155  double tolerance; /**< Absolute compression tolerance */
156  fct_rradd_t core_rradd; /**< Recompression function */
157  fct_ge2lr_t core_ge2lr; /**< Compression function */
158 } pastix_lr_t;
159 
160 /**
161  * @brief Enum to define the type of block.
162  */
163 typedef enum memory_stats_e {
164  FR_InDiag = 0, /**< Full-rank block inside a diagonal block from the non-split partition */
165  FR_OffDiag = 1, /**< Full-rank block outside a diagonal block from the non-split partition */
166  LR_InDiag = 2, /**< Non selected Low-rank block inside a diagonal block from the non-split partition */
167  LR_InSele = 3, /**< Selected low-rank block inside a diagonal block from the non-split partition */
168  LR_OffDiag = 4, /**< Low-rank block outside a diagonal block from the non-split partition */
169  LR_DInD = 5, /**< Non-compressible diagonal block inside a diagonal block from the non-split partition */
170  MEMORY_STATS_SIZE
172 
173 /**
174  * @}
175  */
176 #endif /* _pastix_lowrank_h_ */
memory_stats_t
enum memory_stats_e memory_stats_t
Enum to define the type of block.
FR_InDiag
@ FR_InDiag
Definition: pastix_lowrank.h:164
pastix_lr_minratio
double pastix_lr_minratio
Define the minimal ratio for which we accept to compress a matrix into a low-rank form or not.
Definition: lowrank.c:24
core_get_rklimit
pastix_int_t(* core_get_rklimit)(pastix_int_t, pastix_int_t)
Compute the maximal rank accepted for a given matrix size. The pointer is set according to the low-ra...
Definition: kernels_trace.c:30
pastix_lr_s
Structure to define the type of function to use for the low-rank kernels and their parameters.
Definition: pastix_lowrank.h:147
core_get_rklimit_end
static pastix_int_t core_get_rklimit_end(pastix_int_t M, pastix_int_t N)
Compute the maximal rank accepted for a given matrix size for Just-In-Time strategy.
Definition: pastix_lowrank.h:84
pastix_lrblock_s::v
void * v
Definition: pastix_lowrank.h:116
pastix_lrblock_s::u
void * u
Definition: pastix_lowrank.h:115
pastix_lr_s::use_reltol
int use_reltol
Definition: pastix_lowrank.h:153
pastix_lr_s::ilu_lvl
int ilu_lvl
Definition: pastix_lowrank.h:154
pastix_lr_s::compress_min_width
pastix_int_t compress_min_width
Definition: pastix_lowrank.h:150
LR_OffDiag
@ LR_OffDiag
Definition: pastix_lowrank.h:168
core_get_rklimit_max
static pastix_int_t core_get_rklimit_max(pastix_int_t M, pastix_int_t N)
Compute the maximal rank accepted for a given matrix size for testings.
Definition: pastix_lowrank.h:73
compmeth_shnames
const char * compmeth_shnames[PastixCompressMethodNbr]
List of short names for the compression kernels.
Definition: lowrank.c:27
pastix_trans_t
enum pastix_trans_e pastix_trans_t
Transpostion.
pastix_lr_ortho
pastix_int_t pastix_lr_ortho
Define the orthogonalization method.
Definition: lowrank.c:25
pastix_lr_s::compress_method
pastix_compress_method_t compress_method
Definition: pastix_lowrank.h:149
pastix_lrblock_s
The block low-rank structure to hold a matrix in low-rank form.
Definition: pastix_lowrank.h:112
ge2lrMethods
const fct_ge2lr_t ge2lrMethods[PastixCompressMethodNbr][4]
Array of pointers to the multiple arithmetic and algorithmic variants of ge2lr.
Definition: lowrank.c:43
pastix_lr_s::compress_preselect
int compress_preselect
Definition: pastix_lowrank.h:152
FR_OffDiag
@ FR_OffDiag
Definition: pastix_lowrank.h:165
pastix_lrblock_t
struct pastix_lrblock_s pastix_lrblock_t
The block low-rank structure to hold a matrix in low-rank form.
pastix_lr_t
struct pastix_lr_s pastix_lr_t
Structure to define the type of function to use for the low-rank kernels and their parameters.
Definition: pastix_lowrank.h:107
pastix_lr_s::compress_min_height
pastix_int_t compress_min_height
Definition: pastix_lowrank.h:151
compmeth_lgnames
const char * compmeth_lgnames[PastixCompressMethodNbr]
List of long names for the compression kernels.
Definition: lowrank.c:35
fct_ge2lr_t
pastix_fixdbl_t(* fct_ge2lr_t)(int, pastix_fixdbl_t, pastix_int_t, pastix_int_t, pastix_int_t, const void *, pastix_int_t, pastix_lrblock_t *)
Type of the functions to compress a dense block into a low-rank form.
Definition: pastix_lowrank.h:122
pastix_lr_s::core_ge2lr
fct_ge2lr_t core_ge2lr
Definition: pastix_lowrank.h:157
PastixCompressMethodNbr
@ PastixCompressMethodNbr
Definition: api.h:379
pastix_compress_method_t
enum pastix_compress_method_e pastix_compress_method_t
Compression method available for IPARM_COMPRESS_METHOD parameter.
LR_InSele
@ LR_InSele
Definition: pastix_lowrank.h:167
memory_stats_e
memory_stats_e
Enum to define the type of block.
Definition: pastix_lowrank.h:163
pastix_lrblock_s::rk
int rk
Definition: pastix_lowrank.h:113
LR_InDiag
@ LR_InDiag
Definition: pastix_lowrank.h:166
pastix_lr_s::tolerance
double tolerance
Definition: pastix_lowrank.h:155
pastix_lr_s::core_rradd
fct_rradd_t core_rradd
Definition: pastix_lowrank.h:156
core_get_rklimit_begin
static pastix_int_t core_get_rklimit_begin(pastix_int_t M, pastix_int_t N)
Compute the maximal rank accepted for a given matrix size for Minimal-Memory strategy.
Definition: pastix_lowrank.h:95
rraddMethods
const fct_rradd_t rraddMethods[PastixCompressMethodNbr][4]
Array of pointers to the multiple arithmetic and algorithmic variants of rradd.
Definition: lowrank.c:52
LR_DInD
@ LR_DInD
Definition: pastix_lowrank.h:169
pastix_lr_s::compress_when
pastix_compress_when_t compress_when
Definition: pastix_lowrank.h:148
pastix_lrblock_s::rkmax
int rkmax
Definition: pastix_lowrank.h:114
fct_rradd_t
pastix_fixdbl_t(* fct_rradd_t)(const pastix_lr_t *, pastix_trans_t, const void *, pastix_int_t, pastix_int_t, const pastix_lrblock_t *, pastix_int_t, pastix_int_t, pastix_lrblock_t *, pastix_int_t, pastix_int_t)
Type of the functions to add two low-rank blocks together.
Definition: pastix_lowrank.h:133
pastix_compress_when_t
enum pastix_compress_when_e pastix_compress_when_t
Compression strategy available for IPARM_COMPRESS_WHEN parameter.