cs_matrix.h File Reference

#include "cs_defs.h"
#include "cs_halo.h"
#include "cs_numbering.h"
#include "cs_halo_perio.h"
#include "cs_matrix_assembler.h"

Include dependency graph for cs_matrix.h:

Go to the source code of this file.

Data Structures
struct	cs_matrix_row_info_t

Typedefs
typedef struct _cs_matrix_structure_t	cs_matrix_structure_t
typedef struct _cs_matrix_t	cs_matrix_t
typedef struct _cs_matrix_variant_t	cs_matrix_variant_t

Enumerations
enum	cs_matrix_type_t {   CS_MATRIX_NATIVE, CS_MATRIX_CSR, CS_MATRIX_CSR_SYM, CS_MATRIX_MSR,   CS_MATRIX_N_TYPES }
enum	cs_matrix_fill_type_t {   CS_MATRIX_SCALAR, CS_MATRIX_SCALAR_SYM, CS_MATRIX_BLOCK_D, CS_MATRIX_BLOCK_D_66,   CS_MATRIX_BLOCK_D_SYM, CS_MATRIX_BLOCK, CS_MATRIX_N_FILL_TYPES }

Functions
cs_matrix_structure_t *	cs_matrix_structure_create (cs_matrix_type_t type, bool have_diag, cs_lnum_t n_rows, cs_lnum_t n_cols_ext, cs_lnum_t n_edges, const cs_lnum_2_t *edges, const cs_halo_t *halo, const cs_numbering_t *numbering)
	Create a matrix structure. More...
cs_matrix_structure_t *	cs_matrix_structure_create_msr (cs_matrix_type_t type, bool transfer, bool have_diag, cs_lnum_t n_rows, cs_lnum_t n_cols_ext, cs_lnum_t **row_index, cs_lnum_t **col_id, const cs_halo_t *halo, const cs_numbering_t *numbering)
	Create a matrix structure based on a MSR connectivity definition. More...
cs_matrix_structure_t *	cs_matrix_structure_create_msr_shared (bool have_diag, bool direct_assmbly, cs_lnum_t n_rows, cs_lnum_t n_cols_ext, const cs_lnum_t *row_index, const cs_lnum_t *col_id, const cs_halo_t *halo, const cs_numbering_t *numbering)
	Create an MSR matrix structure sharing an existing connectivity definition as well as an optional edge-based definition. More...
cs_matrix_structure_t *	cs_matrix_structure_create_from_assembler (cs_matrix_type_t type, cs_matrix_assembler_t *ma)
	Create a matrix structure using a matrix assembler. More...
void	cs_matrix_structure_destroy (cs_matrix_structure_t **ms)
	Destroy a matrix structure. More...
cs_matrix_t *	cs_matrix_create (const cs_matrix_structure_t *ms)
	Create a matrix container using a given structure. More...
cs_matrix_t *	cs_matrix_create_by_variant (const cs_matrix_structure_t *ms, const cs_matrix_variant_t *mv)
	Create a matrix container using a given variant. More...
cs_matrix_t *	cs_matrix_create_from_assembler (cs_matrix_type_t type, cs_matrix_assembler_t *ma)
	Create a matrix directly from assembler. More...
cs_matrix_t *	cs_matrix_create_by_copy (cs_matrix_t *src)
	Create a matrix container by copying another. More...
void	cs_matrix_destroy (cs_matrix_t **matrix)
cs_matrix_type_t	cs_matrix_get_type (const cs_matrix_t *matrix)
	Return matrix type. More...
cs_lnum_t	cs_matrix_get_n_columns (const cs_matrix_t *matrix)
	Return number of columns in a matrix. More...
cs_lnum_t	cs_matrix_get_n_rows (const cs_matrix_t *matrix)
	Return number of rows in matrix. More...
cs_lnum_t	cs_matrix_get_n_entries (const cs_matrix_t *matrix)
	Return number of entries in matrix. More...
const cs_lnum_t *	cs_matrix_get_diag_block_size (const cs_matrix_t *matrix)
	Return matrix diagonal block sizes. More...
const cs_lnum_t *	cs_matrix_get_extra_diag_block_size (const cs_matrix_t *matrix)
	Return matrix extra-diagonal block sizes. More...
const cs_halo_t *	cs_matrix_get_halo (const cs_matrix_t *matrix)
	Return pointer to matrix halo structure. More...
cs_matrix_fill_type_t	cs_matrix_get_fill_type (bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size)
	Get matrix fill type, depending on block sizes. More...
void	cs_matrix_set_coefficients (cs_matrix_t *matrix, bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size, const cs_lnum_t n_edges, const cs_lnum_2_t edges[], const cs_real_t *da, const cs_real_t *xa)
	Set matrix coefficients defined relative to a "native" edge graph, sharing arrays with the caller when possible. More...
