Internal OpenNL functions to manipulate sparse matrices. More...

#include "nl_private.h"

Classes
struct	NLMatrixStruct
	The base class for abstract matrices. More...

struct	NLCoeff
	Represents a coefficient in a sparse matrix. More...

struct	NLRowColumn
	Represents a row or a column of a sparse matrix. More...

struct	NLCRSMatrix
	A compact self-contained storage for sparse matrices. More...

struct	NLSparseMatrix

Macros
#define	NL_MATRIX_SPARSE_DYNAMIC 0x1001

#define	NL_MATRIX_CRS 0x1002

#define	NL_MATRIX_SUPERLU_EXT 0x1003

#define	NL_MATRIX_CHOLMOD_EXT 0x1004

#define	NL_MATRIX_FUNCTION 0x1005

#define	NL_MATRIX_OTHER 0x1006

Typedefs
typedef struct NLMatrixStruct *	NLMatrix

typedef void(*	NLDestroyMatrixFunc) (NLMatrix M)
	Function pointer type for matrix destructors.

typedef void(*	NLMultMatrixVectorFunc) (NLMatrix M, const double x, double y)
	Function pointer type for matrix x vector product.

typedef NLuint	NLuint_big
	Type for internal indices.

typedef void(*	NLMatrixFunc) (const double x, double y)
	Function pointer type for matrix-vector products.

Functions
NLAPI void NLAPIENTRY	nlDeleteMatrix (NLMatrix M)
	Deletes a matrix.

NLAPI void NLAPIENTRY	nlMultMatrixVector (NLMatrix M, const double x, double y)
	Computes a matrix x vector product.

NLAPI void NLAPIENTRY	nlCRSMatrixPatternSetRowLength (NLCRSMatrix *M, NLuint i, NLuint n)
	Specifies the number of non-zero entries in the row of a matrix that was constructed by nlCRSMatrixConstructPattern() or nlCRSMatrixConstructPatternSymmetric().

NLAPI void NLAPIENTRY	nlCRSMatrixPatternCompile (NLCRSMatrix *M)
	Intializes a NLCRSMatrix from the pattern (row lengths).

NLAPI void NLAPIENTRY	nlSparseMatrixAddMatrix (NLSparseMatrix *M, double mul, const NLMatrix N)
	Adds a matrix to another sparse matrix.

NLAPI void NLAPIENTRY	nlSparseMatrixAddRow (NLSparseMatrix *M)
	Adds a new empty row to a sparse matrix.

NLAPI void NLAPIENTRY	nlSparseMatrixAddColumn (NLSparseMatrix *M)
	Adds a new empty column to a sparse matrix.

NLAPI void NLAPIENTRY	nlSparseMatrixMAddRow (NLSparseMatrix *M, NLuint i1, double s, NLuint i2)
	Adds a row of a sparse matrix to another row. (row[i1] += s * row[i2]).

NLAPI void NLAPIENTRY	nlSparseMatrixScaleRow (NLSparseMatrix *M, NLuint i, double s)
	Scales a row of a sparse matrix. (row[i] *= s).

NLAPI void NLAPIENTRY	nlSparseMatrixZeroRow (NLSparseMatrix *M, NLuint i)
	Zeroes a row of a sparse matrix. (row[i] = 0).

NLAPI NLuint_big NLAPIENTRY	nlMatrixNNZ (NLMatrix M)
	Gets the number of non-zero entries in a matrix.

NLAPI NLMatrix NLAPIENTRY	nlMatrixFactorize (NLMatrix M, NLenum solver)
	Factorizes a matrix.

NLAPI NLMatrix NLAPIENTRY	nlMatrixNewFromFunction (NLuint m, NLuint n, NLMatrixFunc func)
	Creates a matrix implemented by a matrix-vector function.

NLAPI NLMatrixFunc NLAPIENTRY	nlMatrixGetFunction (NLMatrix M)
	Gets the function pointer that implements matrix x vector product.

NLAPI NLMatrix NLAPIENTRY	nlMatrixNewFromProduct (NLMatrix M, NLboolean product_owns_M, NLMatrix N, NLboolean product_owns_N)
	Creates a matrix that represents the product of two matrices.

Detailed Description

Internal OpenNL functions to manipulate sparse matrices.

Definition in file nl_matrix.h.

Macro Definition Documentation

◆ NL_MATRIX_CHOLMOD_EXT

#define NL_MATRIX_CHOLMOD_EXT 0x1004

Definition at line 73 of file nl_matrix.h.

◆ NL_MATRIX_CRS

#define NL_MATRIX_CRS 0x1002

