NumericsMatrix (functions)


siconos.numerics.NM_add(double alpha, NumericsMatrix *A, double beta, NumericsMatrix *B) → NumericsMatrix *[source]

Add two matrices with coefficients C = alpha*A + beta*B.

Parameters:
  • alpha – the first coefficient
  • A – the first matrix
  • beta – the second coefficient
  • B – the second matrix
Returns:

C a new NumericsMatrix


siconos.numerics.NM_add_to_diag3(NumericsMatrix *M, double alpha) → None[source]

Add a constant term to the diagonal elements, when the block of the SBM are 3x3.

Parameters:
  • M – the matrix
  • alpha – the term to add

siconos.numerics.NM_assert(int type, NumericsMatrix *M) → None[source]

assert that a NumericsMatrix has the right structure given its type

Parameters:
  • type – expected type
  • M – the matrix to check

siconos.numerics.NM_check(NumericsMatrix * A) → int[source]

Check the matrix (the sparse format for now)

Parameters:A – the matrix to check
Returns:0 if the matrix storage is fine, 1 if not

siconos.numerics.NM_clearCSC(NumericsMatrix *A) → None[source]

Clear compressed column storage, if it is existent.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_clearCSCTranspose(NumericsMatrix *A) → None[source]

Clear transposed compressed column storage, if it is existent.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_clearCSR(NumericsMatrix *A) → None[source]

Clear compressed row storage, if it is existent.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_clearDense(NumericsMatrix *A) → None[source]

Clear dense storage, if it is existent.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_clearSparse(NumericsMatrix *A) → None[source]

Clear sparse data, if it is existent.

The linear solver parameters are also cleared.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_clearSparseBlock(NumericsMatrix *A) → None[source]

Clear sparse block storage, if it is existent.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_clearSparseStorage(NumericsMatrix *A) → None[source]

Clear triplet, csc, csc transposed storage, if they are existent.

Linear solver parameters are preserved.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_clearTriplet(NumericsMatrix *A) → None[source]

Clear triplet storage, if it is existent.

Parameters:A – a Numericsmatrix

siconos.numerics.NM_compare(NumericsMatrix *A, NumericsMatrix *B, double tol) → bool[source]

compare to NumericsMatrix up to a given tolerance

Parameters:
  • A – the NumericsMatrix
  • B – the NumericsMatrix
  • tol – the tolerance

siconos.numerics.NM_copy(NumericsMatrix * A, NumericsMatrix *B) → None[source]

Copy a NumericsMatrix inside another NumericsMatrix (deep).

Reallocations are performed if B cannot hold a copy of A

Parameters:
  • A – a NumericsMatrix
  • B – a NumericsMatrix

siconos.numerics.NM_copy_diag_block3(NumericsMatrix *M, int block_row_nb, array_like (np.float64, 1D)*Block) → None[source]

get a 3x3 diagonal block of a NumericsMatrix.

No allocation is done.

Parameters:
  • M – a NumericsMatrix
  • block_row_nb – the number of the block row
  • Block – the target. In all cases (dense, sbm, and sparse) (*Block) must be allocated by caller. A copy is always performed

siconos.numerics.NM_copy_to_sparse(NumericsMatrix * A, NumericsMatrix *B) → None[source]

Copy a NumericsMatrix to s sparse one.

Allocation or reallocation are performed on B

Warning: It is assumed that B has been properly initialized: its storageType
must be set to NM_SPARSE.
Parameters:
  • A – a NumericsMatrix
  • B – a NumericsMatrix

siconos.numerics.NM_create(int storageType, int size0, int size1) → NumericsMatrix *[source]

create a NumericsMatrix and allocate the memory according to the matrix type

Parameters:
  • storageType – the type of storage
  • size0 – number of rows
  • size1 – number of columns
Returns:

a pointer to a NumericsMatrix


siconos.numerics.NM_create_from_data(int storageType, int size0, int size1, None *data) → NumericsMatrix *[source]