void	cs_matrix_copy_coefficients (cs_matrix_t *matrix, bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size, const cs_lnum_t n_edges, const cs_lnum_2_t edges[], const cs_real_t *da, const cs_real_t *xa)
	Set matrix coefficients, copying values to private arrays. More...
void	cs_matrix_transfer_coefficients_msr (cs_matrix_t *matrix, bool symmetric, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size, const cs_lnum_t row_index[], const cs_lnum_t col_id[], cs_real_t **d_val, cs_real_t **x_val)
	Set matrix coefficients in an MSR format, transfering the property of those arrays to the matrix. More...
cs_matrix_assembler_values_t *	cs_matrix_assembler_values_init (cs_matrix_t *matrix, const cs_lnum_t *diag_block_size, const cs_lnum_t *extra_diag_block_size)
	Create and initialize a CSR matrix assembler values structure. More...
void	cs_matrix_release_coefficients (cs_matrix_t *matrix)
	Release shared matrix coefficients. More...
void	cs_matrix_copy_diagonal (const cs_matrix_t *matrix, cs_real_t *restrict da)
	Copy matrix diagonal values. More...
bool	cs_matrix_is_symmetric (const cs_matrix_t *matrix)
	Query matrix coefficients symmetry. More...
bool	cs_matrix_is_mapped_from_native (const cs_matrix_t *matrix)
	Indicate whether coefficients were mapped from native face-based arrays. More...
const cs_real_t *	cs_matrix_get_diagonal (const cs_matrix_t *matrix)
	Get matrix diagonal values. More...
const cs_real_t *	cs_matrix_get_extra_diagonal (const cs_matrix_t *matrix)
	Get pointer to matrix extra-diagonal values in "native" format. More...
void	cs_matrix_row_init (cs_matrix_row_info_t *r)
	Initialize row info for a given matrix. More...
void	cs_matrix_row_finalize (cs_matrix_row_info_t *r)
	Finalize row info for a given matrix. More...
void	cs_matrix_get_row (const cs_matrix_t *matrix, const cs_lnum_t row_id, cs_matrix_row_info_t *r)
	Get row values for a given matrix. More...
void	cs_matrix_get_native_arrays (const cs_matrix_t *matrix, bool *symmetric, cs_lnum_t *n_edges, const cs_lnum_2_t **edges, const cs_real_t **d_val, const cs_real_t **x_val)
	Get arrays describing a matrix in native format. More...
void	cs_matrix_get_csr_arrays (const cs_matrix_t *matrix, const cs_lnum_t **row_index, const cs_lnum_t **col_id, const cs_real_t **val)
	Get arrays describing a matrix in CSR format. More...
void	cs_matrix_get_msr_arrays (const cs_matrix_t *matrix, const cs_lnum_t **row_index, const cs_lnum_t **col_id, const cs_real_t **d_val, const cs_real_t **x_val)
	Get arrays describing a matrix in MSR format. More...
