MatSetValuesBlocked#

Inserts or adds a block of values into a matrix.

Synopsis#

#include "petscmat.h" 
PetscErrorCode MatSetValuesBlocked(Mat mat, PetscInt m, const PetscInt idxm[], PetscInt n, const PetscInt idxn[], const PetscScalar v[], InsertMode addv)

Not Collective

Input Parameters#

mat - the matrix
v - a logically two-dimensional array of values
m - the number of block rows
idxm - the global block indices
n - the number of block columns
idxn - the global block indices
addv - either ADD_VALUES to add values to any existing entries, or INSERT_VALUES replaces existing entries with new values

Notes#

If you create the matrix yourself (that is not with a call to DMCreateMatrix()) then you MUST call MatXXXXSetPreallocation() or MatSetUp() before using this routine.

The m and n count the NUMBER of blocks in the row direction and column direction, NOT the total number of rows/columns; for example, if the block size is 2 and you are passing in values for rows 2,3,4,5 then m would be 2 (not 4). The values in idxm would be 1 2; that is the first index for each block divided by the block size.

You must call MatSetBlockSize() when constructing this matrix (before preallocating it).

By default the values, v, are row-oriented, so the layout of v is the same as for MatSetValues(). See MatSetOption() for other options.

Calls to MatSetValuesBlocked() with the INSERT_VALUES and ADD_VALUES options cannot be mixed without intervening calls to the assembly routines.

MatSetValuesBlocked() uses 0-based row and column numbers in Fortran as well as in C.

Negative indices may be passed in idxm and idxn, these rows and columns are simply ignored. This allows easily inserting element stiffness matrices with homogeneous Dirichlet boundary conditions that you don’t want represented in the matrix.

Each time an entry is set within a sparse matrix via MatSetValues(), internal searching must be done to determine where to place the data in the matrix storage space. By instead inserting blocks of entries via MatSetValuesBlocked(), the overhead of matrix assembly is reduced.

Example#

   Suppose m=n=2 and block size(bs) = 2 The array is

   1  2  | 3  4
   5  6  | 7  8
   - - - | - - -
   9  10 | 11 12
   13 14 | 15 16

   v[] should be passed in like
   v[] = [1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16]

  If you are not using row-oriented storage of v (that is you called MatSetOption(mat,MAT_ROW_ORIENTED,PETSC_FALSE)) then
   v[] = [1,5,9,13,2,6,10,14,3,7,11,15,4,8,12,16]