From 8d6ea502b9fe42b927fa078708155d874c9bf6fa Mon Sep 17 00:00:00 2001
From: Florent Pruvost <florent.pruvost@inria.fr>
Date: Fri, 9 Feb 2024 10:04:27 +0100
Subject: [PATCH] doc: update step6 and step7 coding style and documentation
---
doc/user/chapters/using.org | 68 +++++++++++++----------------
example/lapack_to_chameleon/step7.c | 14 +++---
example/lapack_to_chameleon/step7.h | 10 ++---
3 files changed, 42 insertions(+), 50 deletions(-)
diff --git a/doc/user/chapters/using.org b/doc/user/chapters/using.org
index 490a90268..ba307328d 100644
--- a/doc/user/chapters/using.org
+++ b/doc/user/chapters/using.org
@@ -687,34 +687,29 @@
In this program we use the tile data layout from PLASMA so that the call
#+begin_example
- CHAMELEON_Desc_Create_User(&descA, NULL, ChamRealDouble,
- NB, NB, NB*NB, N, N,
- 0, 0, N, N,
- GRID_P, GRID_Q,
- chameleon_getaddr_ccrb,
- chameleon_getblkldd_ccrb,
- chameleon_getrankof_2d, NULL);
+ CHAMELEON_Desc_Create(&descA, NULL, ChamRealDouble,
+ NB, NB, NB*NB, N, N,
+ 0, 0, N, N,
+ GRID_P, GRID_Q);
#+end_example
is equivalent to the following call
-
#+begin_example
- CHAMELEON_Desc_Create(&descA, NULL, ChamRealDouble,
- NB, NB, NB*NB, N, N,
- 0, 0, N, N,
- GRID_P, GRID_Q);
+ CHAMELEON_Desc_Create_User(&descA, NULL, ChamRealDouble,
+ NB, NB, NB*NB, N, N,
+ 0, 0, N, N,
+ GRID_P, GRID_Q,
+ chameleon_getaddr_ccrb,
+ chameleon_getblkldd_ccrb,
+ chameleon_getrankof_2d, NULL);
#+end_example
- functions *chameleon_getaddr_ccrb*, *chameleon_getblkldd_ccrb*,
- *chameleon_getrankof_2d* being used in *Desc_Create*. It is interesting
- to notice that the code is almost the same as Step5. The only
- additional information to give is the way tiles are distributed
- through the third function given to *CHAMELEON_Desc_Create_User*.
- Here, because we have made experiments only with a 2-D
- block-cyclic distribution, we have parameters P and Q in the
- interface of *Desc_Create* but they have sense only for 2-D
- block-cyclic distribution and then using *chameleon_getrankof_2d*
- function. Of course it could be used with other distributions,
- being no more the parameters of a 2-D block-cyclic grid but of
- another distribution.
+ functions *chameleon_getaddr_ccrb*, *chameleon_getblkldd_ccrb*, *chameleon_getrankof_2d* being used in *Desc_Create*. It
+ is interesting to notice that the code is almost the same as Step5. The only additional information to give is the
+ way tiles are distributed through the third function given to *CHAMELEON_Desc_Create_User*. Here, because we have
+ made experiments only with a 2-D block-cyclic distribution, we have parameters P and Q in the interface of
+ *Desc_Create* but they have sense only for 2-D block-cyclic distribution and then using *chameleon_getrankof_2d*
+ function. Of course it could be used with other distributions, being no more the parameters of a 2-D block-cyclic
+ grid but of another distribution. And the last parameter ~void* get_rankof_arg~ of CHAMELEON_Desc_Create_User can be
+ used to get custom data in the *get_rankof* function.
**** Step7
@@ -733,23 +728,20 @@
that the function used to fill the tiles is provided by the user,
and therefore this approach is much more flexible.
- The new function to understand is *CHAMELEON_dbuild_Tile*, e.g.
+ The new function to understand is *CHAMELEON_map_Tile*, e.g.
#+begin_example
- struct data_pl data_A={(double)N, 51, N};
- CHAMELEON_dbuild_Tile(ChamUpperLower, descA, (void*)&data_A,
- Cham_build_callback_plgsy);
+ struct data_pl data_A={(double)N, 51};
+ CHAMELEON_map_Tile(ChamW, ChamUpperLower, descA, Cham_map_plgsy, (void*)&data_A);
#+end_example
- The idea here is to let Chameleon fill the matrix data in a
- task-based fashion (parallel) by using a function given by the
- user. First, the user should define if all the blocks must be
- entirelly filled or just the upper/lower part with, /e.g./
- ChamUpperLower. We still relies on the same structure
- *CHAM_desc_t* which must be initialized with the proper
- parameters, by calling for example *CHAMELEON_Desc_Create*. Then, an
- opaque pointer is used to let the user give some extra data used
- by his function. The last parameter is the pointer to the user's
- function.
+ The idea here is to let Chameleon fill the matrix data in a task-based fashion (parallel) by using a function given
+ by the user. First, the user has to give the access mode to the matrix between: *ChamR, *ChamW*, *ChamRW* depending on
+ the kind of operations the callback function needs to do on the tiles. In our example here we fill the matrix with
+ random values for the first time so that we use the access mode *ChamW*. Second, the user should define if all the
+ blocks must be entirelly filled or just the upper/lower part with, /e.g./ ChamUpperLower. We still relies on the
+ same structure *CHAM_desc_t* which must be initialized with the proper parameters, by calling for example
+ *CHAMELEON_Desc_Create*. Then comes the pointer to the user's function. And finally the last parameter is an opaque
+ pointer is used to let the user give some extra data used by his function.
*** Using custom data distributions
:PROPERTIES:
diff --git a/example/lapack_to_chameleon/step7.c b/example/lapack_to_chameleon/step7.c
index 8802ee7e7..86b14a5cc 100644
--- a/example/lapack_to_chameleon/step7.c
+++ b/example/lapack_to_chameleon/step7.c
@@ -16,20 +16,20 @@
* @author Guillaume Sylvand
* @author Mathieu Faverge
* @author Philippe Virouleau
- * @date 2024-03-14
+ * @date 2024-03-16
*
*/
#include "step7.h"
/*
- * @brief step7 introduces how to use the build interface.
+ * @brief step7 introduces how to use the map interface.
* @details This program is a copy of step6 with some additional calls to
* build a matrix from within chameleon using a function provided by the user.
* This can be seen as a replacement of the function like CHAMELEON_dplgsy_Tile() that can be used
* to fill the matrix with random data, CHAMELEON_dLapack_to_Tile() to fill the matrix
* with data stored in a lapack-like buffer, or CHAMELEON_Desc_Create_User() that can be used
* to describe an arbitrary tile matrix structure.
- * In this example, the build callback function are just wrapper towards CORE_xxx() functions, so the output
+ * In this example, the map callback function are just wrapper towards CORE_xxx() functions, so the output
* of the program step7 should be exactly similar to that of step6.
* The difference is that the funtion used to fill the tiles is provided by the user,
* and therefore this approach is much more flexible.
@@ -133,7 +133,7 @@ int main(int argc, char *argv[]) {
GRID_P, GRID_Q);
/* generate A matrix with random values such that it is spd.
- We use the callback function Cham_build_callback_plgsy() defined in step7.h
+ We use the callback function Cham_build_plgsy() defined in step7.h
In this example, it is just a wrapper toward CORE_dplgsy() */
struct data_pl plgsy_args = { (double)N, 51 };
struct cham_map_operator_s plgsy_op = {
@@ -151,10 +151,10 @@ int main(int argc, char *argv[]) {
/* generate RHS with the callback Cham_build_callback_plrnt() */
struct data_pl plrnt_args = { 0., 5673 };
struct cham_map_operator_s plrnt_op = {
- .name = "plrnt",
- .cpufunc = Cham_build_plrnt_cpu,
+ .name = "plrnt",
+ .cpufunc = Cham_build_plrnt_cpu,
.cudafunc = NULL,
- .hipfunc = NULL,
+ .hipfunc = NULL,
};
struct cham_map_data_s plrnt_data = {
.access = ChamW,
diff --git a/example/lapack_to_chameleon/step7.h b/example/lapack_to_chameleon/step7.h
index 33d741442..4e5b4cd6c 100644
--- a/example/lapack_to_chameleon/step7.h
+++ b/example/lapack_to_chameleon/step7.h
@@ -15,7 +15,7 @@
* @author Florent Pruvost
* @author Guillaume Sylvand
* @author Mathieu Faverge
- * @date 2024-03-14
+ * @date 2024-03-16
*
*/
#ifndef _step7_h_
@@ -67,11 +67,9 @@ static void init_iparam(int iparam[IPARAM_SIZEOF]){
/**
* Callback function used to build matrix blocks
* Cham_build_callback_plgsy : random symmetric positive definite
- * Cham_build_callback_plrnt : random
+ * Cham_build_callback_plrnt : random general
* These 2 functions use data_pl to get data on the matrix to build, passed through the opaque pointer 'user_data'
- * The callback is expected to build the block of matrix [row_min, row_max] x [col_min, col_max]
- * (with both min and max values included in the intervals, index start at 0 like in C, NOT 1 like in Fortran)
- * and store it at the adresse 'buffer' with leading dimension 'ld'
+ * The callback is expected to build the block of matrix (m,n) and store it in tile->mat
*/
struct data_pl {
double bump;
@@ -88,6 +86,7 @@ static int Cham_build_plgsy_cpu( void *op_args, cham_uplo_t uplo, int m, int n,
tempmm = (m == (descA->mt-1)) ? (descA->m - m * descA->mb) : descA->mb;
tempnn = (n == (descA->nt-1)) ? (descA->n - n * descA->nb) : descA->nb;
+ /* fill the tile with the coreblas function plgsy = random SPD matrix generator */
TCORE_dplgsy( data->bump, tempmm, tempnn, tileA,
descA->m, m * descA->mb, n * descA->nb, data->seed );
@@ -105,6 +104,7 @@ static int Cham_build_plrnt_cpu( void *op_args, cham_uplo_t uplo, int m, int n,
tempmm = (m == (descA->mt-1)) ? (descA->m - m * descA->mb) : descA->mb;
tempnn = (n == (descA->nt-1)) ? (descA->n - n * descA->nb) : descA->nb;
+ /* fill the tile with the coreblas function plrnt = random general matrix generator */
TCORE_dplrnt( tempmm, tempnn, tileA,
descA->m, m * descA->mb, n * descA->nb, data->seed );
--
GitLab