void	cs_matrix_vector_multiply (cs_halo_rotation_t rotation_mode, const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
	Matrix.vector product y = A.x. More...
void	cs_matrix_vector_multiply_nosync (const cs_matrix_t *matrix, const cs_real_t *x, cs_real_t *restrict y)
	Matrix.vector product y = A.x with no prior halo update of x. More...
void	cs_matrix_exdiag_vector_multiply (cs_halo_rotation_t rotation_mode, const cs_matrix_t *matrix, cs_real_t *restrict x, cs_real_t *restrict y)
	Matrix.vector product y = (A-D).x. More...
void	cs_matrix_pre_vector_multiply_sync (cs_halo_rotation_t rotation_mode, const cs_matrix_t *matrix, cs_real_t *x)
void	cs_matrix_csr_assembler_values_init (void *matrix_p, const cs_lnum_t db_size[4], const cs_lnum_t eb_size[4])
	Function for initialization of CSR matrix coefficients using local row ids and column indexes. More...
void	cs_matrix_csr_assembler_values_add (void *matrix_p, 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 CSR matrix coefficients using local row ids and column indexes. More...
void	cs_matrix_msr_assembler_values_init (void *matrix_p, const cs_lnum_t db_size[4], const cs_lnum_t eb_size[4])
	Function for initialization of MSR matrix coefficients using local row ids and column indexes. More...
void	cs_matrix_msr_assembler_values_add (void *matrix_p, 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 MSR matrix coefficients using local row ids and column indexes. More...
void	cs_matrix_variant_build_list (int n_fill_types, cs_matrix_fill_type_t fill_types[], bool type_filter[], const cs_numbering_t *numbering, int *n_variants, cs_matrix_variant_t **m_variant)
	Build list of variants for tuning or testing. More...
cs_matrix_variant_t *	cs_matrix_variant_create (cs_matrix_type_t type, const cs_numbering_t *numbering)
	Build matrix variant. More...
void	cs_matrix_variant_destroy (cs_matrix_variant_t **mv)
	Destroy a matrix variant structure. More...
void	cs_matrix_variant_set_func (cs_matrix_variant_t *mv, const cs_numbering_t *numbering, cs_matrix_fill_type_t fill_type, int ed_flag, const char *func_name)
	Select the sparse matrix-vector product function to be used by a matrix variant for a given fill type. More...
void	cs_matrix_variant_merge (cs_matrix_variant_t *mv, const cs_matrix_variant_t *mv_merge, cs_matrix_fill_type_t fill_type)
	Merge a functions to a matrix variant from another variant sharing the same structure. More...
cs_matrix_type_t	cs_matrix_variant_type (const cs_matrix_variant_t *mv)
	Get the type associated with a matrix variant. More...
void	cs_matrix_variant_test (cs_lnum_t n_rows, cs_lnum_t n_cols_ext, cs_lnum_t n_edges, const cs_lnum_2_t *edges, const cs_halo_t *halo, const cs_numbering_t *numbering)
	Test local matrix.vector product operations. More...

Variables
const char *	cs_matrix_type_name []
const char *	cs_matrix_type_fullname []
const char *	cs_matrix_fill_type_name []

Typedef Documentation

cs_matrix_structure_t

typedef struct _cs_matrix_structure_t cs_matrix_structure_t

cs_matrix_t

typedef struct _cs_matrix_t cs_matrix_t

cs_matrix_variant_t

typedef struct _cs_matrix_variant_t cs_matrix_variant_t

Enumeration Type Documentation

cs_matrix_fill_type_t

enum cs_matrix_fill_type_t

Enumerator
CS_MATRIX_SCALAR
CS_MATRIX_SCALAR_SYM
CS_MATRIX_BLOCK_D
CS_MATRIX_BLOCK_D_66
CS_MATRIX_BLOCK_D_SYM
CS_MATRIX_BLOCK
CS_MATRIX_N_FILL_TYPES

cs_matrix_type_t

enum cs_matrix_type_t

Enumerator
CS_MATRIX_NATIVE
CS_MATRIX_CSR
CS_MATRIX_CSR_SYM
CS_MATRIX_MSR
CS_MATRIX_N_TYPES

Function Documentation

cs_matrix_assembler_values_init()

cs_matrix_assembler_values_t* cs_matrix_assembler_values_init	(	cs_matrix_t *	matrix,
		const cs_lnum_t *	diag_block_size,
		const cs_lnum_t *	extra_diag_block_size
	)

Create and initialize a CSR matrix assembler values structure.

The associated matrix's structure must have been created using cs_matrix_structure_create_from_assembler.

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

Parameters

[in,out]	matrix	pointer to matrix structure
[in]	diag_block_size	block sizes for diagonal, or NULL
[in]	extra_diag_block_size	block sizes for extra diagonal, or NULL

Returns

pointer to initialized matrix assembler values structure;

cs_matrix_copy_coefficients()

void cs_matrix_copy_coefficients	(	cs_matrix_t *	matrix,
		bool	symmetric,
		const cs_lnum_t *	diag_block_size,
		const cs_lnum_t *	extra_diag_block_size,
		const cs_lnum_t	n_edges,
		const cs_lnum_2_t	edges[],
		const cs_real_t *	da,
		const cs_real_t *	xa
	)

Set matrix coefficients, copying values to private arrays.

With private arrays, the matrix becomes independant from the arrays passed as arguments.

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

Parameters

[in,out]	matrix	pointer to matrix structure
[in]	symmetric	indicates if matrix coefficients are symmetric
[in]	diag_block_size	block sizes for diagonal, or NULL
[in]	extra_diag_block_size	block sizes for extra diagonal, or NULL
[in]	n_edges	local number of graph edges
[in]	edges	edges (row <-> column) connectivity
[in]	da	diagonal values (NULL if zero)
[in]	xa	extradiagonal values (NULL if zero) casts as: xa[n_edges] if symmetric, xa[n_edges][2] if non symmetric

cs_matrix_copy_diagonal()

void cs_matrix_copy_diagonal	(	const cs_matrix_t *	matrix,
		cs_real_t *restrict	da
	)

Copy matrix diagonal values.

In case of matrixes with block diagonal coefficients, only the true diagonal values are copied.

Parameters

[in]	matrix	pointer to matrix structure
[out]	da	diagonal (pre-allocated, size: n_rows*block_size)

cs_matrix_create()

cs_matrix_t* cs_matrix_create

(

const cs_matrix_structure_t *

ms

)

Create a matrix container using a given structure.

Note that the matrix container maps to the assigned structure, so it must be destroyed before that structure.

Parameters

[in]

ms

associated matrix structure

Returns

pointer to created matrix structure;

cs_matrix_create_by_copy()

cs_matrix_t* cs_matrix_create_by_copy

(

cs_matrix_t *

src

)

Create a matrix container by copying another.

Note that the matrix containers share the same assigned structure, so they must be both destroyed before that structure.

If assigned, coefficients are not copied.

Parameters

[in]

src

reference matrix structure

Returns

pointer to created matrix structure;

cs_matrix_create_by_variant()

cs_matrix_t* cs_matrix_create_by_variant	(	const cs_matrix_structure_t *	ms,
		const cs_matrix_variant_t *	mv
	)

Create a matrix container using a given variant.

If the matrix variant is incompatible with the structure, it is ignored, and defaults for that structure are used instead.

Parameters

[in]	ms	associated matrix structure
[in]	mv	associated matrix variant

Returns

pointer to created matrix structure;

cs_matrix_create_from_assembler()

cs_matrix_t* cs_matrix_create_from_assembler	(	cs_matrix_type_t	type,
		cs_matrix_assembler_t *	ma
	)

Create a matrix directly from assembler.

Only CSR and MSR formats are handled.

Parameters

[in]	type	type of matrix considered
[in]	ma	pointer to matrix assembler structure

Returns

a pointer to a created matrix structure

cs_matrix_csr_assembler_values_add()

void cs_matrix_csr_assembler_values_add	(	void *	matrix_p,
		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 CSR 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 shoudl 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_p	untyped pointer to matrix description structure
[in]	n	number of values to add
[in]	stride	associated data block size
[in]	row_id	associated local row ids
[in]	col_idx	associated local column indexes
[in]	val	pointer to values (size: n*stride)

cs_matrix_csr_assembler_values_init()

void cs_matrix_csr_assembler_values_init	(	void *	matrix_p,
		const cs_lnum_t	db_size[4],
		const cs_lnum_t	eb_size[4]
	)

Function for initialization of CSR 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]	matrix_p	untyped pointer to matrix description structure
[in]	db	size optional diagonal block sizes
[in]	eb	size optional extra-diagonal block sizes

cs_matrix_destroy()

void cs_matrix_destroy

(

cs_matrix_t **

matrix

)

cs_matrix_exdiag_vector_multiply()

void cs_matrix_exdiag_vector_multiply	(	cs_halo_rotation_t	rotation_mode,
		const cs_matrix_t *	matrix,
		cs_real_t *restrict	x,
		cs_real_t *restrict	y
	)

Matrix.vector product y = (A-D).x.

This function includes a halo update of x prior to multiplication by A.

Parameters

[in]	rotation_mode	halo update option for rotational periodicity
[in]	matrix	pointer to matrix structure
[in,out]	x	multipliying vector values (ghost values updated)
[out]	y	resulting vector

cs_matrix_get_csr_arrays()

void cs_matrix_get_csr_arrays	(	const cs_matrix_t *	matrix,
		const cs_lnum_t **	row_index,
		const cs_lnum_t **	col_id,
		const cs_real_t **	val
	)

Get arrays describing a matrix in CSR format.

This function only works for an CSR matrix (i.e. there is no automatic conversion from another matrix type).

Matrix block sizes can be obtained by cs_matrix_get_diag_block_size() and cs_matrix_get_extra_diag_block_size().

Parameters

[in]	matrix	pointer to matrix structure
[out]	row_index	CSR row index
[out]	col_id	CSR column id
[out]	val	values

cs_matrix_get_diag_block_size()

const cs_lnum_t* cs_matrix_get_diag_block_size

(

const cs_matrix_t *

matrix

)

Return matrix diagonal block sizes.

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

Parameters

[in]

matrix

pointer to matrix structure

Returns

pointer to block sizes

cs_matrix_get_diagonal()

const cs_real_t* cs_matrix_get_diagonal

(

const cs_matrix_t *

matrix

)

Get matrix diagonal values.

In case of matrixes with block diagonal coefficients, a pointer to the complete block diagonal is returned.

Parameters

[in]

matrix

pointer to matrix structure

Returns

pointer to matrix diagonal array

cs_matrix_get_extra_diag_block_size()

const cs_lnum_t* cs_matrix_get_extra_diag_block_size

(

const cs_matrix_t *

matrix

)

Return matrix extra-diagonal block sizes.

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

Parameters

[in]

matrix

pointer to matrix structure

Returns

pointer to block sizes

cs_matrix_get_extra_diagonal()

const cs_real_t* cs_matrix_get_extra_diagonal

(

const cs_matrix_t *

matrix

)

Get pointer to matrix extra-diagonal values in "native" format.

Deprecated:

This function only functions if the coefficients were mapped from native coefficients using cs_matrix_set_coefficients(), in which case the pointer returned is the same as the one passed to that function.

It is used in the current multgrid code, but should be removed as soon as the dependency to the native format is removed.

Parameters

[in]

matrix

pointer to matrix structure

Returns

pointer to matrix diagonal array

cs_matrix_get_fill_type()

cs_matrix_fill_type_t cs_matrix_get_fill_type	(	bool	symmetric,
		const cs_lnum_t *	diag_block_size,
		const cs_lnum_t *	extra_diag_block_size
	)

Get matrix fill type, depending on block sizes.

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

Parameters

[in]	symmetric	indicates if matrix coefficients are symmetric
[in]	diag_block_size	block sizes for diagonal, or NULL
[in]	extra_diag_block_size	block sizes for extra diagonal, or NULL

Returns

matrix fill type

cs_matrix_get_halo()

const cs_halo_t* cs_matrix_get_halo

(

const cs_matrix_t *

matrix

)

Return pointer to matrix halo structure.

Parameters

[in]

matrix

pointer to matrix structure

Returns

pointer to halo strucuture

cs_matrix_get_msr_arrays()

void cs_matrix_get_msr_arrays	(	const cs_matrix_t *	matrix,
		const cs_lnum_t **	row_index,
		const cs_lnum_t **	col_id,
		const cs_real_t **	d_val,
		const cs_real_t **	x_val
	)

Get arrays describing a matrix in MSR format.

This function only works for an MSR matrix (i.e. there is no automatic conversion from another matrix type).

Matrix block sizes can be obtained by cs_matrix_get_diag_block_size() and cs_matrix_get_extra_diag_block_size().

Parameters

[in]	matrix	pointer to matrix structure
[out]	row_index	MSR row index
[out]	col_id	MSR column id
[out]	d_val	diagonal values
[out]	x_val	extra-diagonal values

cs_matrix_get_n_columns()

cs_lnum_t cs_matrix_get_n_columns

(

const cs_matrix_t *

matrix

)

Return number of columns in a matrix.

Parameters

[in]

matrix

pointer to matrix structure

cs_matrix_get_n_entries()

cs_lnum_t cs_matrix_get_n_entries

(

const cs_matrix_t *

matrix

)

Return number of entries in matrix.

When the block size is > 1, the number reported is the number of entry blocks, not individual entries.

Parameters

[in]

matrix

pointer to matrix structure

cs_matrix_get_n_rows()

cs_lnum_t cs_matrix_get_n_rows

(

const cs_matrix_t *

matrix

)

Return number of rows in matrix.

Parameters

[in]

matrix

pointer to matrix structure

cs_matrix_get_native_arrays()

void cs_matrix_get_native_arrays	(	const cs_matrix_t *	matrix,
		bool *	symmetric,
		cs_lnum_t *	n_edges,
		const cs_lnum_2_t **	edges,
		const cs_real_t **	d_val,
		const cs_real_t **	x_val
	)

Get arrays describing a matrix in native format.

This function works for matrix in native format.

Matrix block sizes can be obtained by cs_matrix_get_diag_block_size() and cs_matrix_get_extra_diag_block_size().

Parameters

[in]	matrix	pointer to matrix structure
[out]	symmetric	true if symmetric
[out]	n_edges	number of associated faces
[out]	edges	edges (symmetric row <-> column) connectivity
[out]	d_val	diagonal values
[out]	x_val	extra-diagonal values

cs_matrix_get_row()

void cs_matrix_get_row	(	const cs_matrix_t *	matrix,
		const cs_lnum_t	row_id,
		cs_matrix_row_info_t *	r
	)

Get row values for a given matrix.

This function may not work for all matrix types.

In the case of blocked matrixes, the true (non-blocked) values are returned.

The row information structure must have been previously initialized using cs_matrix_row_init, and should be finalized using using cs_matrix_row_finalize, so as to free buffers it may have built for certain matrix formats.

Parameters

[in]	matrix	pointer to matrix structure
[in]	row_id	id of row to query
[in,out]	r	row info structure

cs_matrix_get_type()

cs_matrix_type_t cs_matrix_get_type

(

const cs_matrix_t *

matrix

)

Return matrix type.

Parameters

[in]

matrix

pointer to matrix structure

cs_matrix_is_mapped_from_native()

bool cs_matrix_is_mapped_from_native

(

const cs_matrix_t *

matrix

)

Indicate whether coefficients were mapped from native face-based arrays.

It is used in the current multgrid code, but should be removed as soon as the dependency to the native format is removed.

Parameters

[in]

matrix

pointer to matrix structure

Returns

true if coefficients were mapped from native face-based arrays, false otherwise

cs_matrix_is_symmetric()

bool cs_matrix_is_symmetric

(

const cs_matrix_t *

matrix

)

Query matrix coefficients symmetry.

Parameters

[in]

matrix

pointer to matrix structure

Returns

true if coefficients are symmetric, false otherwise

cs_matrix_msr_assembler_values_add()

void cs_matrix_msr_assembler_values_add	(	void *	matrix_p,
		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 MSR 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 shoudl 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_p	untyped pointer to matrix description structure
[in]	n	number of values to add
[in]	stride	associated data block size
[in]	row_id	associated local row ids
[in]	col_idx	associated local column indexes
[in]	val	pointer to values (size: n*stride)

cs_matrix_msr_assembler_values_init()

void cs_matrix_msr_assembler_values_init	(	void *	matrix_p,
		const cs_lnum_t	db_size[4],
		const cs_lnum_t	eb_size[4]
	)

Function for initialization of MSR 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]	matrix_p	untyped pointer to matrix description structure
[in]	db	size optional diagonal block sizes
[in]	eb	size optional extra-diagonal block sizes

cs_matrix_pre_vector_multiply_sync()

void cs_matrix_pre_vector_multiply_sync	(	cs_halo_rotation_t	rotation_mode,
		const cs_matrix_t *	matrix,
		cs_real_t *	x
	)

cs_matrix_release_coefficients()

void cs_matrix_release_coefficients

(

cs_matrix_t *

matrix

)

Release shared matrix coefficients.

Pointers to mapped coefficients are set to NULL, while coefficient copies owned by the matrix are not modified.

This simply ensures the matrix does not maintain pointers to nonexistant data.

Parameters

[in,out]

matrix

pointer to matrix structure

cs_matrix_row_finalize()

void cs_matrix_row_finalize

(

cs_matrix_row_info_t *

r

)

Finalize row info for a given matrix.

Parameters

[in,out]

r

row info structure

cs_matrix_row_init()

void cs_matrix_row_init

(

cs_matrix_row_info_t *

r

)

Initialize row info for a given matrix.

Parameters

[out]

r

row info structure

cs_matrix_set_coefficients()

void cs_matrix_set_coefficients	(	cs_matrix_t *	matrix,
		bool	symmetric,
		const cs_lnum_t *	diag_block_size,
		const cs_lnum_t *	extra_diag_block_size,
		const cs_lnum_t	n_edges,
		const cs_lnum_2_t	edges[],
		const cs_real_t *	da,
		const cs_real_t *	xa
	)

Set matrix coefficients defined relative to a "native" edge graph, sharing arrays with the caller when possible.

With shared arrays, the matrix becomes unusable if the arrays passed as arguments are not be modified (its coefficients should be unset first to mark this).

Depending on current options and initialization, values will be copied or simply mapped.

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

Parameters

[in,out]	matrix	pointer to matrix structure
[in]	symmetric	indicates if matrix coefficients are symmetric
[in]	diag_block_size	block sizes for diagonal, or NULL
[in]	extra_diag_block_size	block sizes for extra diagonal, or NULL
[in]	n_edges	local number of graph edges
[in]	edges	edges (row <-> column) connectivity
[in]	da	diagonal values (NULL if zero)
[in]	xa	extradiagonal values (NULL if zero) casts as: xa[n_edges] if symmetric, xa[n_edges][2] if non symmetric

cs_matrix_structure_create()

cs_matrix_structure_t* cs_matrix_structure_create	(	cs_matrix_type_t	type,
		bool	have_diag,
		cs_lnum_t	n_rows,
		cs_lnum_t	n_cols_ext,
		cs_lnum_t	n_edges,
		const cs_lnum_2_t *	edges,
		const cs_halo_t *	halo,
		const cs_numbering_t *	numbering
	)

Create a matrix structure.

Note that the structure created usually maps to the given existing cell global number, face -> cell connectivity arrays, and cell halo structure, so it must be destroyed before they are freed (usually along with the code's main face -> cell structure).

Note that the resulting matrix structure will contain either a full or an empty main diagonal, and that the extra-diagonal structure is always symmetric (though the coefficients my not be, and we may choose a matrix format that does not exploit this symmetry). If the edges connectivity argument is NULL, the matrix will be purely diagonal.

Parameters

[in]	type	type of matrix considered
[in]	have_diag	indicates if the diagonal structure contains nonzeroes
[in]	n_rows	local number of rows
[in]	n_cols_ext	number of local + ghost columns
[in]	n_edges	local number of (undirected) graph edges
[in]	edges	edges (symmetric row <-> column) connectivity
[in]	halo	halo structure associated with cells, or NULL
[in]	numbering	vectorization or thread-related numbering info, or NULL

Returns

pointer to created matrix structure;

cs_matrix_structure_create_from_assembler()

cs_matrix_structure_t* cs_matrix_structure_create_from_assembler	(	cs_matrix_type_t	type,
		cs_matrix_assembler_t *	ma
	)

Create a matrix structure using a matrix assembler.

Only CSR and MSR formats are handled.

Parameters

[in]	type	type of matrix considered
[in]	ma	pointer to matrix assembler structure

Returns

a pointer to a created matrix structure

cs_matrix_structure_create_msr()

cs_matrix_structure_t* cs_matrix_structure_create_msr	(	cs_matrix_type_t	type,
		bool	transfer,
		bool	have_diag,
		cs_lnum_t	n_rows,
		cs_lnum_t	n_cols_ext,
		cs_lnum_t **	row_index,
		cs_lnum_t **	col_id,
		const cs_halo_t *	halo,
		const cs_numbering_t *	numbering
	)

Create a matrix structure based on a MSR connectivity definition.

Only CSR and MSR formats are handled.

col_id is sorted row by row during the creation of this structure.

In case the property of the row index and col_id arrays are transferred to the structure, the arrays pointers passed as arguments are set to NULL, to help ensure the caller does not use the original arrays directly after this call.

Parameters

[in]	type	type of matrix considered
[in]	transfer	transfer property of row_index and col_id if true, map them otherwise
[in]	have_diag	indicates if the structure includes the diagonal (should be the same for all rows)
[in]	n_rows	local number of rows
[in]	n_cols_ext	local number of columns + ghosts
[in]	row_index	pointer to index on rows
[in,out]	col_id	pointer to array of colum ids related to the row index
[in]	halo	halo structure for synchronization, or NULL
[in]	numbering	vectorization or thread-related numbering info, or NULL

Returns

a pointer to a created matrix structure

cs_matrix_structure_create_msr_shared()

cs_matrix_structure_t* cs_matrix_structure_create_msr_shared	(	bool	have_diag,
		bool	direct_assembly,
		cs_lnum_t	n_rows,
		cs_lnum_t	n_cols_ext,
		const cs_lnum_t *	row_index,
		const cs_lnum_t *	col_id,
		const cs_halo_t *	halo,
		const cs_numbering_t *	numbering
	)

Create an MSR matrix structure sharing an existing connectivity definition as well as an optional edge-based definition.

Note that as the structure created maps to the given existing cell global number, face -> cell connectivity arrays, and cell halo structure, it must be destroyed before they are freed (usually along with the code's main face -> cell structure).

Parameters

[in]	have_diag	indicates if the structure includes the diagonal (should be the same for all rows)
[in]	direct_assembly	true if each value corresponds to a unique face
[in]	n_rows	local number of rows
[in]	n_cols_ext	local number of columns + ghosts
[in]	row_index	index on rows
[in]	col_id	array of colum ids related to the row index
[in]	halo	halo structure for synchronization, or NULL
[in]	numbering	vectorization or thread-related numbering info, or NULL

Returns

a pointer to a created CDO matrix structure

cs_matrix_structure_destroy()

void cs_matrix_structure_destroy

(

cs_matrix_structure_t **

ms

)

Destroy a matrix structure.

Parameters

[in,out]

ms

pointer to matrix structure pointer

cs_matrix_transfer_coefficients_msr()

void cs_matrix_transfer_coefficients_msr	(	cs_matrix_t *	matrix,
		bool	symmetric,
		const cs_lnum_t *	diag_block_size,
		const cs_lnum_t *	extra_diag_block_size,
		const cs_lnum_t	row_index[],
		const cs_lnum_t	col_id[],
		cs_real_t **	d_val,
		cs_real_t **	x_val
	)

Set matrix coefficients in an MSR format, transfering the property of those arrays to the matrix.

If the matrix is also in MSR format, this avoids an extra copy. If it is in a different format, values are copied to the structure, and the original arrays freed. In any case, the arrays pointers passed as arguments are set to NULL, to help ensure the caller does not use the original arrays directly after this call.

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

Parameters

[in,out]	matrix	pointer to matrix structure
[in]	symmetric	indicates if matrix coefficients are symmetric
[in]	diag_block_size	block sizes for diagonal, or NULL
[in]	extra_diag_block_size	block sizes for extra diagonal, or NULL
[in]	row_index	MSR row index (0 to n-1)
[in]	col_id	MSR column id (0 to n-1)
[in,out]	d_val	diagonal values (NULL if zero)
[in,out]	x_val	extradiagonal values (NULL if zero)

cs_matrix_variant_build_list()

void cs_matrix_variant_build_list	(	int	n_fill_types,
		cs_matrix_fill_type_t	fill_types[],
		bool	type_filter[],
		const cs_numbering_t *	numbering,
		int *	n_variants,
		cs_matrix_variant_t **	m_variant
	)

Build list of variants for tuning or testing.

Parameters

[in]	n_fill_types	number of fill types tuned for
[in]	fill_types	array of fill types tuned for
[in]	type_filter	true for matrix types tuned for, false for others
[in]	numbering	vectorization or thread-related numbering info, or NULL
[out]	n_variants	number of variants
[out]	m_variant	array of matrix variants

cs_matrix_variant_create()

cs_matrix_variant_t* cs_matrix_variant_create	(	cs_matrix_type_t	type,
		const cs_numbering_t *	numbering
	)

Build matrix variant.

The variant will initially use default matrix-vector functions, which can be later modified using cs_matrix_variant_set_func().

Parameters

[in]	type	type of matrix considered
[in]	numbering	vectorization or thread-related numbering info, or NULL

cs_matrix_variant_destroy()

void cs_matrix_variant_destroy

(

cs_matrix_variant_t **

mv

)

Destroy a matrix variant structure.

Parameters

[in,out]

mv

pointer to matrix variant pointer

cs_matrix_variant_merge()

void cs_matrix_variant_merge	(	cs_matrix_variant_t *	mv,
		const cs_matrix_variant_t *	mv_merge,
		cs_matrix_fill_type_t	fill_type
	)

Merge a functions to a matrix variant from another variant sharing the same structure.

Functions from the structure to merge for the selected fill type are assigned to the main variant.

This can be useful when tuning has been done separately for different fill types, and the resulting selected structure is identical.

Parameters

[in,out]	mv	pointer to matrix variant
[in]	mv_merge	pointer to matrix variant to merge
[in]	fill_type	matrix fill type to merge from

cs_matrix_variant_set_func()

void cs_matrix_variant_set_func	(	cs_matrix_variant_t *	mv,
		const cs_numbering_t *	numbering,
		cs_matrix_fill_type_t	fill_type,
		int	ed_flag,
		const char *	func_name
	)

Select the sparse matrix-vector product function to be used by a matrix variant for a given fill type.

Currently, possible variant functions are:

CS_MATRIX_NATIVE (all fill types) standard fixed (for CS_MATRIX_??_BLOCK_D or CS_MATRIX_??_BLOCK_D_SYM) omp (for OpenMP with compatible numbering) vector (For vector machine with compatible numbering)

CS_MATRIX_CSR (for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM) standard mkl (with MKL)

CS_MATRIX_CSR_SYM (for CS_MATRIX_SCALAR_SYM) standard mkl (with MKL)

CS_MATRIX_MSR (all fill types except CS_MATRIX_33_BLOCK) standard fixed (for CS_MATRIX_??_BLOCK_D or CS_MATRIX_??_BLOCK_D_SYM) mkl (with MKL, for CS_MATRIX_SCALAR or CS_MATRIX_SCALAR_SYM)

parameters: mv <-> Pointer to matrix variant numbering <– mesh numbering info, or NULL fill type <– matrix fill type to merge from ed_flag <– 0: with diagonal only, 1 exclude only; 2; both func_name <– function type name

cs_matrix_variant_test()

void cs_matrix_variant_test	(	cs_lnum_t	n_rows,
		cs_lnum_t	n_cols_ext,
		cs_lnum_t	n_edges,
		const cs_lnum_2_t *	edges,
		const cs_halo_t *	halo,
		const cs_numbering_t *	numbering
	)

Test local matrix.vector product operations.

Parameters

[in]	n_rows	local number of rows
[in]	n_cols_ext	number of local + ghost columns
[in]	n_edges	local number of (undirected) graph edges
[in]	edges	edges (symmetric row <-> column) connectivity
[in]	halo	cell halo structure
[in]	numbering	vectorization or thread-related numbering info, or NULL

Returns

pointer to tuning results structure

cs_matrix_variant_type()

cs_matrix_type_t cs_matrix_variant_type

(

const cs_matrix_variant_t *

mv

)

Get the type associated with a matrix variant.

Parameters

[in]

mv

pointer to matrix variant structure

cs_matrix_vector_multiply()

void cs_matrix_vector_multiply	(	cs_halo_rotation_t	rotation_mode,
		const cs_matrix_t *	matrix,
		cs_real_t *restrict	x,
		cs_real_t *restrict	y
	)

Matrix.vector product y = A.x.

This function includes a halo update of x prior to multiplication by A.

Parameters

[in]	rotation_mode	halo update option for rotational periodicity
[in]	matrix	pointer to matrix structure
[in,out]	x	multipliying vector values (ghost values updated)
[out]	y	resulting vector

cs_matrix_vector_multiply_nosync()

void cs_matrix_vector_multiply_nosync	(	const cs_matrix_t *	matrix,
		const cs_real_t *	x,
		cs_real_t *restrict	y
	)

Matrix.vector product y = A.x with no prior halo update of x.

This function does not include a halo update of x prior to multiplication by A, so it should be called only when the halo of x is known to already be up to date (in which case we avoid the performance penalty of a redundant update by using this variant of the matrix.vector product).

Parameters

[in]	matrix	pointer to matrix structure
[in]	x	multipliying vector values
[out]	y	resulting vector

Variable Documentation

cs_matrix_fill_type_name

const char* cs_matrix_fill_type_name[]

cs_matrix_type_fullname

const char* cs_matrix_type_fullname[]

cs_matrix_type_name

const char* cs_matrix_type_name[]