create a NumericsMatrix and possibly set the data

Parameters:
  • storageType – the type of storage
  • size0 – number of rows
  • size1 – number of columns
  • data – pointer to the matrix data. If NULL, all matrixX fields are set to NULL
Returns:

a pointer to a NumericsMatrix


siconos.numerics.NM_create_from_file(FILE *file) → NumericsMatrix *[source]

siconos.numerics.NM_create_from_filename(char *filename) → NumericsMatrix *[source]

siconos.numerics.NM_csc(NumericsMatrix *A) → CSparseMatrix *[source]

Creation, if needed, of compress column storage of a NumericsMatrix.

Parameters:A – a NumericsMatrix with sparse block storage initialized
Returns:the compressed column CSparseMatrix created in A.

siconos.numerics.NM_csc_alloc(NumericsMatrix *A, CS_INT nzmax) → None[source]

Allocate a csc matrix in A.

Parameters:
  • A – the matrix
  • nzmax – number of non-zero elements

siconos.numerics.NM_csc_empty_alloc(NumericsMatrix *A, CS_INT nzmax) → None[source]

Allocate a csc matrix in A and set the vector of column pointers to 0 such that the matrix is empty.

Parameters:
  • A – the matrix
  • nzmax – number of non-zero elements

siconos.numerics.NM_csc_trans(NumericsMatrix *A) → CSparseMatrix *[source]

Creation, if needed, of the transposed compress column storage from compress column storage.

Parameters:A – a NumericsMatrix with sparse block storage.
Returns:the transposed compressed column matrix created in A.

siconos.numerics.NM_csr(NumericsMatrix *A) → CSparseMatrix *[source]

Creation, if needed, of compress row storage of a NumericsMatrix.

Warning: This rely on the MKL

Parameters:A – a NumericsMatrix with sparse block storage initialized
Returns:the compressed row CSparseMatrix created in A.

siconos.numerics.NM_csr_alloc(NumericsMatrix *A, CS_INT nzmax) → None[source]

Allocate a csr matrix in A.

Parameters:
  • A – the matrix
  • nzmax – number of non-zero elements

siconos.numerics.NM_dWork(NumericsMatrix *A, int size) -> array_like (np.float64, 1D)[source]

Double workspace initialization, if needed.

Parameters:
  • A – pointer on a NumericsMatrix.
  • size – the size of needed space.
Returns:

pointer on A->dWork allocated space of with the right size


siconos.numerics.NM_dense_display(array_like (np.float64, 1D)m, int nRow, int nCol, int lDim) → None[source]

Screen display of the matrix content stored as a double * array in Fortran style.

Parameters:
  • m – the matrix to be displayed
  • nRow – the number of rows
  • nCol – the number of columns
  • lDim – the leading dimension of M

siconos.numerics.NM_dense_display_matlab(array_like (np.float64, 1D)m, int nRow, int nCol, int lDim) → None[source]

Screen display of the matrix content stored as a double * array in Fortran style.

Parameters:
  • m – the matrix to be displayed
  • nRow – the number of rows
  • nCol – the number of columns
  • lDim – the leading dimension of M

siconos.numerics.NM_dense_to_sparse(NumericsMatrix * A, NumericsMatrix *B) → None[source]

matrix conversion display

matrix and vector display


siconos.numerics.NM_display(NumericsMatrix * M) → None[source]

Screen display of the matrix content.

Parameters:M – the matrix to be displayed

siconos.numerics.NM_display_row_by_row(NumericsMatrix * m) → None[source]

Screen display raw by raw of the matrix content.

Parameters:m – the matrix to be displayed

siconos.numerics.NM_duplicate(NumericsMatrix *mat) → NumericsMatrix *[source]

create a NumericsMatrix similar to the another one.

The structure is the same

Parameters:mat – the model matrix
Returns:a pointer to a NumericsMatrix

