MatShellSetOperation#

Allows user to set a matrix operation for a MATSHELL shell matrix.

Synopsis#

#include "petscmat.h" 
PetscErrorCode MatShellSetOperation(Mat mat, MatOperation op, void (*g)(void))

Logically Collective

Input Parameters#

mat - the MATSHELL shell matrix
op - the name of the operation
g - the function that provides the operation.

Example Usage#

  extern PetscErrorCode usermult(Mat, Vec, Vec);

  MatCreateShell(comm, m, n, M, N, ctx, &A);
  MatShellSetOperation(A, MATOP_MULT, (void(*)(void))usermult);

Notes#

See the file include/petscmat.h for a complete list of matrix operations, which all have the form MATOP_, where is the name (in all capital letters) of the user interface routine (e.g., MatMult() -> MATOP_MULT).

All user-provided functions (except for MATOP_DESTROY) should have the same calling sequence as the usual matrix interface routines, since they are intended to be accessed via the usual matrix interface routines, e.g.,

MatMult(Mat, Vec, Vec) -> usermult(Mat, Vec, Vec)

In particular each function MUST return an error code of 0 on success and nonzero on failure.

Within each user-defined routine, the user should call MatShellGetContext() to obtain the user-defined context that was set by MatCreateShell().

Use MatSetOperation() to set an operation for any matrix type. For matrix product operations (i.e. MatMatXXX(), MatTransposeMatXXX() etc) use MatShellSetMatProductOperation()

Fortran Notes#

For MatCreateVecs() the user code should check if the input left or right matrix is -1 and in that case not generate a matrix. See src/mat/tests/ex120f.F