From 0cf641023f766ce56532c1453ddce1d1c563beb7 Mon Sep 17 00:00:00 2001
From: matias hastaran <matias.hastaran@inria.fr>
Date: Tue, 28 Feb 2017 14:18:55 +0100
Subject: [PATCH] cleanup spm documentation
---
integer_sort.c | 8 +-
integer_sort_mtypes.c | 7 +-
spm.c | 3 +
spm.h | 148 ++++++++++++++++++++++----
spm_dofs.c | 22 ++++
spm_integers.c | 25 +++--
spm_io.c | 230 ++++++++++++++++++++++++++++++++++++++++-
spm_read_driver.c | 8 +-
z_spm.c | 26 +++--
z_spm_2dense.c | 96 +++++++++++++++++
z_spm_convert_to_csc.c | 12 ++-
z_spm_convert_to_csr.c | 11 +-
z_spm_convert_to_ijv.c | 10 +-
z_spm_dof_extend.c | 19 ++++
z_spm_dofs2flat.c | 10 +-
z_spm_expand.c | 73 +++++++++++++
z_spm_genrhs.c | 33 +++++-
z_spm_integer.c | 2 +-
z_spm_matrixvector.c | 51 +++++++--
z_spm_norm.c | 22 ++--
z_spm_print.c | 64 ++++++++++++
z_spm_scal.c | 4 +-
22 files changed, 796 insertions(+), 88 deletions(-)
diff --git a/integer_sort.c b/integer_sort.c
index edf89a3d..dd519240 100644
--- a/integer_sort.c
+++ b/integer_sort.c
@@ -30,16 +30,19 @@
Engineering a sort function; Jon Bentley and M. Douglas McIlroy;
Software - Practice and Experience; Vol. 23 (11), 1249-1265, 1993. */
-
/**
+ *******************************************************************************
+ *
* @file integer_sort.c
*
+ * @ingroup pastix_spm_dev
+ *
* File to include to create integer sort function using qsort based
* algorithm. DO NOT compile directly.
*
* @author François Pellegrini
*
-*/
+ *******************************************************************************/
#ifndef MAX_THRESH
#define MAX_THRESH 6
@@ -257,3 +260,4 @@ const pastix_int_t total_elems) /*+ Number of entries to sort
}
}
}
+
diff --git a/integer_sort_mtypes.c b/integer_sort_mtypes.c
index ccafb33d..e900c878 100644
--- a/integer_sort_mtypes.c
+++ b/integer_sort_mtypes.c
@@ -32,6 +32,10 @@
/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
* @file integer_sort_mtypes.c
*
* File to include to create a multi-types sort function using qsort based
@@ -39,7 +43,8 @@
*
* @author François Pellegrini
*
- */
+ *******************************************************************************/
+
#ifndef MAX_THRESH_2
#define MAX_THRESH_2 6
diff --git a/spm.c b/spm.c
index 1bb6738c..8e4db76a 100644
--- a/spm.c
+++ b/spm.c
@@ -22,6 +22,8 @@
#include "s_spm.h"
#include "p_spm.h"
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
+
static int (*conversionTable[3][3][6])(pastix_spm_t*) = {
/* From CSC */
{{ NULL, NULL, NULL, NULL, NULL, NULL },
@@ -67,6 +69,7 @@ static int (*conversionTable[3][3][6])(pastix_spm_t*) = {
{ NULL, NULL, NULL, NULL, NULL, NULL }}
};
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/**
*******************************************************************************
diff --git a/spm.h b/spm.h
index e97b6913..44b143fe 100644
--- a/spm.h
+++ b/spm.h
@@ -18,8 +18,6 @@
/**
* @ingroup pastix_spm
*
- * @enum pastix_driver_e
- *
* @brief The list of matrix driver reader and generators
*
*/
@@ -47,8 +45,6 @@ typedef enum pastix_driver_e {
/**
* @ingroup pastix_spm
*
- * @struct pastix_spm_s
- *
* @brief The sparse matrix data structure
*
* This structure describes matrices with different characteristics that can be useful to any solver:
@@ -89,43 +85,151 @@ struct pastix_spm_s {
void *values; /**< Values stored in the matrix */
};
-int
-csc_load( pastix_int_t *n,
- pastix_int_t **colptr,
- pastix_int_t **rows,
- int *valtype,
- void **values,
- int *dof,
- FILE *infile );
-
-int
-csc_save( pastix_int_t n,
- pastix_int_t *colptr,
- pastix_int_t *rows,
- int ft,
- void *values,
- int dof,
- FILE *outfile );
/**
* Integer arrays subroutines
*/
pastix_int_t *spmIntConvert( pastix_int_t n, int *input );
+
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm
+ *
+ * @brief Sorts in ascending order array of element composed of one single
+ * pastix_int_t with a single key value.
+ *
+ *******************************************************************************
+ *
+ * @param[in,out] pbase TODO
+ *
+ *
+ * @param[in] n
+ * The number of elements in the array.
+ *
+ *******************************************************************************
+ */
void spmIntSort1Asc1(void * const pbase, const pastix_int_t n);
+
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm
+ *
+ * @brief Sorts in ascending order array of element composed of two
+ * pastix_int_t by ascending order. The first value is used as key.
+ *
+ *******************************************************************************
+ *
+ * @param[in,out] pbase TODO
+ *
+ *
+ * @param[in] n
+ * The number of elements in the array.
+ *
+ *******************************************************************************
+ */
void spmIntSort2Asc1(void * const pbase, const pastix_int_t n);
+
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm
+ *
+ * @brief Sorts in ascending order array of element composed of two
+ * pastix_int_t by ascending order. Both values are used as key.
+ *
+ *******************************************************************************
+ *
+ * @param[in,out] pbase TODO
+ *
+ *
+ * @param[in] n
+ * The number of elements in the array.
+ *
+ *******************************************************************************
+ */
void spmIntSort2Asc2(void * const pbase, const pastix_int_t n);
/**
- * Subroutines to print elements of spm structures
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Subroutines to print elements of spm structures
+ *
+ *******************************************************************************
+ * @param[in] f Pointer to the file
+ *
+ * @param[in] i TODO
+ *
+ * @param[in] j TODO
+ *
+ * @param[in] A TODO
+ *******************************************************************************
*/
static inline void z_spmPrintElt( FILE *f, pastix_int_t i, pastix_int_t j, pastix_complex64_t A ){
fprintf( f, "%ld %ld %e %e\n", (long)i, (long)j, creal(A), cimag(A) );
}
+
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Subroutines to print elements of spm structures
+ *
+ *******************************************************************************
+ * @param[in] f Pointer to the file
+ *
+ * @param[in] i TODO
+ *
+ * @param[in] j TODO
+ *
+ * @param[in] A TODO
+ *******************************************************************************
+ */
static inline void c_spmPrintElt( FILE *f, pastix_int_t i, pastix_int_t j, pastix_complex32_t A ){
fprintf( f, "%ld %ld %e %e\n", (long)i, (long)j, crealf(A), cimagf(A) );
}
+
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Subroutines to print elements of spm structures
+ *
+ *******************************************************************************
+ * @param[in] f Pointer to the file
+ *
+ * @param[in] i TODO
+ *
+ * @param[in] j TODO
+ *
+ * @param[in] A TODO
+ *******************************************************************************
+ */
static inline void d_spmPrintElt( FILE *f, pastix_int_t i, pastix_int_t j, double A ){
fprintf( f, "%ld %ld %e\n", (long)i, (long)j, A );
}
+
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Subroutines to print elements of spm structures
+ *
+ *******************************************************************************
+ * @param[in] f Pointer to the file
+ *
+ * @param[in] i TODO
+ *
+ * @param[in] j TODO
+ *
+ * @param[in] A TODO
+ *******************************************************************************
+ */
static inline void s_spmPrintElt( FILE *f, pastix_int_t i, pastix_int_t j, float A ){
fprintf( f, "%ld %ld %e\n", (long)i, (long)j, A );
}
diff --git a/spm_dofs.c b/spm_dofs.c
index c94395bf..4febd9ba 100644
--- a/spm_dofs.c
+++ b/spm_dofs.c
@@ -22,6 +22,28 @@
#include "s_spm.h"
#include "p_spm.h"
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm
+ *
+ * @brief SPM multi-dof subroutines
+ *
+ * TODO
+ *
+ *******************************************************************************
+ *
+ * @param[in] type TODO
+ *
+ * @param[in] dof TODO
+ *
+ * @param[in] spm TODO
+ *
+ ********************************************************************************
+ *
+ * @return TODO
+ *
+ *******************************************************************************/
pastix_spm_t *
spmDofExtend( const int type,
const int dof,
diff --git a/spm_integers.c b/spm_integers.c
index b45833a2..455484e3 100644
--- a/spm_integers.c
+++ b/spm_integers.c
@@ -67,7 +67,7 @@ spmIntConvert( pastix_int_t n, int *input )
/**
*******************************************************************************
*
- * @ingroup pastix_spm
+ * @ingroup pastix_spm_dev
*
* @brief Sorts in ascending order array of element composed of one single
* pastix_int_t with a single key value.
@@ -75,6 +75,7 @@ spmIntConvert( pastix_int_t n, int *input )
*******************************************************************************
*/
#define INTSORTNAME spmIntSort1Asc1
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define INTSORTSIZE (sizeof (pastix_int_t))
#define INTSORTSWAP(p,q) do { \
pastix_int_t t; \
@@ -88,11 +89,12 @@ spmIntConvert( pastix_int_t n, int *input )
#undef INTSORTSIZE
#undef INTSORTSWAP
#undef INTSORTCMP
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/**
*******************************************************************************
*
- * @ingroup pastix_spm
+ * @ingroup pastix_spm_dev
*
* @brief Sorts in ascending order array of element composed of two
* pastix_int_t by ascending order. The first value is used as key.
@@ -100,6 +102,7 @@ spmIntConvert( pastix_int_t n, int *input )
*******************************************************************************
*/
#define INTSORTNAME spmIntSort2Asc1
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define INTSORTSIZE (2 * sizeof (pastix_int_t))
#define INTSORTSWAP(p,q) do { \
pastix_int_t t, u; \
@@ -116,11 +119,12 @@ spmIntConvert( pastix_int_t n, int *input )
#undef INTSORTSIZE
#undef INTSORTSWAP
#undef INTSORTCMP
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/**
*******************************************************************************
*
- * @ingroup pastix_spm
+ * @ingroup pastix_spm_dev
*
* @brief Sorts in ascending order array of element composed of three
* pastix_int_t by ascending order. The first value is used as key.
@@ -128,6 +132,7 @@ spmIntConvert( pastix_int_t n, int *input )
*******************************************************************************
*/
#define INTSORTNAME spmInt_intSort3Asc1
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define INTSORTSIZE (3 * sizeof (pastix_int_t))
#define INTSORTSWAP(p,q) do { \
pastix_int_t t, u, v; \
@@ -147,11 +152,12 @@ spmIntConvert( pastix_int_t n, int *input )
#undef INTSORTSIZE
#undef INTSORTSWAP
#undef INTSORTCMP
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/**
*******************************************************************************
*
- * @ingroup pastix_spm
+ * @ingroup pastix_spm_dev
*
* @brief Sorts in ascending order array of element composed of two
* pastix_int_t by ascending order. Both values are used as key.
@@ -159,6 +165,7 @@ spmIntConvert( pastix_int_t n, int *input )
*******************************************************************************
*/
#define INTSORTNAME spmIntSort2Asc2
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define INTSORTSIZE (2 * sizeof (pastix_int_t))
#define INTSORTSWAP(p,q) do { \
pastix_int_t t, u; \
@@ -175,11 +182,12 @@ spmIntConvert( pastix_int_t n, int *input )
#undef INTSORTSIZE
#undef INTSORTSWAP
#undef INTSORTCMP
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/**
*******************************************************************************
*
- * @ingroup pastix_spm
+ * @ingroup pastix_spm_dev
*
* @brief Sort 2 arrays simultaneously, the first array is an array of
* pastix_int_t and used as primary key for sorting. The second array is an
@@ -188,6 +196,7 @@ spmIntConvert( pastix_int_t n, int *input )
*******************************************************************************
*/
#define INTSORTNAME spmIntMSortIntAsc
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define INTSORTSIZE(x) (sizeof (pastix_int_t))
#define INTSORTNTAB 2
#define INTSORTSWAP(p,q) do { \
@@ -214,11 +223,12 @@ spmIntConvert( pastix_int_t n, int *input )
#undef INTSORTSWAP
#undef INTSORTCMP
#undef INTSORTNTAB
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/**
*******************************************************************************
*
- * @ingroup pastix_spm
+ * @ingroup pastix_spm_dev
*
* @brief Sort 2 arrays simultaneously, the first array is an array of
* pastix_int_t and used as primary key for sorting. The second array is an
@@ -227,6 +237,7 @@ spmIntConvert( pastix_int_t n, int *input )
*******************************************************************************
*/
#define INTSORTNAME spmIntMSortSmallIntAsc
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define INTSORTSIZE(x) (sizeof (int))
#define INTSORTNTAB 2
#define INTSORTSWAP(p,q) do { \
@@ -253,4 +264,4 @@ spmIntConvert( pastix_int_t n, int *input )
#undef INTSORTSWAP
#undef INTSORTCMP
#undef INTSORTNTAB
-
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
diff --git a/spm_io.c b/spm_io.c
index 3825cadb..89b7fd47 100644
--- a/spm_io.c
+++ b/spm_io.c
@@ -16,6 +16,31 @@
#include "common.h"
#include "spm.h"
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Read an array of integer.
+ *
+ *******************************************************************************
+ *
+ * @param[in] stream
+ * The opened file in which the spm is stored.
+ *
+ * @param[in] n
+ * Number of elements.
+ *
+ * @param[out] array
+ * Array of results.
+ *
+ ********************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the read happened successfuly.
+ * \retval PASTIX_ERR_FILE if the input format is incorrect.
+ *
+ *******************************************************************************/
static inline int
readArrayOfInteger( FILE *stream,
pastix_int_t n,
@@ -73,6 +98,31 @@ readArrayOfInteger( FILE *stream,
return PASTIX_SUCCESS;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Read an array of 64bits complex.
+ *
+ *******************************************************************************
+ *
+ * @param[in] stream
+ * The opened file in which the spm is stored.
+ *
+ * @param[in] n
+ * Number of elements.
+ *
+ * @param[out] array
+ * Array of results.
+ *
+ ********************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the read happened successfuly.
+ * \retval PASTIX_ERR_FILE if the input format is incorrect.
+ *
+ *******************************************************************************/
static inline int
readArrayOfComplex64( FILE *stream,
pastix_int_t n,
@@ -135,6 +185,31 @@ readArrayOfComplex64( FILE *stream,
return PASTIX_SUCCESS;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Read an array of 32bits complex.
+ *
+ *******************************************************************************
+ *
+ * @param[in] stream
+ * The opened file in which the spm is stored.
+ *
+ * @param[in] n
+ * Number of elements.
+ *
+ * @param[out] array
+ * Array of results.
+ *
+ ********************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the read happened successfuly.
+ * \retval PASTIX_ERR_FILE if the input format is incorrect.
+ *
+ *******************************************************************************/
static inline int
readArrayOfComplex32( FILE *stream,
pastix_int_t n,
@@ -197,6 +272,31 @@ readArrayOfComplex32( FILE *stream,
return PASTIX_SUCCESS;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Read an array of double.
+ *
+ *******************************************************************************
+ *
+ * @param[in] stream
+ * The opened file in which the spm is stored.
+ *
+ * @param[in] n
+ * Number of elements.
+ *
+ * @param[out] array
+ * Array of results.
+ *
+ ********************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the read happened successfuly.
+ * \retval PASTIX_ERR_FILE if the input format is incorrect.
+ *
+ *******************************************************************************/
static inline int
readArrayOfDouble( FILE *stream,
pastix_int_t n,
@@ -256,6 +356,32 @@ readArrayOfDouble( FILE *stream,
return PASTIX_SUCCESS;
}
+
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Read an array of float.
+ *
+ *******************************************************************************
+ *
+ * @param[in] stream
+ * The opened file in which the spm is stored.
+ *
+ * @param[in] n
+ * Number of elements.
+ *
+ * @param[out] array
+ * Array of results.
+ *
+ ********************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the read happened successfuly.
+ * \retval PASTIX_ERR_FILE if the input format is incorrect.
+ *
+ *******************************************************************************/
static inline int
readArrayOfFloat( FILE *stream,
pastix_int_t n,
@@ -333,6 +459,12 @@ readArrayOfFloat( FILE *stream,
* @param[in] infile
* The opened file in which the spm is stored.
*
+ *******************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the load happened successfuly.
+ * \retval PASTIX_ERR_FILE if the input format is incorrect.
+ *
*******************************************************************************/
int
spmLoad( pastix_spm_t *spm,
@@ -477,7 +609,29 @@ spmLoad( pastix_spm_t *spm,
return rc;
}
-
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief write an array of 64bits complex.
+ *
+ *******************************************************************************
+ *
+ * @param[in] outfile
+ * TODO
+ *
+ * @param[in] n
+ * numbers of elements.
+ *
+ * @param[in] array
+ * array to write.
+ *
+ *******************************************************************************
+ *
+ * @return PASTIX_SUCCESS if the write happened successfuly.
+ *
+ *******************************************************************************/
static inline int
writeArrayOfComplex64( FILE *outfile,
pastix_int_t n,
@@ -496,6 +650,29 @@ writeArrayOfComplex64( FILE *outfile,
return PASTIX_SUCCESS;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief write an array of 32bits complex.
+ *
+ *******************************************************************************
+ *
+ * @param[in] outfile
+ * TODO
+ *
+ * @param[in] n
+ * numbers of elements.
+ *
+ * @param[in] array
+ * array to write.
+ *
+ *******************************************************************************
+ *
+ * @return PASTIX_SUCCESS if the write happened successfuly.
+ *
+ *******************************************************************************/
static inline int
writeArrayOfComplex32( FILE *outfile,
pastix_int_t n,
@@ -514,6 +691,29 @@ writeArrayOfComplex32( FILE *outfile,
return PASTIX_SUCCESS;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief write an array of double.
+ *
+ *******************************************************************************
+ *
+ * @param[in] outfile
+ * TODO
+ *
+ * @param[in] n
+ * numbers of elements.
+ *
+ * @param[in] array
+ * array to write.
+ *
+ *******************************************************************************
+ *
+ * @return PASTIX_SUCCESS if the write happened successfuly.
+ *
+ *******************************************************************************/
static inline int
writeArrayOfDouble( FILE *outfile,
pastix_int_t n,
@@ -532,6 +732,30 @@ writeArrayOfDouble( FILE *outfile,
return PASTIX_SUCCESS;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief write an array of float.
+ *
+ *******************************************************************************
+ *
+ * @param[in] outfile
+ * TODO
+ *
+ * @param[in] n
+ * numbers of elements.
+ *
+ * @param[in] array
+ * array to write.
+ *
+ *******************************************************************************
+ *
+ * @return PASTIX_SUCCESS if the write happened successfuly.
+ *
+ *
+ *******************************************************************************/
static inline int
writeArrayOfFloat( FILE *outfile,
pastix_int_t n,
@@ -568,6 +792,10 @@ writeArrayOfFloat( FILE *outfile,
* @param[in] outfile
* The opened file in which to store the spm.
*
+ ********************************************************************************
+ *
+ * @return PASTIX_SUCCESS if the save happened successfuly
+ *
*******************************************************************************/
int
spmSave( pastix_spm_t *spm,
diff --git a/spm_read_driver.c b/spm_read_driver.c
index 3c42bbe9..8c4600e6 100644
--- a/spm_read_driver.c
+++ b/spm_read_driver.c
@@ -48,10 +48,16 @@
* On exit, the filled sparse matrix structure with the matrix from the
* file.
*
- * @param[in] pastix_comm
+ * @param[in] comm
* The MPI communicator on which to distribute the sparse matrix. This
* is also used in case of distributed formats.
*
+ ********************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the file reading happened successfuly
+ * \retval PASTIX_ERR_BADPARAMETER if one the parameter is incorrect.
+ *
*******************************************************************************/
int
spmReadDriver( pastix_driver_t driver,
diff --git a/z_spm.c b/z_spm.c
index ed003155..4560b551 100644
--- a/z_spm.c
+++ b/z_spm.c
@@ -20,11 +20,12 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmSort - This routine sorts the subarray of edges of each vertex in a
- * centralized spm stored in CSC or CSR format. Nothing is performed if IJV
- * format is used.
+ * @brief This routine sorts the subarray of edges of each vertex in a
+ * centralized spm stored in CSC or CSR format.
+ *
+ * Nothing is performed if IJV format is used.
*
* WARNING: This function should NOT be called if dof is greater than 1.
*
@@ -90,11 +91,12 @@ z_spmSort( pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
+ *
+ * @brief This routine merge the multiple entries in a sparse
+ * matrix by suming their values together.
*
- * z_spmMergeDuplicate - This routine merge the multiple entries in a sparse
- * matrix by suming their values together. The sparse matrix needs to be sorted
- * first (see z_spmSort()).
+ * The sparse matrix needs to be sorted first (see z_spmSort()).
*
* WARNING: This function should NOT be called if dof is greater than 1.
*
@@ -184,10 +186,12 @@ z_spmMergeDuplicate( pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
+ *
+ * @brief This routine corrects the sparse matrix structure if it's
+ * pattern is not symmetric.
*
- * z_spmSymmetrize - This routine corrects the sparse matrix structure if it's
- * pattern is not symmetric. It returns the new symmetric pattern with zeores on
+ * It returns the new symmetric pattern with zeores on
* the new entries.
*
*******************************************************************************
diff --git a/z_spm_2dense.c b/z_spm_2dense.c
index ad9933ff..da31bf3a 100644
--- a/z_spm_2dense.c
+++ b/z_spm_2dense.c
@@ -24,6 +24,25 @@
#include "spm.h"
#include "z_spm.h"
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Convert a CSC matrix into a dense matrix.
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix uses to generate the right hand side, and the
+ * solution of the full problem.
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval A TODO
+ *
+ *******************************************************************************/
pastix_complex64_t *
z_spmCSC2dense( const pastix_spm_t *spm )
{
@@ -181,6 +200,25 @@ z_spmCSC2dense( const pastix_spm_t *spm )
return A;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Convert a CSR matrix into a dense matrix.
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix uses to generate the right hand side, and the
+ * solution of the full problem.
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval A TODO
+ *
+ *******************************************************************************/
pastix_complex64_t *
z_spmCSR2dense( const pastix_spm_t *spm )
{
@@ -338,6 +376,25 @@ z_spmCSR2dense( const pastix_spm_t *spm )
return A;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Convert a IJV matrix into a dense matrix.
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix uses to generate the right hand side, and the
+ * solution of the full problem.
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval A TODO
+ *
+ *******************************************************************************/
pastix_complex64_t *
z_spmIJV2dense( const pastix_spm_t *spm )
{
@@ -511,6 +568,25 @@ z_spmIJV2dense( const pastix_spm_t *spm )
return A;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Convert a sparse matrix into a dense matrix.
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix uses to generate the right hand side, and the
+ * solution of the full problem.
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval A TODO
+ *
+ *******************************************************************************/
pastix_complex64_t *
z_spm2dense( const pastix_spm_t *spm )
{
@@ -525,6 +601,26 @@ z_spm2dense( const pastix_spm_t *spm )
return NULL;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief TODO
+ *
+ *******************************************************************************
+ *
+ * @param[in] f
+ *
+ * @param[in] m
+ *
+ * @param[in] n
+ *
+ * @param[in] A
+ *
+ * @param[in] lda
+ *
+ *******************************************************************************/
void
z_spmDensePrint( FILE *f, pastix_int_t m, pastix_int_t n, pastix_complex64_t *A, pastix_int_t lda )
{
diff --git a/z_spm_convert_to_csc.c b/z_spm_convert_to_csc.c
index ed0db67d..4b0a2c83 100644
--- a/z_spm_convert_to_csc.c
+++ b/z_spm_convert_to_csc.c
@@ -20,9 +20,9 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmConvertIJV2CSC - convert a matrix in IJV format to a matrix in CSC
+ * @brief convert a matrix in IJV format to a matrix in CSC
* format.
*
*******************************************************************************
@@ -126,10 +126,12 @@ z_spmConvertIJV2CSC( pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmConvertCSR2CSC - convert a matrix in CSR format to a matrix in CSC
- * format. If the matrix is PastixSymmetric or PastixHermitian, then the
+ * @brief convert a matrix in CSR format to a matrix in CSC
+ * format.
+ *
+ * If the matrix is PastixSymmetric or PastixHermitian, then the
* transpose or respectively the conjugate is returned.
*
*******************************************************************************
diff --git a/z_spm_convert_to_csr.c b/z_spm_convert_to_csr.c
index 026df262..363654c9 100644
--- a/z_spm_convert_to_csr.c
+++ b/z_spm_convert_to_csr.c
@@ -20,10 +20,11 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmConvertCSC2CSR - convert a matrix in CSC format to a matrix in CSR
- * format. If the matrix is PastixSymmetric or PastixHermitian, then the
+ * @brief convert a matrix in CSC format to a matrix in CSR format.
+ *
+ * If the matrix is PastixSymmetric or PastixHermitian, then the
* transpose or respectively the conjugate is returned.
*
*******************************************************************************
@@ -99,9 +100,9 @@ z_spmConvertCSC2CSR( pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmConvertIJV2CSR - convert a matrix in IJV format to a matrix in CSR
+ * @brief convert a matrix in IJV format to a matrix in CSR
* format.
*
*******************************************************************************
diff --git a/z_spm_convert_to_ijv.c b/z_spm_convert_to_ijv.c
index 6ab25d09..6cb9afe8 100644
--- a/z_spm_convert_to_ijv.c
+++ b/z_spm_convert_to_ijv.c
@@ -20,10 +20,9 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmConvertCSC2IJV - convert a matrix in CSC format to a matrix in IJV
- * format.
+ * @brief convert a matrix in CSC format to a matrix in IJV format.
*
*******************************************************************************
*
@@ -71,10 +70,9 @@ z_spmConvertCSC2IJV( pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmConvertCSR2IJV - convert a matrix in CSR format to a matrix in IJV
- * format.
+ * @brief convert a matrix in CSR format to a matrix in IJV format.
*
*******************************************************************************
*
diff --git a/z_spm_dof_extend.c b/z_spm_dof_extend.c
index 7e03fce0..0db18910 100644
--- a/z_spm_dof_extend.c
+++ b/z_spm_dof_extend.c
@@ -17,6 +17,25 @@
#include "spm.h"
#include "z_spm.h"
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief convert a matrix in CSR format to a matrix in IJV format.
+ *
+ *******************************************************************************
+ *
+ * @param[in,out] spm
+ * The sparse matrix uses to generate the right hand side, and the
+ * solution of the full problem.
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS
+ *
+ *******************************************************************************/
void
z_spmDofExtend(pastix_spm_t *spm)
{
diff --git a/z_spm_dofs2flat.c b/z_spm_dofs2flat.c
index e196ea9c..16a466ec 100644
--- a/z_spm_dofs2flat.c
+++ b/z_spm_dofs2flat.c
@@ -29,9 +29,9 @@
/**
*******************************************************************************
*
- * @ingroup spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmDofs2Flat - Convert a sparse matrix with dofs into a sparse matrix without dofs.
+ * @brief Convert a sparse matrix with dofs into a sparse matrix without dofs.
*
*
*******************************************************************************
@@ -40,7 +40,11 @@
* The sparse matrix which needs to be converted
*
*******************************************************************************
- **/
+ *
+ * @return
+ * \retval PASTIX_SUCCESS
+ *
+ *******************************************************************************/
void
z_spmDofs2Flat(pastix_spm_t *spm)
{
diff --git a/z_spm_expand.c b/z_spm_expand.c
index 69c4a67b..160205c7 100644
--- a/z_spm_expand.c
+++ b/z_spm_expand.c
@@ -17,6 +17,25 @@
#include "spm.h"
#include "z_spm.h"
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief TODO
+ *
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix which needs to be converted
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval newspm
+ *
+ *******************************************************************************/
pastix_spm_t *
z_spmCSCExpand(const pastix_spm_t *spm)
{
@@ -180,6 +199,24 @@ z_spmCSCExpand(const pastix_spm_t *spm)
return newspm;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief TODO
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix which needs to be converted
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval newspm TODO
+ *
+ *******************************************************************************/
pastix_spm_t *
z_spmCSRExpand(const pastix_spm_t *spm)
{
@@ -341,6 +378,24 @@ z_spmCSRExpand(const pastix_spm_t *spm)
return newspm;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief TODO
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix which needs to be converted
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval newspm TODO
+ *
+ *******************************************************************************/
pastix_spm_t *
z_spmIJVExpand(const pastix_spm_t *spm)
{
@@ -492,6 +547,24 @@ z_spmIJVExpand(const pastix_spm_t *spm)
return newspm;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief TODO
+ *
+ *******************************************************************************
+ *
+ * @param[in] spm
+ * The sparse matrix which needs to be converted
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS
+ *
+ *******************************************************************************/
pastix_spm_t *
z_spmExpand( const pastix_spm_t *spm )
{
diff --git a/z_spm_genrhs.c b/z_spm_genrhs.c
index 8a2defa4..3da90ec8 100644
--- a/z_spm_genrhs.c
+++ b/z_spm_genrhs.c
@@ -21,15 +21,37 @@
#include "z_spm.h"
#include "kernels/pastix_zcores.h"
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#define Rnd64_A 6364136223846793005ULL
#define Rnd64_C 1ULL
#define RndF_Mul 5.4210108624275222e-20f
#define RndD_Mul 5.4210108624275222e-20
+
static pastix_complex64_t mzone = (pastix_complex64_t)-1.;
static pastix_complex64_t zone = (pastix_complex64_t) 1.;
static pastix_complex64_t zzero = (pastix_complex64_t) 0.;
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief TODO
+ *
+ *******************************************************************************
+ *
+ * @param[in] n
+ *
+ * @param[in] seed
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval ran
+ *
+ *******************************************************************************/
static inline unsigned long long int
Rnd64_jump(unsigned long long int n, unsigned long long int seed ) {
unsigned long long int a_k, c_k, ran;
@@ -49,21 +71,26 @@ Rnd64_jump(unsigned long long int n, unsigned long long int seed ) {
return ran;
}
+#ifndef DOXYGEN_SHOULD_SKIP_THIS
#if defined(PRECISION_z) || defined(PRECISION_c)
#define NBELEM 2
#else
#define NBELEM 1
#endif
+#endif /* DOXYGEN_SHOULD_SKIP_THIS */
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
* z_spmRndVect generates a random vector for testing purpose.
*
*******************************************************************************
*
+ * @param[in] scale
+ * TODO
+ *
* @param[in] m
* The number of rows of the tile A. m >= 0.
*
@@ -119,7 +146,7 @@ void z_spmRndVect( double scale, int m, int n, pastix_complex64_t *A, int lda,
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
* z_spmGenRHS - Generate nrhs right hand side vectors associated to a given
* matrix to test a problem with a solver.
@@ -280,7 +307,7 @@ z_spmGenRHS( int type, int nrhs,
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
* z_spmCheckAxb - Check the backward error, and the forward error if x0 is
* provided.
diff --git a/z_spm_integer.c b/z_spm_integer.c
index d9d3a115..e56c23d5 100644
--- a/z_spm_integer.c
+++ b/z_spm_integer.c
@@ -24,7 +24,7 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm
+ * @ingroup pastix_spm_dev
*
* @brief Sort 2 arrays simultaneously, the first array is an array of
* pastix_int_t and used as key for sorting. The second array is an array of
diff --git a/z_spm_matrixvector.c b/z_spm_matrixvector.c
index 48496628..9a7009d1 100644
--- a/z_spm_matrixvector.c
+++ b/z_spm_matrixvector.c
@@ -20,9 +20,9 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmGeCSCv - compute the matrix-vector product:
+ * @brief compute the matrix-vector product:
* y = alpha * op( A ) * x + beta * y
*
* A is a PastixGeneral csc, where op( X ) is one of
@@ -152,9 +152,9 @@ z_spmGeCSCv(const pastix_trans_t trans,
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmSYCSCv - compute the matrix-vector product:
+ * @brief compute the matrix-vector product:
* y = alpha * A + beta * y
*
* A is a PastixSymmetric csc, alpha and beta are scalars, and x and y are
@@ -241,9 +241,9 @@ z_spmSyCSCv( pastix_complex64_t alpha,
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmHeCSCv - compute the matrix-vector product:
+ * @brief compute the matrix-vector product:
* y = alpha * A + beta * y
*
* A is a PastixHermitian csc, alpha and beta are scalars, and x and y are
@@ -329,7 +329,44 @@ z_spmHeCSCv( pastix_complex64_t alpha,
}
#endif
-
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief compute the matrix-vector product:
+ * y = alpha * A + beta * y
+ *
+ * A is a PastixHermitian csc, alpha and beta are scalars, and x and y are
+ * vectors, and A a symm.
+ *
+ *******************************************************************************
+ *
+ * @param[in] trans
+ * TODO
+ *
+ * @param[in] alphaptr
+ * alpha specifies the scalar alpha
+ *
+ * @param[in] csc
+ * The PastixHermitian csc.
+ *
+ * @param[in] xptr
+ * The vector x.
+ *
+ * @param[in] betaptr
+ * beta specifies the scalar beta
+ *
+ * @param[in,out] yptr
+ * The vector y.
+ *
+ *******************************************************************************
+ *
+ * @return
+ * \retval PASTIX_SUCCESS if the y vector has been computed succesfully,
+ * \retval PASTIX_ERR_BADPARAMETER otherwise.
+ *
+ *******************************************************************************/
int
z_spmCSCMatVec(const pastix_trans_t trans,
const void *alphaptr,
diff --git a/z_spm_norm.c b/z_spm_norm.c
index f6d4d17b..e64fc46b 100644
--- a/z_spm_norm.c
+++ b/z_spm_norm.c
@@ -23,9 +23,9 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmFrobeniusNorm - Compute the Frobenius norm of the non distributed given
+ * @brief Compute the Frobenius norm of the non distributed given
* spm structure.
*
* ||A|| = sqrt( sum( a_ij ^ 2 ) )
@@ -114,9 +114,9 @@ z_spmFrobeniusNorm( const pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmMaxNorm - Compute the Max norm of the non distributed given spm
+ * @brief Compute the Max norm of the non distributed given spm
* structure.
*
* ||A|| = max( abs(a_ij) )
@@ -150,9 +150,9 @@ z_spmMaxNorm( const pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmInfNorm - Compute the Infinity norm of the non distributed given spm
+ * @brief Compute the Infinity norm of the non distributed given spm
* structure given by the maximum column sum.
*
* ||A|| = max_i( sum_j(|a_ij|) )
@@ -268,9 +268,9 @@ z_spmInfNorm( const pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmOneNorm - Compute the Oneinity norm of the non distributed given spm
+ * @brief Compute the Oneinity norm of the non distributed given spm
* structure fiven by the maximum row sum
*
* ||A|| = max_j( sum_i(|a_ij|) )
@@ -382,13 +382,13 @@ z_spmOneNorm( const pastix_spm_t *spm )
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmNorm - Compute the norm of an spm matrix
+ * @brief Compute the norm of an spm matrix
*
*******************************************************************************
*
- * @param[in] type
+ * @param[in] ntype
* = PastixMaxNorm: Max norm
* = PastixOneNorm: One norm
* = PastixInfNorm: Infinity norm
diff --git a/z_spm_print.c b/z_spm_print.c
index 0633f555..e6b6bcbb 100644
--- a/z_spm_print.c
+++ b/z_spm_print.c
@@ -24,6 +24,22 @@
#include "spm.h"
#include "z_spm.h"
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Write CSC matrix in a file
+ *
+ *******************************************************************************
+ *
+ * @param[in] f
+ * Output file
+ *
+ * @param[in] spm
+ * The spm structure describing the matrix.
+ *
+ *******************************************************************************/
void
z_spmCSCPrint( FILE *f, const pastix_spm_t *spm )
{
@@ -193,6 +209,22 @@ z_spmCSCPrint( FILE *f, const pastix_spm_t *spm )
return;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Write CSR matrix in a file
+ *
+ *******************************************************************************
+ *
+ * @param[in] f
+ * Output file
+ *
+ * @param[in] spm
+ * The spm structure describing the matrix.
+ *
+ *******************************************************************************/
void
z_spmCSRPrint( FILE *f, const pastix_spm_t *spm )
{
@@ -362,6 +394,22 @@ z_spmCSRPrint( FILE *f, const pastix_spm_t *spm )
return;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Write IJV matrix in a file
+ *
+ *******************************************************************************
+ *
+ * @param[in] f
+ * Output file
+ *
+ * @param[in] spm
+ * The spm structure describing the matrix.
+ *
+ *******************************************************************************/
void
z_spmIJVPrint( FILE *f, const pastix_spm_t *spm )
{
@@ -549,6 +597,22 @@ z_spmIJVPrint( FILE *f, const pastix_spm_t *spm )
return;
}
+/**
+ *******************************************************************************
+ *
+ * @ingroup pastix_spm_dev
+ *
+ * @brief Write a spm matrix in a file
+ *
+ *******************************************************************************
+ *
+ * @param[in] f
+ * Output file
+ *
+ * @param[in] spm
+ * The spm structure describing the matrix.
+ *
+ *******************************************************************************/
void
z_spmPrint( FILE *f, const pastix_spm_t *spm )
{
diff --git a/z_spm_scal.c b/z_spm_scal.c
index 436ec6a5..220b066a 100644
--- a/z_spm_scal.c
+++ b/z_spm_scal.c
@@ -22,9 +22,9 @@
/**
*******************************************************************************
*
- * @ingroup pastix_spm_internal
+ * @ingroup pastix_spm_dev
*
- * z_spmScal - Scal the spm: A = alpha * A
+ * @brief Scal the spm: A = alpha * A
*
*******************************************************************************
*
--
GitLab