Definition at line 71 of file nl_matrix.h.

◆ NL_MATRIX_FUNCTION

#define NL_MATRIX_FUNCTION 0x1005

Definition at line 74 of file nl_matrix.h.

◆ NL_MATRIX_OTHER

#define NL_MATRIX_OTHER 0x1006

Definition at line 75 of file nl_matrix.h.

◆ NL_MATRIX_SPARSE_DYNAMIC

#define NL_MATRIX_SPARSE_DYNAMIC 0x1001

Definition at line 70 of file nl_matrix.h.

◆ NL_MATRIX_SUPERLU_EXT

#define NL_MATRIX_SUPERLU_EXT 0x1003

Definition at line 72 of file nl_matrix.h.

Typedef Documentation

◆ NLDestroyMatrixFunc

typedef void(* NLDestroyMatrixFunc) (NLMatrix M)

Function pointer type for matrix destructors.

Definition at line 63 of file nl_matrix.h.

◆ NLMatrix

typedef struct NLMatrixStruct* NLMatrix

Definition at line 58 of file nl_matrix.h.

◆ NLMatrixFunc

typedef void(* NLMatrixFunc) (const double *x, double *y)

Function pointer type for matrix-vector products.

Definition at line 807 of file nl_matrix.h.

◆ NLMultMatrixVectorFunc

typedef void(* NLMultMatrixVectorFunc) (NLMatrix M, const double *x, double *y)

Function pointer type for matrix x vector product.

Definition at line 68 of file nl_matrix.h.

◆ NLuint_big

typedef NLuint NLuint_big

Type for internal indices.

Matrix dimension is limited to 4G x 4G. Number of non-zero entries is limited to 2^32 (4G) in standard mode, and to 2^64 in GARGANTUA mode.

Definition at line 268 of file nl_matrix.h.

Function Documentation

◆ nlCRSMatrixPatternCompile()

NLAPI void NLAPIENTRY nlCRSMatrixPatternCompile ( NLCRSMatrix * M )

Intializes a NLCRSMatrix from the pattern (row lengths).

Parameters

[in] M a pointer to the NLCRSMatrix to be compiled.

◆ nlDeleteMatrix()

NLAPI void NLAPIENTRY nlDeleteMatrix ( NLMatrix M )

Deletes a matrix.

If M is NULL, then the function does nothing

Parameters

[in] M the matrix to be deleted

◆ nlMatrixFactorize()

NLAPI NLMatrix NLAPIENTRY nlMatrixFactorize	(	NLMatrix	M,
		NLenum	solver
	)

Factorizes a matrix.

The corresponding extension needs to be successfully initialized before calling this function.

Parameters

[in]	M	the input matrix
[in]	solver	a direct solver, i.e., one of: NL_SUPERLU_EXT NL_PERM_SUPERLU_EXT NL_SYMMETRIC_SUPERLU_EXT NL_CHOLMOD_EXT

Returns: a factorization of M, or NULL if M is singular. When calling nlMultMatrixVector() with the result, it solves a linear system (the result may be thought of as the inverse of M).

◆ nlMatrixGetFunction()

NLAPI NLMatrixFunc NLAPIENTRY nlMatrixGetFunction ( NLMatrix M )

Gets the function pointer that implements matrix x vector product.

Parameters

[in] M the matrix

Returns: the pointer to the matrix x vector product function if M was created by nlMatrixNewFromFunction(), NULL otherwise

◆ nlMatrixNewFromFunction()

NLAPI NLMatrix NLAPIENTRY nlMatrixNewFromFunction	(	NLuint	m,
		NLuint	n,
		NLMatrixFunc	func
	)

Creates a matrix implemented by a matrix-vector function.

Parameters

[in]	m	number of rows
[in]	n	number of columns
[in]	func	a function that implements the matrix x vector product, and that takes the right hand side and the left hand side as arguments.

◆ nlMatrixNewFromProduct()

NLAPI NLMatrix NLAPIENTRY nlMatrixNewFromProduct	(	NLMatrix	M,
		NLboolean	product_owns_M,
		NLMatrix	N,
		NLboolean	product_owns_N
	)

Creates a matrix that represents the product of two matrices.

Parameters

[in]	M	an m times k matrix.
[in]	product_owns_M	if set to NL_TRUE, then caller is no longer responsible for the memory associated to M, and M will be destroyed when the product will be destroyed. If it is set to NL_FALSE, then the product only keeps a reference to M, and the caller remains responsible for deallocating M.
[in]	N	a k times n matrix.
[in]	product_owns_N	if set to NL_TRUE, then caller is no longer responsible for the memory associated to N, and N will be destroyed when the product will be destroyed. If it is set to NL_FALSE, then the product only keeps a reference to N, and the caller remains responsible for deallocating N.

