My Project
programmer's documentation
Macros | Typedefs | Functions
cs_matrix_assembler.h File Reference
#include "cs_defs.h"
#include "cs_halo.h"
#include "cs_log.h"
Include dependency graph for cs_matrix_assembler.h:

Go to the source code of this file.

Macros

#define CS_MATRIX_DISTANT_ROW_USE_COL_IDX   (1 << 0)
 
#define CS_MATRIX_DISTANT_ROW_USE_COL_G_ID   (1 << 1)
 
#define CS_MATRIX_EXTERNAL_HALO   (1 << 2)
 

Typedefs

typedef struct _cs_matrix_assembler_t cs_matrix_assembler_t
 
typedef struct _cs_matrix_assembler_values_t cs_matrix_assembler_values_t
 
typedef void() cs_matrix_assembler_values_init_t(void *matrix, const cs_lnum_t *db_size, const cs_lnum_t *eb_size)
 Function pointer for initialization of matrix coefficients using local row ids and column indexes. More...
 
typedef void() cs_matrix_assembler_values_add_t(void *matrix, cs_lnum_t n, cs_lnum_t stride, const cs_lnum_t row_id[], const cs_lnum_t col_idx[], const cs_real_t vals[])
 Function pointer for addition to matrix coefficients using local row ids and column indexes. More...
 
typedef void() cs_matrix_assembler_values_cdo_add_t(void *matrix, cs_lnum_t row_id, cs_lnum_t stride, cs_lnum_t n_cols, const cs_real_t diag_val[], const cs_lnum_t col_idx[], const cs_real_t vals[])
 Function pointer for addition to matrix coefficients using local row ids and column indexes in case of CDO schemes. Contrary to other add_values() function. Here values are structured in a CSR-like way. By this way one avoids to allocate specific arrays for this step. More...
 
typedef void() cs_matrix_assembler_values_add_g_t(void *matrix, cs_lnum_t n, cs_lnum_t stride, const cs_gnum_t row_g_id[], const cs_gnum_t col_g_id[], const cs_real_t vals[])
 Function pointer for addition to matrix coefficients using global row ids and column indexes. More...
 
typedef void() cs_matrix_assembler_values_begin_t(void *matrix)
 Function pointer to start the final assembly of matrix coefficients. More...
 
typedef void() cs_matrix_assembler_values_end_t(void *matrix)
 Function pointer to complete the final assembly of matrix coefficients. More...
 

Functions

cs_matrix_assembler_tcs_matrix_assembler_create (const cs_gnum_t l_range[2], bool separate_diag)
 Create a matrix assembler structure. More...
 
cs_matrix_assembler_tcs_matrix_assembler_create_from_shared (cs_lnum_t n_rows, bool separate_diag, const cs_lnum_t row_idx[], const cs_lnum_t col_id[], const cs_halo_t *halo)
 Create a matrix assembler structure based on a given connectivity and associated halo structure. More...
 
void cs_matrix_assembler_destroy (cs_matrix_assembler_t **ma)
 Destroy a matrix assembler structure. More...
 
void cs_matrix_assembler_add_g_ids (cs_matrix_assembler_t *ma, cs_lnum_t n, const cs_gnum_t g_row_id[], const cs_gnum_t g_col_id[])
 Add entries to a matrix assembler structure. More...
 
void cs_matrix_assembler_compute (cs_matrix_assembler_t *ma)
 Compute internal structures required by a matrix assembler. More...
 
void cs_matrix_assembler_set_options (cs_matrix_assembler_t *ma, int flags)
 Set option flags for a given matrix assembler structure. More...
 
int cs_matrix_assembler_get_options (const cs_matrix_assembler_t *ma)
 Return the option flags for a given matrix assembler structure. More...
 
const cs_gnum_tcs_matrix_assembler_get_l_range (const cs_matrix_assembler_t *ma)
 Return a pointer to local global row range associated with a matrix assembler. More...
 
const cs_halo_tcs_matrix_assembler_get_halo (const cs_matrix_assembler_t *ma)
 Return a pointer to the halo structure associated with a matrix assembler. More...
 
bool cs_matrix_assembler_get_separate_diag (const cs_matrix_assembler_t *ma)
 Indicate if the matrix assembler is based on a separate diagonal. More...
 