siconos.numerics.NM_equal(NumericsMatrix *A, NumericsMatrix *B) → bool[source]

compare to NumericsMatrix up to machine accuracy (DBL_EPSILON)

Parameters:
  • A – the NumericsMatrix
  • B – the NumericsMatrix

siconos.numerics.NM_extract_diag_block(NumericsMatrix *M, int block_row_nb, size_t start_row, int size, array_like (np.float64, 1D)*Block) → None[source]

get the (square) diagonal block of a NumericsMatrix.

No allocation is done.

Parameters:
  • M – a NumericsMatrix
  • block_row_nb – the number of the block Row. Useful only in sparse case
  • start_row – the starting row. Useful only in dense case.
  • size – of the diag block. Only useful in dense case.
  • Block – the target. In the dense and sparse case (*Block) must be allocated by caller. In case of SBM case **Bout contains the resulting block (from the SBM).

siconos.numerics.NM_extract_diag_block3(NumericsMatrix *M, int block_row_nb, array_like (np.float64, 1D)*Block) → None[source]

get a 3x3 diagonal block of a NumericsMatrix.

No allocation is done.

Parameters:
  • M – a NumericsMatrix
  • block_row_nb – the number of the block row
  • Block – the target. In the dense and sparse case (*Block) must be allocated by caller. In case of SBM case **Bout contains the resulting block (from the SBM).

siconos.numerics.NM_eye(int size) → NumericsMatrix *[source]

siconos.numerics.NM_fill(NumericsMatrix *M, int storageType, int size0, int size1, None *data) → None[source]

fill an existing NumericsMatrix struct

Parameters:
  • M – the struct to fill
  • storageType – the type of storage
  • size0 – number of rows
  • size1 – number of columns
  • data – pointer to the matrix data. If NULL, all matrixX fields are set to NULL

siconos.numerics.NM_free(NumericsMatrix *m) → None[source]

Free memory for a NumericsMatrix.

Warning: call this function only if you are sure that memory has been allocated for the structure in Numerics. This function is assumed that the memory is “owned” by this structure. Note that this function does not free m.

Parameters:m – the matrix to be deleted.

siconos.numerics.NM_gemm(double alpha, NumericsMatrix *A, NumericsMatrix *B, double beta, NumericsMatrix *C) → None[source]

Matrix matrix multiplication : C = alpha A B + beta C.

Parameters:
  • alpha – scalar
  • A – a NumericsMatrix
  • B – a NumericsMatrix
  • beta – scalar
  • C – a NumericsMatrix

siconos.numerics.NM_gemv(double alpha, NumericsMatrix *A, array_like (np.float64, 1D)x, double beta, array_like (np.float64, 1D)y) → None[source]

Matrix vector multiplication : y = alpha A x + beta y.

Parameters:
  • alpha – scalar
  • A – a NumericsMatrix
  • x – pointer on a dense vector of size A->size1
  • beta – scalar
  • y – pointer on a dense vector of size A->size1

siconos.numerics.NM_gesv(NumericsMatrix *A, array_like (np.float64, 1D)b, bool preserve) → int[source]

Direct computation of the solution of a real system of linear equations: A x = b.

Parameters:
  • A – a NumericsMatrix. On a dense factorisation A.iWork is initialized.
  • b – pointer on a dense vector of size A->size1
  • preserve – preserve the original matrix data. Only useful in the dense case, where the LU factorization is done in-place.
Returns:

0 if successful, else the error is specific to the backend solver used


siconos.numerics.NM_gesv_expert(NumericsMatrix *A, array_like (np.float64, 1D)b, keep) → int[source]

Direct computation of the solution of a real system of linear equations: A x = b.

The factorized matrix A is kept for future solve. If A is already factorized, the solve the linear system from it

Warning: this is not enable for all the solvers, your mileage may vary