Returns: an NLMatrix that represents the product between M and N

◆ nlMatrixNNZ()

NLAPI NLuint_big NLAPIENTRY nlMatrixNNZ ( NLMatrix M )

Gets the number of non-zero entries in a matrix.

If the matrix is sparse, it gets the number of non-zero entries, else it returns m*n

Returns: the number of non-zero entries in M

◆ nlMultMatrixVector()

NLAPI void NLAPIENTRY nlMultMatrixVector	(	NLMatrix	M,
		const double *	x,
		double *	y
	)

Computes a matrix x vector product.

Parameters

[in]	M	the matrix
[in]	x	the vector to be multiplied by the matrix
[out]	y	the result

◆ nlSparseMatrixAddColumn()

NLAPI void NLAPIENTRY nlSparseMatrixAddColumn ( NLSparseMatrix * M )

Adds a new empty column to a sparse matrix.

Parameters

[in,out] M a pointer to the sparse matrix.

◆ nlSparseMatrixAddMatrix()

NLAPI void NLAPIENTRY nlSparseMatrixAddMatrix	(	NLSparseMatrix *	M,
		double	mul,
		const NLMatrix	N
	)

Adds a matrix to another sparse matrix.

Does M += mul * N. If N has symmetric storage, then M needs also to have symmetric storage.

Parameters

[in,out]	M	a pointer to an NLSparseMatrix
[in]	mul	a multiplicative factor that pre-multiply all coefficients of `N`
[in]	N	a matrix. Needs to be either a NLSparseMatrix or a NLCRSMatrix.

◆ nlSparseMatrixAddRow()

NLAPI void NLAPIENTRY nlSparseMatrixAddRow ( NLSparseMatrix * M )

Adds a new empty row to a sparse matrix.

Parameters

[in,out] M a pointer to the sparse matrix.

◆ nlSparseMatrixMAddRow()

NLAPI void NLAPIENTRY nlSparseMatrixMAddRow	(	NLSparseMatrix *	M,
		NLuint	i1,
		double	s,
		NLuint	i2
	)

Adds a row of a sparse matrix to another row. (row[i1] += s * row[i2]).

Parameters

[in,out]	M	a pointer to a sparse matrix.
[in]	i1	index of the row.
[in]	s	scaling factor.
[in]	i2	index of the other row.

◆ nlSparseMatrixScaleRow()

NLAPI void NLAPIENTRY nlSparseMatrixScaleRow	(	NLSparseMatrix *	M,
		NLuint	i,
		double	s
	)

Scales a row of a sparse matrix. (row[i] *= s).

Parameters

[in,out]	M	a pointer to a sparse matrix.
[in]	i	index of the row.
[in]	s	scaling factor.

Precondition: M has row storage and has not column storage.

◆ nlSparseMatrixZeroRow()

NLAPI void NLAPIENTRY nlSparseMatrixZeroRow	(	NLSparseMatrix *	M,
		NLuint	i
	)

Zeroes a row of a sparse matrix. (row[i] = 0).

Parameters

[in,out]	M	a pointer to a sparse matrix.
[in]	i	index of the row.

Precondition: M has row storage and has not column storage.

Classes

Macros

Typedefs

Functions

Detailed Description

Macro Definition Documentation

◆ NL_MATRIX_CHOLMOD_EXT

◆ NL_MATRIX_CRS

◆ NL_MATRIX_FUNCTION

◆ NL_MATRIX_OTHER

◆ NL_MATRIX_SPARSE_DYNAMIC

◆ NL_MATRIX_SUPERLU_EXT

Typedef Documentation

◆ NLDestroyMatrixFunc

◆ NLMatrix

◆ NLMatrixFunc

◆ NLMultMatrixVectorFunc

◆ NLuint_big

Function Documentation

◆ nlCRSMatrixPatternCompile()

◆ nlDeleteMatrix()

◆ nlMatrixFactorize()

◆ nlMatrixGetFunction()

◆ nlMatrixNewFromFunction()

◆ nlMatrixNewFromProduct()

◆ nlMatrixNNZ()

◆ nlMultMatrixVector()

◆ nlSparseMatrixAddColumn()

◆ nlSparseMatrixAddMatrix()

◆ nlSparseMatrixAddRow()

◆ nlSparseMatrixMAddRow()

◆ nlSparseMatrixScaleRow()

◆ nlSparseMatrixZeroRow()