8.2
general documentation
cs_blas.h
Go to the documentation of this file.
1 #ifndef __CS_BLAS_H__
2 #define __CS_BLAS_H__
3 
4 /*============================================================================
5  * BLAS (Basic Linear Algebra Subroutine) functions
6  *============================================================================*/
7 
8 /*
9  This file is part of code_saturne, a general-purpose CFD tool.
10 
11  Copyright (C) 1998-2024 EDF S.A.
12 
13  This program is free software; you can redistribute it and/or modify it under
14  the terms of the GNU General Public License as published by the Free Software
15  Foundation; either version 2 of the License, or (at your option) any later
16  version.
17 
18  This program is distributed in the hope that it will be useful, but WITHOUT
19  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
20  FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
21  details.
22 
23  You should have received a copy of the GNU General Public License along with
24  this program; if not, write to the Free Software Foundation, Inc., 51 Franklin
25  Street, Fifth Floor, Boston, MA 02110-1301, USA.
26 */
27 
28 /*----------------------------------------------------------------------------*/
29 
30 #include "cs_defs.h"
31 
32 /*----------------------------------------------------------------------------
33  * External library headers
34  *----------------------------------------------------------------------------*/
35 
36 /*----------------------------------------------------------------------------
37  * Local headers
38  *----------------------------------------------------------------------------*/
39 
40 #include "cs_base.h"
41 #include "cs_log.h"
42 
43 /*----------------------------------------------------------------------------*/
44 
46 
47 /*============================================================================
48  * Macro definitions
49  *============================================================================*/
50 
51 /*============================================================================
52  * Type definitions
53  *============================================================================*/
54 
55 /* BLAS reduction algorithm families */
56 
57 typedef enum {
58 
61 
63 
64 /*============================================================================
65  * Public function prototypes
66  *============================================================================*/
67 
68 /*----------------------------------------------------------------------------*/
69 /*
70  * \brief Print information on BLAS libraries used.
71  *
72  * \param[in] log_type log type
73  */
74 /*----------------------------------------------------------------------------*/
75 
76 void
78 
79 /*----------------------------------------------------------------------------*/
80 /*
81  * \brief Set the preferred BLAS reduction algorithm family.
82  *
83  * This may not be enforced for all algorithms, though it should at least
84  * be enforced for the most general functions such as \ref cs_dot.
85  *
86  * \param[in] mode BLAS mode to use
87  */
88 /*----------------------------------------------------------------------------*/
89 
90 void
92 
93 /*----------------------------------------------------------------------------
94  * Constant times a vector plus a vector: y <-- ax + y
95  *
96  * parameters:
97  * n <-- size of arrays x and y
98  * a <-- multiplier for x
99  * x <-- array of floating-point values
100  * y <-- array of floating-point values
101  *----------------------------------------------------------------------------*/
102 
103 void
105  double a,
106  const cs_real_t *x,
107  cs_real_t *restrict y);
108 
109 /*----------------------------------------------------------------------------
110  * Return the sum of a vector. For better precision, a superblock algorithm
111  * is used.
112  *
113  * parameters:
114  * n <-- size of array x
115  * x <-- array of floating-point values
116  *
117  * returns:
118  * the resulting sum
119  *----------------------------------------------------------------------------*/
120 
121 double
122 cs_sum(cs_lnum_t n,
123  const cs_real_t *x);
124 
125 /*----------------------------------------------------------------------------
126  * Return the weighted sum of a vector. For better precision, a superblock
127  * algorithm is used.
128  *
129  * \param[in] n size of array x
130  * \param[in] w array of floating-point weights
131  * \param[in] x array of floating-point values
132  *
133  * \return the resulting weighted sum
134  *----------------------------------------------------------------------------*/
135 
136 double
138  const cs_real_t *w,
139  const cs_real_t *x);
140 
141 /*----------------------------------------------------------------------------
142  * Return the dot product of 2 vectors: x.y
143  *
144  * parameters:
145  * n <-- size of arrays x and y
146  * x <-- array of floating-point values
147  * y <-- array of floating-point values
148  *
149  * returns:
150  * dot product
151  *----------------------------------------------------------------------------*/
152 
153 double
154 cs_dot(cs_lnum_t n,
155  const cs_real_t *x,
156  const cs_real_t *y);
157 
158 /*----------------------------------------------------------------------------
159  * Return dot products of a vector with itself: x.x
160  *
161  * parameters:
162  * n <-- size of arrays x
163  * x <-- array of floating-point values
164  *
165  * returns:
166  * dot product
167  *----------------------------------------------------------------------------*/
168 
169 double
171  const cs_real_t *x);
172 
173 /*----------------------------------------------------------------------------
174  * Return weighted dot products of a vector with itself: x.x
175  *
176  * For better precision, a superblock algorithm is used.
177  *
178  * parameters:
179  * n <-- size of arrays x
180  * w <-- array of weights
181  * x <-- array of floating-point values
182  *
183  * returns:
184  * dot product
185  *----------------------------------------------------------------------------*/
186 
187 double
189  const cs_real_t *w,
190  const cs_real_t *x);
191 
192 /*----------------------------------------------------------------------------
193  * Return the double dot product of 2 vectors: x.x, and x.y
194  *
195  * The products could be computed separately, but computing them
196  * simultaneously adds more optimization opportunities and possibly better
197  * cache behavior.
198  *
199  * parameters:
200  * n <-- size of arrays x and y
201  * x <-- array of floating-point values
202  * y <-- array of floating-point values
203  * xx --> x.x dot product
204  * xy --> x.y dot product
205  *----------------------------------------------------------------------------*/
206 
207 void
209  const cs_real_t *restrict x,
210  const cs_real_t *restrict y,
211  double *xx,
212  double *xy);
213 
214 /*----------------------------------------------------------------------------
215  * Return the double dot product of 3 vectors: x.y, and y.z
216  *
217  * The products could be computed separately, but computing them
218  * simultaneously adds more optimization opportunities and possibly better
219  * cache behavior.
220  *
221  * parameters:
222  * n <-- size of arrays x and y
223  * x <-- array of floating-point values
224  * y <-- array of floating-point values
225  * z <-- array of floating-point values
226  * xy --> x.y dot product
227  * yz --> x.z dot product
228  *----------------------------------------------------------------------------*/
229 
230 void
232  const cs_real_t *restrict x,
233  const cs_real_t *restrict y,
234  const cs_real_t *restrict z,
235  double *xx,
236  double *xy);
237 
238 /*----------------------------------------------------------------------------
239  * Return 3 dot products of 3 vectors: x.x, x.y, and y.z
240  *
241  * The products could be computed separately, but computing them
242  * simultaneously adds more optimization opportunities and possibly better
243  * cache behavior.
244  *
245  * parameters:
246  * n <-- size of arrays x and y
247  * x <-- array of floating-point values
248  * y <-- array of floating-point values
249  * z <-- array of floating-point values
250  * xx --> x.y dot product
251  * xy --> x.y dot product
252  * yz --> y.z dot product
253  *----------------------------------------------------------------------------*/
254 
255 void
257  const cs_real_t *restrict x,
258  const cs_real_t *restrict y,
259  const cs_real_t *restrict z,
260  double *xx,
261  double *xy,
262  double *yz);
263 
264 /*----------------------------------------------------------------------------
265  * Return 5 dot products of 3 vectors: x.x, y.y, x.y, x.z, and y.z
266  *
267  * The products could be computed separately, but computing them
268  * simultaneously adds more optimization opportunities and possibly better
269  * cache behavior.
270  *
271  * parameters:
272  * n <-- size of arrays x and y
273  * x <-- array of floating-point values
274  * y <-- array of floating-point values
275  * z <-- array of floating-point values
276  * xx --> x.y dot product
277  * yy --> y.y dot product
278  * xy --> x.y dot product
279  * xz --> x.z dot product
280  * yz --> y.z dot product
281  *----------------------------------------------------------------------------*/
282 
283 void
285  const cs_real_t *restrict x,
286  const cs_real_t *restrict y,
287  const cs_real_t *restrict z,
288  double *xx,
289  double *yy,
290  double *xy,
291  double *xz,
292  double *yz);
293 
294 /*----------------------------------------------------------------------------
295  * Return the global dot product of 2 vectors: x.y
296  *
297  * In parallel mode, the local results are summed on the default
298  * global communicator.
299  *
300  * parameters:
301  * n <-- size of arrays x and y
302  * x <-- array of floating-point values
303  * y <-- array of floating-point values
304  *
305  * returns:
306  * dot product
307  *----------------------------------------------------------------------------*/
308 
309 double
311  const cs_real_t *x,
312  const cs_real_t *y);
313 
314 /*----------------------------------------------------------------------------
315  * Return the global residual of 2 intensive vectors:
316  * 1/sum(vol) . sum(vol.x.y)
317  *
318  * parameters:
319  * n <-- size of arrays x and y
320  * vol <-- array of floating-point values
321  * x <-- array of floating-point values
322  * y <-- array of floating-point values
323  *
324  * returns:
325  * global residual
326  *----------------------------------------------------------------------------*/
327 
328 double
330  const cs_real_t *vol,
331  const cs_real_t *x,
332  const cs_real_t *y);
333 
334 /*----------------------------------------------------------------------------
335  * Return the global volume weighted mean
336  * 1/sum(vol) . sum(vol.x)
337  *
338  * parameters:
339  * n <-- size of arrays x
340  * vol <-- array of floating-point values
341  * x <-- array of floating-point values
342  *
343  * returns:
344  * global residual
345  *----------------------------------------------------------------------------*/
346 
347 double
349  const cs_real_t *vol,
350  const cs_real_t *x);
351 
352 /*----------------------------------------------------------------------------*/
353 
355 
356 #endif /* __CS_BLAS_H__ */
double cs_gmean(cs_lnum_t n, const cs_real_t *vol, const cs_real_t *x)
Return the global spacial average of an intensive vectors: 1/sum(vol) . sum(x.vol)
Definition: cs_blas.c:1767
double cs_dot_wxx(cs_lnum_t n, const cs_real_t *w, const cs_real_t *x)
Definition: cs_blas.c:1533
double cs_dot(cs_lnum_t n, const cs_real_t *x, const cs_real_t *y)
Return the dot product of 2 vectors: x.y.
Definition: cs_blas.c:1493
void cs_dot_xx_yy_xy_xz_yz(cs_lnum_t n, const cs_real_t *restrict x, const cs_real_t *restrict y, const cs_real_t *restrict z, double *xx, double *yy, double *xy, double *xz, double *yz)
Return 5 dot products of 3 vectors: x.x, y.y, x.y, x.z, and y.z.
Definition: cs_blas.c:1682
void cs_dot_xy_yz(cs_lnum_t n, const cs_real_t *restrict x, const cs_real_t *restrict y, const cs_real_t *restrict z, double *xx, double *xy)
Return 2 dot products of 3 vectors: x.y, and y.z.
Definition: cs_blas.c:1621
void cs_axpy(cs_lnum_t n, double a, const cs_real_t *x, cs_real_t *restrict y)
Constant times a vector plus a vector: y <– ax + y.
Definition: cs_blas.c:1349
double cs_weighted_sum(cs_lnum_t n, const cs_real_t *w, const cs_real_t *x)
Definition: cs_blas.c:1436
double cs_dot_xx(cs_lnum_t n, const cs_real_t *x)
Return dot products of a vector with itself: x.x.
Definition: cs_blas.c:1514
cs_blas_reduce_t
Definition: cs_blas.h:57
@ CS_BLAS_REDUCE_KAHAN
Definition: cs_blas.h:60
@ CS_BLAS_REDUCE_SUPERBLOCK
Definition: cs_blas.h:59
void cs_blas_set_reduce_algorithm(cs_blas_reduce_t mode)
Set the preferred BLAS reduction algorithm family.
Definition: cs_blas.c:1310
double cs_gres(cs_lnum_t n, const cs_real_t *vol, const cs_real_t *x, const cs_real_t *y)
Return the global residual of 2 intensive vectors: 1/sum(vol) . sum(x.y.vol)
Definition: cs_blas.c:1742
double cs_sum(cs_lnum_t n, const cs_real_t *x)
Definition: cs_blas.c:1382
void cs_dot_xx_xy_yz(cs_lnum_t n, const cs_real_t *restrict x, const cs_real_t *restrict y, const cs_real_t *restrict z, double *xx, double *xy, double *yz)
Return 3 dot products of 3 vectors: x.x, x.y, and y.z.
Definition: cs_blas.c:1650
void cs_blas_library_info(cs_log_t log_type)
Print information on BLAS libraries used.
Definition: cs_blas.c:1284
void cs_dot_xx_xy(cs_lnum_t n, const cs_real_t *restrict x, const cs_real_t *restrict y, double *xx, double *xy)
Return 2 dot products of 2 vectors: x.x, and x.y.
Definition: cs_blas.c:1594
double cs_gdot(cs_lnum_t n, const cs_real_t *x, const cs_real_t *y)
Return the global dot product of 2 vectors: x.y.
Definition: cs_blas.c:1713
#define restrict
Definition: cs_defs.h:141
#define BEGIN_C_DECLS
Definition: cs_defs.h:528
double cs_real_t
Floating-point value.
Definition: cs_defs.h:332
#define END_C_DECLS
Definition: cs_defs.h:529
int cs_lnum_t
local mesh entity id
Definition: cs_defs.h:325
cs_log_t
Definition: cs_log.h:48