Parameters:
  • A – a NumericsMatrix. On a dense factorisation A.iWork is initialized.
  • b – pointer on a dense vector of size A->size1
  • keep – if set to NM_KEEP_FACTORS, keep all the info related to the factorization to allow for future solves. If A is already factorized, just solve the linear system. If set to NM_PRESERVE, preserve the original matrix (just used in the dense case). if NM_NONE, discard everything.
Returns:

0 if successful, else the error is specific to the backend solver used


siconos.numerics.NM_gesv_expert_multiple_rhs(NumericsMatrix *A, array_like (np.float64, 1D)b, int n_rhs, keep) → int[source]

siconos.numerics.NM_get_value(NumericsMatrix *M, int i, int j) → double[source]

get the value of a NumericsMatrix.

Parameters:
  • M – the NumericsMatrix
  • i – row index
  • j – column index
Returns:

the value to be inserted.


siconos.numerics.NM_iWork(NumericsMatrix *A, size_t size, size_t sizeof_elt) → None *[source]

Integer work vector initialization, if needed.

Parameters:
  • A – pointer on a NumericsMatrix.
  • size – number of element to allocate
  • sizeof_elt – of an element in bytes (result of sizeof for instance)
Returns:

pointer on A->iWork allocated space of with the right size


siconos.numerics.NM_internalData(NumericsMatrix *A) → NumericsMatrixInternalData *[source]

Get Matrix internal data with initialization if needed.

Parameters:A – a NumericsMatrix.
Returns:a pointer on internal data.

siconos.numerics.NM_internalData_copy(NumericsMatrix * A, NumericsMatrix *B) → None[source]

Copy the internalData structure.

Parameters:M – the matrix to modify

siconos.numerics.NM_internalData_new(NumericsMatrix *M) → None[source]

Allocate the internalData structure (but not its content!)

Parameters:M – the matrix to modify

siconos.numerics.NM_inv(NumericsMatrix *A, NumericsMatrix *Ainv) → int[source]

Computation of the inverse of a NumericsMatrix A usinf NM_gesv_expert.

Parameters:
  • A – a NumericsMatrix.
  • Ainv – the matrix inverse.

siconos.numerics.NM_inverse_diagonal_block_matrix_in_place(NumericsMatrix *A) → int[source]

siconos.numerics.NM_is_symmetric(NumericsMatrix *A) → int[source]

siconos.numerics.NM_multiply(NumericsMatrix *A, NumericsMatrix *B) → NumericsMatrix *[source]

Matrix matrix multiplication : C = A B.

Parameters:
  • A – a NumericsMatrix
  • B – a NumericsMatrix
  • C – a NumericsMatrix

siconos.numerics.NM_new(None) → NumericsMatrix *[source]

Constructors and destructors.

Creation of an empty NumericsMatrix.

Returns:a pointer to allocated space

siconos.numerics.NM_new_SBM(int size0, int size1, SparseBlockStructuredMatrix *m1) → NumericsMatrix *[source]

new NumericsMatrix with sparse storage from minimal set of data

Parameters:
  • size0 – number of rows
  • size1 – number of columns
  • m1 – the SparseBlockStructuredMatrix
Returns:

a pointer to a NumericsMatrix


siconos.numerics.NM_new_from_file(FILE *file) → NumericsMatrix *[source]

Create from file a NumericsMatrix with memory allocation.

Parameters:file – the corresponding file
Returns:0 if the matrix

siconos.numerics.NM_new_from_filename(char *filename) → NumericsMatrix *[source]

siconos.numerics.NM_nnz(NumericsMatrix *M) → size_t[source]

return the number of non-zero element.

For a dense matrix, it is the product of the dimensions (e.g. an upper bound). For a sparse matrix, it is the true number

Parameters:M – the matrix
Returns:the number (or an upper bound) of non-zero elements in the matrix

siconos.numerics.NM_norm_1(NumericsMatrix * A) → double[source]