cs_lnum_t cs_matrix_assembler_get_n_rows (const cs_matrix_assembler_t *ma)
 Return the number of rows associated with a matrix assembler. More...
 
cs_lnum_t cs_matrix_assembler_get_n_columns (const cs_matrix_assembler_t *ma)
 Return the number of columns associated with a matrix assembler. More...
 
const cs_lnum_tcs_matrix_assembler_get_row_index (const cs_matrix_assembler_t *ma)
 Return a row index associated with a matrix assembler. More...
 
const cs_lnum_tcs_matrix_assembler_get_col_ids (const cs_matrix_assembler_t *ma)
 Return a column ids associated with a matrix assembler. More...
 
void cs_matrix_assembler_get_rank_counts (const cs_matrix_assembler_t *ma, int rc[4])
 Return info on the number of neighbor ranks a matrix assembler may communicate with. More...
 
void cs_matrix_assembler_log_rank_counts (const cs_matrix_assembler_t *ma, cs_log_t log_id, const char *name)
 Log rank counts for a given matrix assembler. More...
 
cs_matrix_assembler_values_tcs_matrix_assembler_values_create (const cs_matrix_assembler_t *ma, bool sep_diag, const cs_lnum_t *db_size, const cs_lnum_t *eb_size, void *matrix, cs_matrix_assembler_values_init_t *init, cs_matrix_assembler_values_add_t *add, cs_matrix_assembler_values_add_g_t *add_g, cs_matrix_assembler_values_begin_t *begin, cs_matrix_assembler_values_end_t *end)
 Create and initialize a matrix assembler values structure. More...
 
void cs_matrix_assembler_values_finalize (cs_matrix_assembler_values_t **mav)
 Finalize matrix assembler values structure. More...
 
void cs_matrix_assembler_values_add (cs_matrix_assembler_values_t *mav, cs_lnum_t n, const cs_lnum_t row_id[], const cs_lnum_t col_id[], const cs_real_t val[])
 Add values to a matrix assembler values structure using local row and column ids. More...
 
void cs_matrix_assembler_values_add_g (cs_matrix_assembler_values_t *mav, cs_lnum_t n, const cs_gnum_t g_row_id[], const cs_gnum_t g_col_id[], const cs_real_t val[])
 Add values to a matrix assembler values structure using global row and column ids. More...
 
void cs_matrix_assembler_values_done (cs_matrix_assembler_values_t *mav)
 Start assembly of matrix values structure. More...
 

Macro Definition Documentation

◆ CS_MATRIX_DISTANT_ROW_USE_COL_G_ID

#define CS_MATRIX_DISTANT_ROW_USE_COL_G_ID   (1 << 1)

◆ CS_MATRIX_DISTANT_ROW_USE_COL_IDX

#define CS_MATRIX_DISTANT_ROW_USE_COL_IDX   (1 << 0)

Matrix assembler option flags

◆ CS_MATRIX_EXTERNAL_HALO

#define CS_MATRIX_EXTERNAL_HALO   (1 << 2)

Typedef Documentation

◆ cs_matrix_assembler_t

typedef struct _cs_matrix_assembler_t cs_matrix_assembler_t

Structure used to pre-build a matrix structure

◆ cs_matrix_assembler_values_add_g_t

typedef void() cs_matrix_assembler_values_add_g_t(void *matrix, cs_lnum_t n, cs_lnum_t stride, const cs_gnum_t row_g_id[], const cs_gnum_t col_g_id[], const cs_real_t vals[])

Function pointer for addition to matrix coefficients using global row ids and column indexes.

