MatSetValuesBlocked — PETSc 3.25.0 documentation

Skip to main content
`Ctrl`+`K`

# 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

- m - the number of block rows

- idxm - the global block indices

- n - the number of block columns

- idxn - the global block indices

- v - a one-dimensional array that contains the values implicitly stored as a two-dimensional array, by default in row-major order. See `MAT_ROW_ORIENTED` in `MatSetOption()` for how to use column-major order.

- 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 stored in row-major order. See `MAT_ROW_ORIENTED` in `MatSetOption()` for how to use column-major order.

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]

## Fortran Notes

If any of `idmx`, `idxn`, and `v` are scalars pass them using, for example,

      call MatSetValuesBlocked(mat, one, [idxm], one, [idxn], [v], INSERT_VALUES, ierr)

If `v` is a two-dimensional array use `reshape()` to pass it as a one dimensional array

## See Also

Matrices, `Mat`, `MatSetBlockSize()`, `MatSetOption()`, `MatAssemblyBegin()`, `MatAssemblyEnd()`, `MatSetValues()`, `MatSetValuesBlockedLocal()`

## Level

intermediate

## Location

src/mat/interface/matrix.c

## Examples

src/ts/tutorials/ex35.cxx
src/ts/tutorials/ex34.c
src/ts/tutorials/ex25.c
src/ts/tutorials/ex10.c
src/ksp/ksp/tutorials/ex74.c
src/ksp/ksp/tutorials/ex56.c
src/ts/tutorials/ex22.c
src/ksp/ksp/tutorials/ex71.c
src/ksp/ksp/tutorials/ex55.c
src/ts/tutorials/ex9.c

## Implementations

MatSetValuesBlocked_MPIBAIJ() in src/mat/impls/baij/mpi/mpibaij.c
MatSetValuesBlocked_SeqBAIJ() in src/mat/impls/baij/seq/baij.c
MatSetValuesBlocked_IS() in src/mat/impls/is/matis.c
MatSetValuesBlocked_MPISBAIJ() in src/mat/impls/sbaij/mpi/mpisbaij.c
MatSetValuesBlocked_SeqSBAIJ() in src/mat/impls/sbaij/seq/sbaij.c

Index of all Mat routines
Table of Contents for all manual pages
Index of all manual pages