Compute the 1-norm of a sparse matrix = max (sum (abs (A))), largest column sum of a matrix (the sparse format for now)

Parameters:A – the matrix
Returns:the norm

siconos.numerics.NM_norm_inf(NumericsMatrix * A) → double[source]

Compute the inf-norm of a sparse matrix = max (sum (abs (A^T))), largest row sum of a matrix (the sparse format for now)

Parameters:A – the matrix
Returns:the norm

siconos.numerics.NM_null(NumericsMatrix *A) → None[source]

set NumericsMatrix fields to NULL

Parameters:A – a matrix

siconos.numerics.NM_prod_mv_3x3(int sizeX, int sizeY, NumericsMatrix *A, array_like (np.float64, 1D) x, array_like (np.float64, 1D)y) → None[source]

Matrix - vector product.

Matrix - vector product y = A*x + y

Parameters:
  • sizeX – dim of the vector x
  • sizeY – dim of the vector y
  • A – the matrix to be multiplied
  • x – the vector to be multiplied
  • y – the resulting vector

siconos.numerics.NM_read_in_file(NumericsMatrix * M, FILE *file) → None[source]

Read in file of the matrix content without performing memory allocation.

Parameters:
  • M – the matrix to be read
  • file – the corresponding file

siconos.numerics.NM_read_in_file_scilab(NumericsMatrix * M, FILE *file) → None[source]

Read in file for scilab of the matrix content.

Parameters:
  • M – the matrix to be read
  • file – the corresponding file

siconos.numerics.NM_read_in_filename(NumericsMatrix * M, char *filename) → None[source]

Read in file of the matrix content.

Parameters:
  • M – the matrix to be read
  • filename – the corresponding name of the file

siconos.numerics.NM_row_prod(int sizeX, int sizeY, int currentRowNumber, NumericsMatrix * A, array_like (np.float64, 1D) x, array_like (np.float64, 1D)y, int init) → None[source]

Row of a Matrix - vector product y = rowA*x or y += rowA*x, rowA being a submatrix of A (sizeY rows and sizeX columns)

Parameters:
  • sizeX – dim of the vector x
  • sizeY – dim of the vector y
  • currentRowNumber – position of the first row of rowA in A (warning: real row if A is a double*, block-row if A is a SparseBlockStructuredMatrix)
  • A – the matrix to be multiplied
  • x – the vector to be multiplied
  • y – the resulting vector
  • init – = 0 for y += Ax, =1 for y = Ax

siconos.numerics.NM_row_prod_no_diag(size_t sizeX, size_t sizeY, int block_start, size_t row_start, NumericsMatrix *A, array_like (np.float64, 1D)x, array_like (np.float64, 1D)y, array_like (np.float64, 1D)xsave, bool init) → None[source]

Row of a Matrix - vector product y = rowA*x or y += rowA*x, rowA being a submatrix of A (sizeY rows and sizeX columns)

Parameters:
  • sizeX – dim of the vector x
  • sizeY – dim of the vector y
  • block_start – block number (only used for SBM)
  • row_start – position of the first row of A (unused if A is SBM)
  • A – the matrix to be multiplied
  • x – the vector to be multiplied
  • y – the resulting vector
  • xsave – storage for saving the part of x set to 0
  • init – if True y = Ax, else y += Ax

siconos.numerics.NM_row_prod_no_diag1x1(size_t sizeX, int block_start, size_t row_start, NumericsMatrix *A, array_like (np.float64, 1D)x, array_like (np.float64, 1D)y, bool init) → None[source]

siconos.numerics.NM_row_prod_no_diag3(size_t sizeX, int block_start, size_t row_start, NumericsMatrix *A, array_like (np.float64, 1D)x, array_like (np.float64, 1D)y, bool init) → None[source]

Row of a Matrix - vector product y = rowA*x or y += rowA*x, rowA being a submatrix of A (3 rows and sizeX columns)