Values whose global row id is outside the local range should be ignored (this allows simply filtering values before calling this function, avoiding an extra copy (a copy will probably be done by the function anyways).

Warning
The matrix pointer must point to valid data when the selection function is called, so the life cycle of the data pointed to should be at least as long as that of the assembler values structure.
Parameters
[in,out]matrixuntyped pointer to matrix description structure
[in]nnumber of values to add
[in]strideassociated data block size
[in]g_row_idassociated global row ids
[in]g_col_idassociated global column ids
[in]valpointer to values (size: n*stride)

◆ cs_matrix_assembler_values_add_t

typedef void() cs_matrix_assembler_values_add_t(void *matrix, cs_lnum_t n, cs_lnum_t stride, const cs_lnum_t row_id[], const cs_lnum_t col_idx[], const cs_real_t vals[])

Function pointer for addition to matrix coefficients using local row ids and column indexes.

Values whose associated row index is negative should be ignored; Values whose column index is -1 are assumed to be assigned to a separately stored diagonal. Other indexes should be valid.

Warning
The matrix pointer must point to valid data when the selection function is called, so the life cycle of the data pointed to should be at least as long as that of the assembler values structure.
Remarks
Note that we pass column indexes (not ids) here; as the caller is already assumed to have identified the index matching a given column id.
Parameters
[in,out]matrixuntyped pointer to matrix description structure
[in]nnumber of values to add
[in]strideassociated data block size
[in]row_idassociated local row ids
[in]col_idxassociated local column indexes
[in]valpointer to values (size: n*stride)

◆ cs_matrix_assembler_values_begin_t

typedef void() cs_matrix_assembler_values_begin_t(void *matrix)

Function pointer to start the final assembly of matrix coefficients.

Warning
The matrix pointer must point to valid data when the selection function is called, so the life cycle of the data pointed to should be at least as long as that of the assembler values structure.
Parameters
[in,out]matrixuntyped pointer to matrix description structure

◆ cs_matrix_assembler_values_cdo_add_t

typedef void() cs_matrix_assembler_values_cdo_add_t(void *matrix, cs_lnum_t row_id, cs_lnum_t stride, cs_lnum_t n_cols, const cs_real_t diag_val[], const cs_lnum_t col_idx[], const cs_real_t vals[])

Function pointer for addition to matrix coefficients using local row ids and column indexes in case of CDO schemes. Contrary to other add_values() function. Here values are structured in a CSR-like way. By this way one avoids to allocate specific arrays for this step.

Values whose associated row index is negative should be ignored; Values whose column index is -1 are assumed to be assigned to a separately stored diagonal. Other indexes should be valid.

Warning
The matrix pointer must point to valid data when the selection function is called, so the life cycle of the data pointed to should be at least as long as that of the assembler values structure.
Remarks
Note that we pass column indexes (not ids) here; as the caller is already assumed to have identified the index matching a given column id.
Parameters
[in,out]matrix_puntyped pointer to matrix description structure
[in]row_idlocal row id to deal with
[in]strideassociated data block size
[in]n_colsnumber of columns for the row to deal with
[in]diag_valpointer to the diagonal value(s)
[in]col_idxassociated local column indexes
[in]valspointer to values (size: n*stride*row_size)

◆ cs_matrix_assembler_values_end_t

typedef void() cs_matrix_assembler_values_end_t(void *matrix)

Function pointer to complete the final assembly of matrix coefficients.

Warning
The matrix pointer must point to valid data when the selection function is called, so the life cycle of the data pointed to should be at least as long as that of the assembler values structure.
Parameters
[in,out]matrixuntyped pointer to matrix description structure

◆ cs_matrix_assembler_values_init_t

typedef void() cs_matrix_assembler_values_init_t(void *matrix, const cs_lnum_t *db_size, const cs_lnum_t *eb_size)

Function pointer for initialization of matrix coefficients using local row ids and column indexes.

Warning
The matrix pointer must point to valid data when the selection function is called, so the life cycle of the data pointed to should be at least as long as that of the assembler values structure.
Parameters
[in,out]matrixuntyped pointer to matrix description structure
[in]dbsize optional diagonal block sizes
[in]ebsize optional extra-diagonal block sizes

◆ cs_matrix_assembler_values_t

typedef struct _cs_matrix_assembler_values_t cs_matrix_assembler_values_t

Structure used to set matrix coefficients

Function Documentation

◆ cs_matrix_assembler_add_g_ids()

void cs_matrix_assembler_add_g_ids ( cs_matrix_assembler_t ma,
cs_lnum_t  n,
const cs_gnum_t  g_row_id[],
const cs_gnum_t  g_col_id[] 
)

Add entries to a matrix assembler structure.

This function should be called by a single thread for a given assembler.

Parameters
[in,out]mapointer to matrix assembler structure
[in]nnumber of entries
[in]g_col_idglobal column ids associated with entries
[in]g_row_idglobal row ids associated with entries

◆ cs_matrix_assembler_compute()

void cs_matrix_assembler_compute ( cs_matrix_assembler_t ma)

Compute internal structures required by a matrix assembler.

The associated vector halo is also computed at this stage.

Parameters
[in,out]mapointer to matrix assembler structure

This function should be called by a single thread for a given assembler.

◆ cs_matrix_assembler_create()

cs_matrix_assembler_t* cs_matrix_assembler_create ( const cs_gnum_t  l_range[2],
bool  separate_diag 
)

Create a matrix assembler structure.

The associated matrix structure data will initially be empty, though the range of rows associated with the current rank must be defined immediately.

Parameters
[in]l_rangeglobal id range [min, max[ for local rank
[in]separate_diagif true, diagonal terms are handled separately
Returns
pointer to created matrix assembler structure

◆ cs_matrix_assembler_create_from_shared()

cs_matrix_assembler_t* cs_matrix_assembler_create_from_shared ( cs_lnum_t  n_rows,
bool  separate_diag,
const cs_lnum_t  row_idx[],
const cs_lnum_t  col_id[],
const cs_halo_t halo 
)

Create a matrix assembler structure based on a given connectivity and associated halo structure.

The assembler may not be later modified when built this way.

The connectivity arrays and halo will be shared by the caller, so their life cycle must be at least as long as the matrix assembler structure.

Parameters
[in]n_rowsnumber fo local rows
[in]separate_diagif true, diagonal terms are handled separately
[in]row_idxmatrix row index
[in]col_idmatrix column indexes
[in]haloassociated halo structure
Returns
pointer to created matrix assembler structure

◆ cs_matrix_assembler_destroy()

void cs_matrix_assembler_destroy ( cs_matrix_assembler_t **  ma)

Destroy a matrix assembler structure.

Parameters
[in,out]mapointer to matrix assembler structure pointer

◆ cs_matrix_assembler_get_col_ids()

const cs_lnum_t* cs_matrix_assembler_get_col_ids ( const cs_matrix_assembler_t ma)

Return a column ids associated with a matrix assembler.

These ids relative to all columns of successive rows, with columns ordered by local id, so local columns appear first, distant columns after. Depending on the separate_diag option used when creating the matrix assembler, the columns may include the diagonal or not. The matching index can be obtained using cs_matrix_assembler_get_row_index.

Warning
the returned index is valid only as long as the matrix assembly structure exists.
Parameters
[in]mapointer to matrix assembler structure
Returns
pointer to matrix structure row index

◆ cs_matrix_assembler_get_halo()

const cs_halo_t* cs_matrix_assembler_get_halo ( const cs_matrix_assembler_t ma)

Return a pointer to the halo structure associated with a matrix assembler.

Parameters
[in]mapointer to matrix assembler structure
Returns
pointer to halo structure

◆ cs_matrix_assembler_get_l_range()

const cs_gnum_t* cs_matrix_assembler_get_l_range ( const cs_matrix_assembler_t ma)

Return a pointer to local global row range associated with a matrix assembler.

Parameters
[in]mapointer to matrix assembler structure
Returns
pointer to local range

◆ cs_matrix_assembler_get_n_columns()

cs_lnum_t cs_matrix_assembler_get_n_columns ( const cs_matrix_assembler_t ma)

Return the number of columns associated with a matrix assembler.

Parameters
[in]mapointer to matrix assembler structure
Returns
number of columns associated with matrix assembler

◆ cs_matrix_assembler_get_n_rows()

cs_lnum_t cs_matrix_assembler_get_n_rows ( const cs_matrix_assembler_t ma)

Return the number of rows associated with a matrix assembler.

Parameters
[in]mapointer to matrix assembler structure
Returns
number of rows associated with matrix assembler

◆ cs_matrix_assembler_get_options()

int cs_matrix_assembler_get_options ( const cs_matrix_assembler_t ma)

Return the option flags for a given matrix assembler structure.

Flags are defined as a sum (bitwise or) of constants, described in cs_matrix_assembler_set_options.

Parameters
[in]mapointer to matrix assembler structure
Returns
option flags (sum of integer constants) used y this structure

◆ cs_matrix_assembler_get_rank_counts()

void cs_matrix_assembler_get_rank_counts ( const cs_matrix_assembler_t ma,
int  rc[4] 
)

Return info on the number of neighbor ranks a matrix assembler may communicate with.

Parameters
[in]mapointer to matrix assembler structure
[out]rcrank counts; the 4 values are:
  • 0 number of communicating ranks for vector update (halo)
  • 1 number of communicating ranks for matrix assembly
  • 2 maximum number of communicating ranks for halo construction (assumed ranks algorithm)
  • 3 maximum number of communicating ranks for matrix assembly determination (assumed ranks algorithm)

◆ cs_matrix_assembler_get_row_index()

const cs_lnum_t* cs_matrix_assembler_get_row_index ( const cs_matrix_assembler_t ma)

Return a row index associated with a matrix assembler.

This index is a CSR type index relative to all columns, including or excluding the diagonal depending on the separate_diag option used when creating the matrix assembler. The matching column ids can be obtained using cs_matrix_assembler_get_col_ids.

Warning
the returned index is valid only as long as the matrix assembly structure exists.
Parameters
[in]mapointer to matrix assembler structure
Returns
pointer to matrix structure row index

◆ cs_matrix_assembler_get_separate_diag()

bool cs_matrix_assembler_get_separate_diag ( const cs_matrix_assembler_t ma)

Indicate if the matrix assembler is based on a separate diagonal.

Parameters
[in]mapointer to matrix assembler structure
Returns
true if the associated structure has a separate diagonal, false otherwise

◆ cs_matrix_assembler_log_rank_counts()

void cs_matrix_assembler_log_rank_counts ( const cs_matrix_assembler_t ma,
cs_log_t  log_id,
const char *  name 
)

Log rank counts for a given matrix assembler.

Parameters
[in]mapointer to matrix assembler structure
[in]log_idlog type
[in]namename of this assembler

◆ cs_matrix_assembler_set_options()

void cs_matrix_assembler_set_options ( cs_matrix_assembler_t ma,
int  flags 
)

Set option flags for a given matrix assembler structure.

When used, this function should be called before defining entries (in case of future option additions) and in any case before computing the final structure.

Flags are defined as a sum (bitwise or) of constants, described below:

  • CS_MATRIX_DISTANT_ROW_USE_COL_IDX indicates that column indexes matching distant row data are computed and maintained, so the associated coefficient contributions can be added more efficiently.
  • CS_MATRIX_DISTANT_ROW_USE_COL_G_ID indicates that columns global ids matching distant row data are maintained directly, so no lookup to a global id description of matrix columns is needed; this option is useful only when using an external library allowing incremental setting or accumulation of coefficients using global column ids, such as with PETSc's MatSetValues. When building matrices locally first (which includes most cases, whether internal matrices, or using library conversion or import functions such as PETSc's MatCreateMPIAIJWithArrays) this is slightly less efficient, as column ids will need to be matched to each row's columns a second time for those (exchanged) coefficients.
  • CS_MATRIX_EXTERNAL_HALO indicates that we do not need to build an associated halo structure, as it will be built externally (i.e. by an external library such as PETSc, HYPRE, ...) using its own equivalent structures.
Parameters
[in,out]mapointer to matrix assembler structure
[in]flagssum of matrix assembler flag constants (bitwise or)

◆ cs_matrix_assembler_values_add()

void cs_matrix_assembler_values_add ( cs_matrix_assembler_values_t mav,
cs_lnum_t  n,
const cs_lnum_t  row_id[],
const cs_lnum_t  col_id[],
const cs_real_t  val[] 
)

Add values to a matrix assembler values structure using local row and column ids.

If the matching matrix coefficients use a block structure, the values passed to this function should use the same block size.

Note also that if the matrix has different diagonal and extradiagonal block sizes, separate calls to this function should be used for both types of coefficients; in addition, in this case, diagonal coefficients should only be provided by the owning rank (this also impacts how the associated matrix assembler structure is defined).

This function may be called by different threads, as long those threads do not add contributions to the same rows (assuming caution is taken in the case of external libraries so that their builder functions have tht same property).

Parameters
[in,out]mavpointer to matrix assembler values structure
[in]nnumber of entries
[in]col_idlocal column ids associated with entries
[in]row_idlocal row ids associated with entries
[in]valvalues associated with entries

◆ cs_matrix_assembler_values_add_g()

void cs_matrix_assembler_values_add_g ( cs_matrix_assembler_values_t mav,
cs_lnum_t  n,
const cs_gnum_t  g_row_id[],
const cs_gnum_t  g_col_id[],
const cs_real_t  val[] 
)

Add values to a matrix assembler values structure using global row and column ids.

If the matching matrix coefficients use a block structure, the values passed to this function should use the same block size.

Note also that if the matrix has different diagonal and extradiagonal block sizes, separate calls to this function should be used for both types of coefficients; in addition, in this case, diagonal coefficients should only be provided by the owning rank (this also impacts how the associated matrix assembler structure is defined).

This function may be called by different threads, as long those threads do not add contributions to the same rows (assuming caution is taken in the case of external libraries so that their builder functions have tht same property).

Parameters
[in,out]mavpointer to matrix assembler values structure
[in]nnumber of entries
[in]g_col_idglobal column ids associated with entries
[in]g_row_idglobal row ids associated with entries
[in]valvalues associated with entries

◆ cs_matrix_assembler_values_create()

cs_matrix_assembler_values_t* cs_matrix_assembler_values_create ( const cs_matrix_assembler_t ma,
bool  sep_diag,
const cs_lnum_t db_size,
const cs_lnum_t eb_size,
void *  matrix,
cs_matrix_assembler_values_init_t init,
cs_matrix_assembler_values_add_t add,
cs_matrix_assembler_values_add_g_t add_g,
cs_matrix_assembler_values_begin_t begin,
cs_matrix_assembler_values_end_t end 
)

Create and initialize a matrix assembler values structure.

The associated values will initially be set to zero.

Block sizes are defined by an optional array of 4 values: 0: useful block size, 1: vector block extents, 2: matrix line extents, 3: matrix line*column extents

This is a low-level function, which should be called by a simpler function (cs_matrix_assembler_values_init) which provides the necessary function pointers.

Warning
The matrix pointer must point to valid data when the selection function is called, so the life cycle of the data pointed to should be at least as long as that of the assembler values structure. In a similar manner, the life cycle of the associated matrix assembler must also be at least as long as that of the assembler values structure.
Parameters
[in]maassociated matrix assembly structure
[in]sep_diagtrue if diagonal terms are stored separately
[in]db_sizeoptional diagonal block sizes
[in]eb_sizeoptional extra-diagonal block sizes
[in,out]matrixuntyped pointer to matrix description structure
[in]initpointer to matrix coefficients initialization function
[in]addpointer to matrix coefficients addition from local ids function
[in]add_gpointer to matrix coefficients addition from global ids function
[in]beginpointer to matrix coefficients assembly start function (optional)
[in]endpointer to matrix coefficients assembly end function (optional)
Returns
pointer to initialized matrix assembler structure;

◆ cs_matrix_assembler_values_done()

void cs_matrix_assembler_values_done ( cs_matrix_assembler_values_t mav)

Start assembly of matrix values structure.

The call to this function is always optional, and indicates that assembly may begin. Calling it before cs_matrix_assembler_values_finalize may be useful when the underlying libraries can overlap communication (or other operations such as matrix trasformation) and computation.

Remarks
When values have been added to rows belonging to another rank, communication will occur here. Splitting this function could add another opportunity for overlap of computation and communication, but is not done as of 2016, as it would add complexity, with probably limited returns, as the effective asynchonous progress of MPI libraries is usually limited.
Parameters
[in,out]mavpointer to matrix assembler data structure

◆ cs_matrix_assembler_values_finalize()

void cs_matrix_assembler_values_finalize ( cs_matrix_assembler_values_t **  mav)

Finalize matrix assembler values structure.

When this function returns, the assembler values structure has been destroyed, and the associated matrix is fully assembled (i.e. ready to use).

Parameters
[in,out]mavpointer to matrix assembler values structure pointer