Parameters:
  • sizeX – dim of the vector x
  • block_start – block number (only used for SBM)
  • row_start – position of the first row of A (unused if A is SBM)
  • A – the matrix to be multiplied
  • x – the vector to be multiplied
  • y – the resulting vector
  • init – if True y = Ax, else y += Ax

siconos.numerics.NM_setSparseSolver(NumericsMatrix *A, solver_id) → None[source]

Set the linear solver.

Parameters:
  • A – the matrix
  • solver_id – the solver

siconos.numerics.NM_symmetry_discrepancy(NumericsMatrix *A) → double[source]

siconos.numerics.NM_tgemv(double alpha, NumericsMatrix *A, array_like (np.float64, 1D)x, double beta, array_like (np.float64, 1D)y) → None[source]

Transposed matrix multiplication : y += alpha transpose(A) x + y.

Parameters:
  • alpha – scalar
  • A – a NumericsMatrix
  • x – pointer on a dense vector of size A->size1
  • beta – scalar
  • y – pointer on a dense vector of size A->size1

siconos.numerics.NM_to_dense(NumericsMatrix * A, NumericsMatrix *B) → int[source]

siconos.numerics.NM_transpose(NumericsMatrix *A) → NumericsMatrix *[source]

new NumericsMatrix equal to the transpose of a given matrix

Parameters:A
Returns:a pointer to a NumericsMatrix

siconos.numerics.NM_triplet(NumericsMatrix *A) → CSparseMatrix *[source]

Creation, if needed, of triplet storage from sparse block storage.

Parameters:A – a NumericsMatrix initialized with sparsed block storage.
Returns:the triplet sparse Matrix created in A.

siconos.numerics.NM_triplet_alloc(NumericsMatrix *A, CS_INT nzmax) → None[source]

Allocate a triplet matrix in A.

Parameters:
  • A – the matrix
  • nzmax – maximum number of non-zero elements

siconos.numerics.NM_update_size(NumericsMatrix *A) → None[source]

update the size of the matrix based on the matrix data

Parameters:A – the matrix which size is updated

siconos.numerics.NM_vector_display(array_like (np.float64, 1D)m, int nRow) → None[source]

Screen display of the vector content stored as a double * array.

Parameters:
  • m – the vector to be displayed
  • nRow – the number of rows

siconos.numerics.NM_write_in_file(NumericsMatrix * M, FILE *file) → None[source]

PrintInFile of the matrix content.

Parameters:
  • M – the matrix to be printed
  • file – filename the corresponding file

siconos.numerics.NM_write_in_file_python(NumericsMatrix * M, FILE *file) → None[source]

NM_write_in_file_python of the matrix content.

Parameters:
  • M – the matrix to be printed
  • file – the corresponding file

siconos.numerics.NM_write_in_file_scilab(NumericsMatrix * M, FILE *file) → None[source]

NM_write_in_file_scilab of the matrix content.

Parameters:
  • M – the matrix to be printed
  • file – the corresponding file

siconos.numerics.NM_write_in_filename(NumericsMatrix * M, char *filename) → None[source]

matrix I/O

PrintInFile of the matrix content

Parameters:
  • M – the matrix to be printed
  • filename – the corresponding name of the file

siconos.numerics.NM_zentry(NumericsMatrix *M, int i, int j, double val) → None[source]

setters and getters

insert an non zero entry into a NumericsMatrix. for storageType = NM_SPARSE, a conversion to triplet is done for performing the entry in the matrix. This method is expensice in terms of memory management. For a lot of entries, use preferably a triplet matrix.

Parameters:
  • M – the NumericsMatrix
  • i – row index
  • j – column index
  • val – the value to be inserted.

siconos.numerics.numericsSparseMatrix(NumericsMatrix *A) → NumericsSparseMatrix *[source]

Creation, if needed, of sparse matrix storage.

Parameters:A – a NumericsMatrix
Returns:a pointer on the sparse matrix storage