Actual source code: petscmat.h
petsc-3.4.2 2013-07-02

      1: /*
      2:      Include file for the matrix component of PETSc
      3: */
      4: #ifndef __PETSCMAT_H
      6: #include <petscvec.h>

      8: /*S
      9:      Mat - Abstract PETSc matrix object used to manage all linear operators in PETSc, even those without
     10:            an explicit sparse representation (such as matrix-free operators)

     12:    Level: beginner

     14:   Concepts: matrix; linear operator

     16: .seealso:  MatCreate(), MatType, MatSetType(), MatDestroy()
     17: S*/
     18: typedef struct _p_Mat*           Mat;

     20: /*J
     21:     MatType - String with the name of a PETSc matrix type

     23:    Level: beginner

     25: .seealso: MatSetType(), Mat, MatSolverPackage, MatRegister()
     26: J*/
     27: typedef const char* MatType;
     28: #define MATSAME            "same"
     29: #define MATMAIJ            "maij"
     30: #define MATSEQMAIJ         "seqmaij"
     31: #define MATMPIMAIJ         "mpimaij"
     32: #define MATIS              "is"
     33: #define MATAIJ             "aij"
     34: #define MATSEQAIJ          "seqaij"
     35: #define MATSEQAIJPTHREAD   "seqaijpthread"
     36: #define MATAIJPTHREAD      "aijpthread"
     37: #define MATMPIAIJ          "mpiaij"
     38: #define MATAIJCRL          "aijcrl"
     39: #define MATSEQAIJCRL       "seqaijcrl"
     40: #define MATMPIAIJCRL       "mpiaijcrl"
     41: #define MATAIJCUSP         "aijcusp"
     42: #define MATSEQAIJCUSP      "seqaijcusp"
     43: #define MATMPIAIJCUSP      "mpiaijcusp"
     44: #define MATAIJCUSPARSE     "aijcusparse"
     45: #define MATSEQAIJCUSPARSE  "seqaijcusparse"
     46: #define MATMPIAIJCUSPARSE  "mpiaijcusparse"
     47: #define MATAIJPERM         "aijperm"
     48: #define MATSEQAIJPERM      "seqaijperm"
     49: #define MATMPIAIJPERM      "mpiaijperm"
     50: #define MATSHELL           "shell"
     51: #define MATDENSE           "dense"
     52: #define MATSEQDENSE        "seqdense"
     53: #define MATMPIDENSE        "mpidense"
     54: #define MATELEMENTAL       "elemental"
     55: #define MATBAIJ            "baij"
     56: #define MATSEQBAIJ         "seqbaij"
     57: #define MATMPIBAIJ         "mpibaij"
     58: #define MATMPIADJ          "mpiadj"
     59: #define MATSBAIJ           "sbaij"
     60: #define MATSEQSBAIJ        "seqsbaij"
     61: #define MATMPISBAIJ        "mpisbaij"
     62: #define MATSEQBSTRM        "seqbstrm"
     63: #define MATMPIBSTRM        "mpibstrm"
     64: #define MATBSTRM           "bstrm"
     65: #define MATSEQSBSTRM       "seqsbstrm"
     66: #define MATMPISBSTRM       "mpisbstrm"
     67: #define MATSBSTRM          "sbstrm"
     68: #define MATDAAD            "daad"
     69: #define MATMFFD            "mffd"
     70: #define MATNORMAL          "normal"
     71: #define MATLRC             "lrc"
     72: #define MATSCATTER         "scatter"
     73: #define MATBLOCKMAT        "blockmat"
     74: #define MATCOMPOSITE       "composite"
     75: #define MATFFT             "fft"
     76: #define MATFFTW            "fftw"
     77: #define MATSEQCUFFT        "seqcufft"
     78: #define MATTRANSPOSEMAT    "transpose"
     79: #define MATSCHURCOMPLEMENT "schurcomplement"
     80: #define MATPYTHON          "python"
     81: #define MATHYPRESTRUCT     "hyprestruct"
     82: #define MATHYPRESSTRUCT    "hypresstruct"
     83: #define MATSUBMATRIX       "submatrix"
     84: #define MATLOCALREF        "localref"
     85: #define MATNEST            "nest"

     87: /*J
     88:     MatSolverPackage - String with the name of a PETSc matrix solver type.

     90:     For example: "petsc" indicates what PETSc provides, "superlu" indicates either
     91:        SuperLU or SuperLU_Dist etc.

     94:    Level: beginner

     96: .seealso: MatGetFactor(), Mat, MatSetType(), MatType
     97: J*/
     98: #define MatSolverPackage char*
     99: #define MATSOLVERSUPERLU      "superlu"
    100: #define MATSOLVERSUPERLU_DIST "superlu_dist"
    101: #define MATSOLVERUMFPACK      "umfpack"
    102: #define MATSOLVERCHOLMOD      "cholmod"
    103: #define MATSOLVERESSL         "essl"
    104: #define MATSOLVERLUSOL        "lusol"
    105: #define MATSOLVERMUMPS        "mumps"
    106: #define MATSOLVERPASTIX       "pastix"
    107: #define MATSOLVERMATLAB       "matlab"
    108: #define MATSOLVERPETSC        "petsc"
    109: #define MATSOLVERBAS          "bas"
    110: #define MATSOLVERCUSPARSE     "cusparse"
    111: #define MATSOLVERBSTRM        "bstrm"
    112: #define MATSOLVERSBSTRM       "sbstrm"
    113: #define MATSOLVERELEMENTAL    "elemental"
    114: #define MATSOLVERCLIQUE       "clique"

    116: /*E
    117:     MatFactorType - indicates what type of factorization is requested

    119:     Level: beginner

    121:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    123: .seealso: MatSolverPackage, MatGetFactor()
    124: E*/
    125: typedef enum {MAT_FACTOR_NONE, MAT_FACTOR_LU, MAT_FACTOR_CHOLESKY, MAT_FACTOR_ILU, MAT_FACTOR_ICC,MAT_FACTOR_ILUDT} MatFactorType;
    126: PETSC_EXTERN const char *const MatFactorTypes[];

    128: PETSC_EXTERN PetscErrorCode MatGetFactor(Mat,const MatSolverPackage,MatFactorType,Mat*);
    129: PETSC_EXTERN PetscErrorCode MatGetFactorAvailable(Mat,const MatSolverPackage,MatFactorType,PetscBool *);
    130: PETSC_EXTERN PetscErrorCode MatFactorGetSolverPackage(Mat,const MatSolverPackage*);
    131: PETSC_EXTERN PetscErrorCode MatGetFactorType(Mat,MatFactorType*);

    133: /* Logging support */
    134: #define    MAT_FILE_CLASSID 1211216    /* used to indicate matrices in binary files */
    135: PETSC_EXTERN PetscClassId MAT_CLASSID;
    136: PETSC_EXTERN PetscClassId MAT_FDCOLORING_CLASSID;
    137: PETSC_EXTERN PetscClassId MAT_TRANSPOSECOLORING_CLASSID;
    138: PETSC_EXTERN PetscClassId MAT_PARTITIONING_CLASSID;
    139: PETSC_EXTERN PetscClassId MAT_COARSEN_CLASSID;
    140: PETSC_EXTERN PetscClassId MAT_NULLSPACE_CLASSID;
    141: PETSC_EXTERN PetscClassId MATMFFD_CLASSID;

    143: /*E
    144:     MatReuse - Indicates if matrices obtained from a previous call to MatGetSubMatrices()
    145:      or MatGetSubMatrix() are to be reused to store the new matrix values. For MatConvert() is used to indicate
    146:      that the input matrix is to be replaced with the converted matrix.

    148:     Level: beginner

    150:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    152: .seealso: MatGetSubMatrices(), MatGetSubMatrix(), MatDestroyMatrices(), MatConvert()
    153: E*/
    154: typedef enum {MAT_INITIAL_MATRIX,MAT_REUSE_MATRIX,MAT_IGNORE_MATRIX} MatReuse;

    156: /*E
    157:     MatGetSubMatrixOption - Indicates if matrices obtained from a call to MatGetSubMatrices()
    158:      include the matrix values. Currently it is only used by MatGetSeqNonzerostructure().

    160:     Level: beginner

    162: .seealso: MatGetSeqNonzerostructure()
    163: E*/
    164: typedef enum {MAT_DO_NOT_GET_VALUES,MAT_GET_VALUES} MatGetSubMatrixOption;

    166: PETSC_EXTERN PetscErrorCode MatInitializePackage(void);

    168: PETSC_EXTERN PetscErrorCode MatCreate(MPI_Comm,Mat*);
    169: PETSC_EXTERN PetscErrorCode MatSetSizes(Mat,PetscInt,PetscInt,PetscInt,PetscInt);
    170: PETSC_EXTERN PetscErrorCode MatSetType(Mat,MatType);
    171: PETSC_EXTERN PetscErrorCode MatSetFromOptions(Mat);
    172: PETSC_EXTERN PetscErrorCode MatViewFromOptions(Mat,const char[],const char[]);
    173: PETSC_EXTERN PetscErrorCode MatRegisterAll(void);
    174: PETSC_EXTERN PetscErrorCode MatRegister(const char[],PetscErrorCode(*)(Mat));
    175: PETSC_EXTERN PetscErrorCode MatRegisterBaseName(const char[],const char[],const char[]);
    176: PETSC_EXTERN PetscErrorCode MatSetOptionsPrefix(Mat,const char[]);
    177: PETSC_EXTERN PetscErrorCode MatAppendOptionsPrefix(Mat,const char[]);
    178: PETSC_EXTERN PetscErrorCode MatGetOptionsPrefix(Mat,const char*[]);

    180: PETSC_EXTERN PetscBool         MatRegisterAllCalled;
    181: PETSC_EXTERN PetscFunctionList MatList;
    182: PETSC_EXTERN PetscFunctionList MatColoringList;
    183: PETSC_EXTERN PetscFunctionList MatPartitioningList;
    184: PETSC_EXTERN PetscFunctionList MatCoarsenList;

    186: /*E
    187:     MatStructure - Indicates if the matrix has the same nonzero structure

    189:     Level: beginner

    191:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    193: .seealso: MatCopy(), KSPSetOperators(), PCSetOperators()
    194: E*/
    195: typedef enum {DIFFERENT_NONZERO_PATTERN,SUBSET_NONZERO_PATTERN,SAME_NONZERO_PATTERN,SAME_PRECONDITIONER} MatStructure;

    197: PETSC_EXTERN PetscErrorCode MatCreateSeqDense(MPI_Comm,PetscInt,PetscInt,PetscScalar[],Mat*);
    198: PETSC_EXTERN PetscErrorCode MatCreateDense(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscScalar[],Mat*);
    199: PETSC_EXTERN PetscErrorCode MatCreateSeqAIJ(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);
    200: PETSC_EXTERN PetscErrorCode MatCreateAIJ(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);
    201: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscInt[],const PetscScalar[],Mat *);
    202: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJWithSplitArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt[],PetscInt[],PetscScalar[],PetscInt[],PetscInt[],PetscScalar[],Mat*);

    204: PETSC_EXTERN PetscErrorCode MatCreateSeqBAIJ(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);
    205: PETSC_EXTERN PetscErrorCode MatCreateBAIJ(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);
    206: PETSC_EXTERN PetscErrorCode MatCreateMPIBAIJWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscInt[],const PetscScalar[],Mat*);

    208: PETSC_EXTERN PetscErrorCode MatCreateMPIAdj(MPI_Comm,PetscInt,PetscInt,PetscInt[],PetscInt[],PetscInt[],Mat*);
    209: PETSC_EXTERN PetscErrorCode MatCreateSeqSBAIJ(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);

    211: PETSC_EXTERN PetscErrorCode MatCreateSBAIJ(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);
    212: PETSC_EXTERN PetscErrorCode MatCreateMPISBAIJWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],const PetscInt[],const PetscScalar[],Mat *);
    213: PETSC_EXTERN PetscErrorCode MatMPISBAIJSetPreallocationCSR(Mat,PetscInt,const PetscInt[],const PetscInt[],const PetscScalar[]);
    214: PETSC_EXTERN PetscErrorCode MatXAIJSetPreallocation(Mat,PetscInt,const PetscInt*,const PetscInt*,const PetscInt*,const PetscInt*);

    216: PETSC_EXTERN PetscErrorCode MatCreateShell(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,void *,Mat*);
    217: PETSC_EXTERN PetscErrorCode MatCreateNormal(Mat,Mat*);
    218: PETSC_EXTERN PetscErrorCode MatCreateLRC(Mat,Mat,Mat,Mat*);
    219: PETSC_EXTERN PetscErrorCode MatCreateIS(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,ISLocalToGlobalMapping,Mat*);
    220: PETSC_EXTERN PetscErrorCode MatCreateSeqAIJCRL(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);
    221: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJCRL(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);

    223: PETSC_EXTERN PetscErrorCode MatCreateSeqBSTRM(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);
    224: PETSC_EXTERN PetscErrorCode MatCreateMPIBSTRM(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);
    225: PETSC_EXTERN PetscErrorCode MatCreateSeqSBSTRM(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);
    226: PETSC_EXTERN PetscErrorCode MatCreateMPISBSTRM(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);

    228: PETSC_EXTERN PetscErrorCode MatCreateScatter(MPI_Comm,VecScatter,Mat*);
    229: PETSC_EXTERN PetscErrorCode MatScatterSetVecScatter(Mat,VecScatter);
    230: PETSC_EXTERN PetscErrorCode MatScatterGetVecScatter(Mat,VecScatter*);
    231: PETSC_EXTERN PetscErrorCode MatCreateBlockMat(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt*,Mat*);
    232: PETSC_EXTERN PetscErrorCode MatCompositeAddMat(Mat,Mat);
    233: PETSC_EXTERN PetscErrorCode MatCompositeMerge(Mat);
    234: PETSC_EXTERN PetscErrorCode MatCreateComposite(MPI_Comm,PetscInt,const Mat*,Mat*);
    235: typedef enum {MAT_COMPOSITE_ADDITIVE,MAT_COMPOSITE_MULTIPLICATIVE} MatCompositeType;
    236: PETSC_EXTERN PetscErrorCode MatCompositeSetType(Mat,MatCompositeType);

    238: PETSC_EXTERN PetscErrorCode MatCreateFFT(MPI_Comm,PetscInt,const PetscInt[],MatType,Mat*);
    239: PETSC_EXTERN PetscErrorCode MatCreateSeqCUFFT(MPI_Comm,PetscInt,const PetscInt[],Mat*);

    241: PETSC_EXTERN PetscErrorCode MatCreateTranspose(Mat,Mat*);
    242: PETSC_EXTERN PetscErrorCode MatCreateSubMatrix(Mat,IS,IS,Mat*);
    243: PETSC_EXTERN PetscErrorCode MatSubMatrixUpdate(Mat,Mat,IS,IS);
    244: PETSC_EXTERN PetscErrorCode MatCreateLocalRef(Mat,IS,IS,Mat*);

    246: PETSC_EXTERN PetscErrorCode MatPythonSetType(Mat,const char[]);

    248: PETSC_EXTERN PetscErrorCode MatSetUp(Mat);
    249: PETSC_EXTERN PetscErrorCode MatDestroy(Mat*);

    251: PETSC_EXTERN PetscErrorCode MatConjugate(Mat);
    252: PETSC_EXTERN PetscErrorCode MatRealPart(Mat);
    253: PETSC_EXTERN PetscErrorCode MatImaginaryPart(Mat);
    254: PETSC_EXTERN PetscErrorCode MatGetDiagonalBlock(Mat,Mat*);
    255: PETSC_EXTERN PetscErrorCode MatGetTrace(Mat,PetscScalar*);
    256: PETSC_EXTERN PetscErrorCode MatInvertBlockDiagonal(Mat,const PetscScalar **);

    258: /* ------------------------------------------------------------*/
    259: PETSC_EXTERN PetscErrorCode MatSetValues(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
    260: PETSC_EXTERN PetscErrorCode MatSetValuesBlocked(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
    261: PETSC_EXTERN PetscErrorCode MatSetValuesRow(Mat,PetscInt,const PetscScalar[]);
    262: PETSC_EXTERN PetscErrorCode MatSetValuesRowLocal(Mat,PetscInt,const PetscScalar[]);
    263: PETSC_EXTERN PetscErrorCode MatSetValuesBatch(Mat,PetscInt,PetscInt,PetscInt[],const PetscScalar[]);
    264: PETSC_EXTERN PetscErrorCode MatSetRandom(Mat,PetscRandom);

    266: /*S
    267:      MatStencil - Data structure (C struct) for storing information about a single row or
    268:         column of a matrix as indexed on an associated grid.

    270:    Fortran usage is different, see MatSetValuesStencil() for details.

    272:    Level: beginner

    274:   Concepts: matrix; linear operator

    276: .seealso:  MatSetValuesStencil(), MatSetStencil(), MatSetValuesBlockedStencil()
    277: S*/
    278: typedef struct {
    279:   PetscInt k,j,i,c;
    280: } MatStencil;

    282: PETSC_EXTERN PetscErrorCode MatSetValuesStencil(Mat,PetscInt,const MatStencil[],PetscInt,const MatStencil[],const PetscScalar[],InsertMode);
    283: PETSC_EXTERN PetscErrorCode MatSetValuesBlockedStencil(Mat,PetscInt,const MatStencil[],PetscInt,const MatStencil[],const PetscScalar[],InsertMode);
    284: PETSC_EXTERN PetscErrorCode MatSetStencil(Mat,PetscInt,const PetscInt[],const PetscInt[],PetscInt);

    286: PETSC_EXTERN PetscErrorCode MatSetColoring(Mat,ISColoring);
    287: PETSC_EXTERN PetscErrorCode MatSetValuesAdifor(Mat,PetscInt,void*);

    289: /*E
    290:     MatAssemblyType - Indicates if the matrix is now to be used, or if you plan
    291:      to continue to add values to it

    293:     Level: beginner

    295: .seealso: MatAssemblyBegin(), MatAssemblyEnd()
    296: E*/
    297: typedef enum {MAT_FLUSH_ASSEMBLY=1,MAT_FINAL_ASSEMBLY=0} MatAssemblyType;
    298: PETSC_EXTERN PetscErrorCode MatAssemblyBegin(Mat,MatAssemblyType);
    299: PETSC_EXTERN PetscErrorCode MatAssemblyEnd(Mat,MatAssemblyType);
    300: PETSC_EXTERN PetscErrorCode MatAssembled(Mat,PetscBool *);

    304: /*E
    305:     MatOption - Options that may be set for a matrix and its behavior or storage

    307:     Level: beginner

    309:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    311:    Developer Notes: Entries that are negative need not be called collectively by all processes.

    313: .seealso: MatSetOption()
    314: E*/
    315: typedef enum {MAT_OPTION_MIN = -8,
    316:               MAT_NEW_NONZERO_LOCATION_ERR = -7,
    317:               MAT_NO_OFF_PROC_ZERO_ROWS = -6,
    318:               MAT_NO_OFF_PROC_ENTRIES = -5,
    319:               MAT_UNUSED_NONZERO_LOCATION_ERR = -4,
    320:               MAT_NEW_NONZERO_ALLOCATION_ERR = -3,
    321:               MAT_ROW_ORIENTED = -2,
    322:               MAT_NEW_NONZERO_LOCATIONS = -1,
    323:               MAT_SYMMETRIC = 1,
    324:               MAT_STRUCTURALLY_SYMMETRIC = 2,
    325:               MAT_NEW_DIAGONALS = 3,
    326:               MAT_IGNORE_OFF_PROC_ENTRIES = 4,
    327:               MAT_USE_HASH_TABLE = 5,
    328:               MAT_KEEP_NONZERO_PATTERN = 6,
    329:               MAT_IGNORE_ZERO_ENTRIES = 7,
    330:               MAT_USE_INODES = 8,
    331:               MAT_HERMITIAN = 9,
    332:               MAT_SYMMETRY_ETERNAL = 10,
    333:               MAT_CHECK_COMPRESSED_ROW = 11,
    334:               MAT_IGNORE_LOWER_TRIANGULAR = 12,
    335:               MAT_ERROR_LOWER_TRIANGULAR = 13,
    336:               MAT_GETROW_UPPERTRIANGULAR = 14,
    337:               MAT_SPD = 15,
    338:               MAT_OPTION_MAX = 16} MatOption;

    340: PETSC_EXTERN const char *MatOptions[];
    341: PETSC_EXTERN PetscErrorCode MatSetOption(Mat,MatOption,PetscBool );
    342: PETSC_EXTERN PetscErrorCode MatGetType(Mat,MatType*);

    344: PETSC_EXTERN PetscErrorCode MatGetValues(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],PetscScalar[]);
    345: PETSC_EXTERN PetscErrorCode MatGetRow(Mat,PetscInt,PetscInt *,const PetscInt *[],const PetscScalar*[]);
    346: PETSC_EXTERN PetscErrorCode MatRestoreRow(Mat,PetscInt,PetscInt *,const PetscInt *[],const PetscScalar*[]);
    347: PETSC_EXTERN PetscErrorCode MatGetRowUpperTriangular(Mat);
    348: PETSC_EXTERN PetscErrorCode MatRestoreRowUpperTriangular(Mat);
    349: PETSC_EXTERN PetscErrorCode MatGetColumn(Mat,PetscInt,PetscInt *,const PetscInt *[],const PetscScalar*[]);
    350: PETSC_EXTERN PetscErrorCode MatRestoreColumn(Mat,PetscInt,PetscInt *,const PetscInt *[],const PetscScalar*[]);
    351: PETSC_EXTERN PetscErrorCode MatGetColumnVector(Mat,Vec,PetscInt);
    352: PETSC_EXTERN PetscErrorCode MatSeqAIJGetArray(Mat,PetscScalar *[]);
    353: PETSC_EXTERN PetscErrorCode MatSeqAIJRestoreArray(Mat,PetscScalar *[]);
    354: PETSC_EXTERN PetscErrorCode MatDenseGetArray(Mat,PetscScalar *[]);
    355: PETSC_EXTERN PetscErrorCode MatDenseRestoreArray(Mat,PetscScalar *[]);
    356: PETSC_EXTERN PetscErrorCode MatGetBlockSize(Mat,PetscInt *);
    357: PETSC_EXTERN PetscErrorCode MatSetBlockSize(Mat,PetscInt);
    358: PETSC_EXTERN PetscErrorCode MatGetBlockSizes(Mat,PetscInt *,PetscInt *);
    359: PETSC_EXTERN PetscErrorCode MatSetBlockSizes(Mat,PetscInt,PetscInt);
    360: PETSC_EXTERN PetscErrorCode MatSetNThreads(Mat,PetscInt);
    361: PETSC_EXTERN PetscErrorCode MatGetNThreads(Mat,PetscInt*);

    363: PETSC_EXTERN PetscErrorCode MatMult(Mat,Vec,Vec);
    364: PETSC_EXTERN PetscErrorCode MatMultDiagonalBlock(Mat,Vec,Vec);
    365: PETSC_EXTERN PetscErrorCode MatMultAdd(Mat,Vec,Vec,Vec);
    366: PETSC_EXTERN PetscErrorCode MatMultTranspose(Mat,Vec,Vec);
    367: PETSC_EXTERN PetscErrorCode MatMultHermitianTranspose(Mat,Vec,Vec);
    368: PETSC_EXTERN PetscErrorCode MatIsTranspose(Mat,Mat,PetscReal,PetscBool *);
    369: PETSC_EXTERN PetscErrorCode MatIsHermitianTranspose(Mat,Mat,PetscReal,PetscBool *);
    370: PETSC_EXTERN PetscErrorCode MatMultTransposeAdd(Mat,Vec,Vec,Vec);
    371: PETSC_EXTERN PetscErrorCode MatMultHermitianTransposeAdd(Mat,Vec,Vec,Vec);
    372: PETSC_EXTERN PetscErrorCode MatMultConstrained(Mat,Vec,Vec);
    373: PETSC_EXTERN PetscErrorCode MatMultTransposeConstrained(Mat,Vec,Vec);
    374: PETSC_EXTERN PetscErrorCode MatMatSolve(Mat,Mat,Mat);

    376: /*E
    377:     MatDuplicateOption - Indicates if a duplicated sparse matrix should have
    378:   its numerical values copied over or just its nonzero structure.

    380:     Level: beginner

    382:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    384: $   MAT_SHARE_NONZERO_PATTERN - the i and j arrays in the new matrix will be shared with the original matrix
    385: $                               this also triggers the MAT_DO_NOT_COPY_VALUES option. This is used when you
    386: $                               have several matrices with the same nonzero pattern.

    388: .seealso: MatDuplicate()
    389: E*/
    390: typedef enum {MAT_DO_NOT_COPY_VALUES,MAT_COPY_VALUES,MAT_SHARE_NONZERO_PATTERN} MatDuplicateOption;

    392: PETSC_EXTERN PetscErrorCode MatConvert(Mat,MatType,MatReuse,Mat*);
    393: PETSC_EXTERN PetscErrorCode MatDuplicate(Mat,MatDuplicateOption,Mat*);

    396: PETSC_EXTERN PetscErrorCode MatCopy(Mat,Mat,MatStructure);
    397: PETSC_EXTERN PetscErrorCode MatView(Mat,PetscViewer);
    398: PETSC_EXTERN PetscErrorCode MatIsSymmetric(Mat,PetscReal,PetscBool *);
    399: PETSC_EXTERN PetscErrorCode MatIsStructurallySymmetric(Mat,PetscBool *);
    400: PETSC_EXTERN PetscErrorCode MatIsHermitian(Mat,PetscReal,PetscBool *);
    401: PETSC_EXTERN PetscErrorCode MatIsSymmetricKnown(Mat,PetscBool *,PetscBool *);
    402: PETSC_EXTERN PetscErrorCode MatIsHermitianKnown(Mat,PetscBool *,PetscBool *);
    403: PETSC_EXTERN PetscErrorCode MatMissingDiagonal(Mat,PetscBool  *,PetscInt *);
    404: PETSC_EXTERN PetscErrorCode MatLoad(Mat, PetscViewer);

    406: PETSC_EXTERN PetscErrorCode MatGetRowIJ(Mat,PetscInt,PetscBool ,PetscBool ,PetscInt*,const PetscInt *[],const PetscInt *[],PetscBool  *);
    407: PETSC_EXTERN PetscErrorCode MatRestoreRowIJ(Mat,PetscInt,PetscBool ,PetscBool ,PetscInt *,const PetscInt *[],const PetscInt *[],PetscBool  *);
    408: PETSC_EXTERN PetscErrorCode MatGetColumnIJ(Mat,PetscInt,PetscBool ,PetscBool ,PetscInt*,const PetscInt *[],const PetscInt *[],PetscBool  *);
    409: PETSC_EXTERN PetscErrorCode MatRestoreColumnIJ(Mat,PetscInt,PetscBool ,PetscBool ,PetscInt *,const PetscInt *[],const PetscInt *[],PetscBool  *);

    411: /*S
    412:      MatInfo - Context of matrix information, used with MatGetInfo()

    414:    In Fortran this is simply a double precision array of dimension MAT_INFO_SIZE

    416:    Level: intermediate

    418:   Concepts: matrix^nonzero information

    420: .seealso:  MatGetInfo(), MatInfoType
    421: S*/
    422: typedef struct {
    423:   PetscLogDouble block_size;                         /* block size */
    424:   PetscLogDouble nz_allocated,nz_used,nz_unneeded;   /* number of nonzeros */
    425:   PetscLogDouble memory;                             /* memory allocated */
    426:   PetscLogDouble assemblies;                         /* number of matrix assemblies called */
    427:   PetscLogDouble mallocs;                            /* number of mallocs during MatSetValues() */
    428:   PetscLogDouble fill_ratio_given,fill_ratio_needed; /* fill ratio for LU/ILU */
    429:   PetscLogDouble factor_mallocs;                     /* number of mallocs during factorization */
    430: } MatInfo;

    432: /*E
    433:     MatInfoType - Indicates if you want information about the local part of the matrix,
    434:      the entire parallel matrix or the maximum over all the local parts.

    436:     Level: beginner

    438:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    440: .seealso: MatGetInfo(), MatInfo
    441: E*/
    442: typedef enum {MAT_LOCAL=1,MAT_GLOBAL_MAX=2,MAT_GLOBAL_SUM=3} MatInfoType;
    443: PETSC_EXTERN PetscErrorCode MatGetInfo(Mat,MatInfoType,MatInfo*);
    444: PETSC_EXTERN PetscErrorCode MatGetDiagonal(Mat,Vec);
    445: PETSC_EXTERN PetscErrorCode MatGetRowMax(Mat,Vec,PetscInt[]);
    446: PETSC_EXTERN PetscErrorCode MatGetRowMin(Mat,Vec,PetscInt[]);
    447: PETSC_EXTERN PetscErrorCode MatGetRowMaxAbs(Mat,Vec,PetscInt[]);
    448: PETSC_EXTERN PetscErrorCode MatGetRowMinAbs(Mat,Vec,PetscInt[]);
    449: PETSC_EXTERN PetscErrorCode MatGetRowSum(Mat,Vec);
    450: PETSC_EXTERN PetscErrorCode MatTranspose(Mat,MatReuse,Mat*);
    451: PETSC_EXTERN PetscErrorCode MatHermitianTranspose(Mat,MatReuse,Mat*);
    452: PETSC_EXTERN PetscErrorCode MatPermute(Mat,IS,IS,Mat *);
    453: PETSC_EXTERN PetscErrorCode MatDiagonalScale(Mat,Vec,Vec);
    454: PETSC_EXTERN PetscErrorCode MatDiagonalSet(Mat,Vec,InsertMode);
    455: PETSC_EXTERN PetscErrorCode MatEqual(Mat,Mat,PetscBool *);
    456: PETSC_EXTERN PetscErrorCode MatMultEqual(Mat,Mat,PetscInt,PetscBool *);
    457: PETSC_EXTERN PetscErrorCode MatMultAddEqual(Mat,Mat,PetscInt,PetscBool *);
    458: PETSC_EXTERN PetscErrorCode MatMultTransposeEqual(Mat,Mat,PetscInt,PetscBool *);
    459: PETSC_EXTERN PetscErrorCode MatMultTransposeAddEqual(Mat,Mat,PetscInt,PetscBool *);

    461: PETSC_EXTERN PetscErrorCode MatNorm(Mat,NormType,PetscReal *);
    462: PETSC_EXTERN PetscErrorCode MatGetColumnNorms(Mat,NormType,PetscReal *);
    463: PETSC_EXTERN PetscErrorCode MatZeroEntries(Mat);
    464: PETSC_EXTERN PetscErrorCode MatZeroRows(Mat,PetscInt,const PetscInt [],PetscScalar,Vec,Vec);
    465: PETSC_EXTERN PetscErrorCode MatZeroRowsIS(Mat,IS,PetscScalar,Vec,Vec);
    466: PETSC_EXTERN PetscErrorCode MatZeroRowsStencil(Mat,PetscInt,const MatStencil [],PetscScalar,Vec,Vec);
    467: PETSC_EXTERN PetscErrorCode MatZeroRowsColumnsStencil(Mat,PetscInt,const MatStencil[],PetscScalar,Vec,Vec);
    468: PETSC_EXTERN PetscErrorCode MatZeroRowsColumns(Mat,PetscInt,const PetscInt [],PetscScalar,Vec,Vec);
    469: PETSC_EXTERN PetscErrorCode MatZeroRowsColumnsIS(Mat,IS,PetscScalar,Vec,Vec);

    471: PETSC_EXTERN PetscErrorCode MatGetSize(Mat,PetscInt*,PetscInt*);
    472: PETSC_EXTERN PetscErrorCode MatGetLocalSize(Mat,PetscInt*,PetscInt*);
    473: PETSC_EXTERN PetscErrorCode MatGetOwnershipRange(Mat,PetscInt*,PetscInt*);
    474: PETSC_EXTERN PetscErrorCode MatGetOwnershipRanges(Mat,const PetscInt**);
    475: PETSC_EXTERN PetscErrorCode MatGetOwnershipRangeColumn(Mat,PetscInt*,PetscInt*);
    476: PETSC_EXTERN PetscErrorCode MatGetOwnershipRangesColumn(Mat,const PetscInt**);
    477: PETSC_EXTERN PetscErrorCode MatGetOwnershipIS(Mat,IS*,IS*);

    479: PETSC_EXTERN PetscErrorCode MatGetSubMatrices(Mat,PetscInt,const IS[],const IS[],MatReuse,Mat *[]);
    480: PETSC_EXTERN PetscErrorCode MatGetSubMatricesParallel(Mat,PetscInt,const IS[],const IS[],MatReuse,Mat *[]);
    481: PETSC_EXTERN PetscErrorCode MatDestroyMatrices(PetscInt,Mat *[]);
    482: PETSC_EXTERN PetscErrorCode MatGetSubMatrix(Mat,IS,IS,MatReuse,Mat *);
    483: PETSC_EXTERN PetscErrorCode MatGetLocalSubMatrix(Mat,IS,IS,Mat*);
    484: PETSC_EXTERN PetscErrorCode MatRestoreLocalSubMatrix(Mat,IS,IS,Mat*);
    485: PETSC_EXTERN PetscErrorCode MatGetSeqNonzeroStructure(Mat,Mat*);
    486: PETSC_EXTERN PetscErrorCode MatDestroySeqNonzeroStructure(Mat*);

    488: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJConcatenateSeqAIJ(MPI_Comm,Mat,PetscInt,MatReuse,Mat*);
    489: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJConcatenateSeqAIJSymbolic(MPI_Comm,Mat,PetscInt,Mat*);
    490: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJConcatenateSeqAIJNumeric(MPI_Comm,Mat,PetscInt,Mat);
    491: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJSumSeqAIJ(MPI_Comm,Mat,PetscInt,PetscInt,MatReuse,Mat*);
    492: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJSumSeqAIJSymbolic(MPI_Comm,Mat,PetscInt,PetscInt,Mat*);
    493: PETSC_EXTERN PetscErrorCode MatCreateMPIAIJSumSeqAIJNumeric(Mat,Mat);
    494: PETSC_EXTERN PetscErrorCode MatMPIAIJGetLocalMat(Mat,MatReuse,Mat*);
    495: PETSC_EXTERN PetscErrorCode MatMPIAIJGetLocalMatCondensed(Mat,MatReuse,IS*,IS*,Mat*);
    496: PETSC_EXTERN PetscErrorCode MatGetBrowsOfAcols(Mat,Mat,MatReuse,IS*,IS*,Mat*);
    497: PETSC_EXTERN PetscErrorCode MatGetGhosts(Mat, PetscInt *,const PetscInt *[]);

    499: PETSC_EXTERN PetscErrorCode MatIncreaseOverlap(Mat,PetscInt,IS[],PetscInt);

    501: PETSC_EXTERN PetscErrorCode MatMatMult(Mat,Mat,MatReuse,PetscReal,Mat*);
    502: PETSC_EXTERN PetscErrorCode MatMatMultSymbolic(Mat,Mat,PetscReal,Mat*);
    503: PETSC_EXTERN PetscErrorCode MatMatMultNumeric(Mat,Mat,Mat);

    505: PETSC_EXTERN PetscErrorCode MatMatMatMult(Mat,Mat,Mat,MatReuse,PetscReal,Mat*);
    506: PETSC_EXTERN PetscErrorCode MatMatMatMultSymbolic(Mat,Mat,Mat,PetscReal,Mat*);
    507: PETSC_EXTERN PetscErrorCode MatMatMatMultNumeric(Mat,Mat,Mat,Mat);

    509: PETSC_EXTERN PetscErrorCode MatPtAP(Mat,Mat,MatReuse,PetscReal,Mat*);
    510: PETSC_EXTERN PetscErrorCode MatPtAPSymbolic(Mat,Mat,PetscReal,Mat*);
    511: PETSC_EXTERN PetscErrorCode MatPtAPNumeric(Mat,Mat,Mat);
    512: PETSC_EXTERN PetscErrorCode MatRARt(Mat,Mat,MatReuse,PetscReal,Mat*);
    513: PETSC_EXTERN PetscErrorCode MatRARtSymbolic(Mat,Mat,PetscReal,Mat*);
    514: PETSC_EXTERN PetscErrorCode MatRARtNumeric(Mat,Mat,Mat);

    516: PETSC_EXTERN PetscErrorCode MatTransposeMatMult(Mat,Mat,MatReuse,PetscReal,Mat*);
    517: PETSC_EXTERN PetscErrorCode MatTransposetMatMultSymbolic(Mat,Mat,PetscReal,Mat*);
    518: PETSC_EXTERN PetscErrorCode MatTransposetMatMultNumeric(Mat,Mat,Mat);
    519: PETSC_EXTERN PetscErrorCode MatMatTransposeMult(Mat,Mat,MatReuse,PetscReal,Mat*);
    520: PETSC_EXTERN PetscErrorCode MatMatTransposeMultSymbolic(Mat,Mat,PetscReal,Mat*);
    521: PETSC_EXTERN PetscErrorCode MatMatTransposeMultNumeric(Mat,Mat,Mat);

    523: PETSC_EXTERN PetscErrorCode MatAXPY(Mat,PetscScalar,Mat,MatStructure);
    524: PETSC_EXTERN PetscErrorCode MatAYPX(Mat,PetscScalar,Mat,MatStructure);

    526: PETSC_EXTERN PetscErrorCode MatScale(Mat,PetscScalar);
    527: PETSC_EXTERN PetscErrorCode MatShift(Mat,PetscScalar);

    529: PETSC_EXTERN PetscErrorCode MatSetLocalToGlobalMapping(Mat,ISLocalToGlobalMapping,ISLocalToGlobalMapping);
    530: PETSC_EXTERN PetscErrorCode MatSetLocalToGlobalMappingBlock(Mat,ISLocalToGlobalMapping,ISLocalToGlobalMapping);
    531: PETSC_EXTERN PetscErrorCode MatGetLocalToGlobalMapping(Mat,ISLocalToGlobalMapping*,ISLocalToGlobalMapping*);
    532: PETSC_EXTERN PetscErrorCode MatGetLocalToGlobalMappingBlock(Mat,ISLocalToGlobalMapping*,ISLocalToGlobalMapping*);
    533: PETSC_EXTERN PetscErrorCode MatZeroRowsLocal(Mat,PetscInt,const PetscInt [],PetscScalar,Vec,Vec);
    534: PETSC_EXTERN PetscErrorCode MatZeroRowsLocalIS(Mat,IS,PetscScalar,Vec,Vec);
    535: PETSC_EXTERN PetscErrorCode MatZeroRowsColumnsLocal(Mat,PetscInt,const PetscInt [],PetscScalar,Vec,Vec);
    536: PETSC_EXTERN PetscErrorCode MatZeroRowsColumnsLocalIS(Mat,IS,PetscScalar,Vec,Vec);
    537: PETSC_EXTERN PetscErrorCode MatSetValuesLocal(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],const PetscScalar[],InsertMode);
    538: PETSC_EXTERN PetscErrorCode MatSetValuesBlockedLocal(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[],const PetscScalar[],InsertMode);

    540: PETSC_EXTERN PetscErrorCode MatStashSetInitialSize(Mat,PetscInt,PetscInt);
    541: PETSC_EXTERN PetscErrorCode MatStashGetInfo(Mat,PetscInt*,PetscInt*,PetscInt*,PetscInt*);

    543: PETSC_EXTERN PetscErrorCode MatInterpolate(Mat,Vec,Vec);
    544: PETSC_EXTERN PetscErrorCode MatInterpolateAdd(Mat,Vec,Vec,Vec);
    545: PETSC_EXTERN PetscErrorCode MatRestrict(Mat,Vec,Vec);
    546: PETSC_EXTERN PetscErrorCode MatGetVecs(Mat,Vec*,Vec*);
    547: PETSC_EXTERN PetscErrorCode MatGetRedundantMatrix(Mat,PetscInt,MPI_Comm,PetscInt,MatReuse,Mat*);
    548: PETSC_EXTERN PetscErrorCode MatGetMultiProcBlock(Mat,MPI_Comm,MatReuse,Mat*);
    549: PETSC_EXTERN PetscErrorCode MatFindZeroDiagonals(Mat,IS*);

    551: /*MC
    552:    MatSetValue - Set a single entry into a matrix.

    554:    Not collective

    556:    Input Parameters:
    557: +  m - the matrix
    558: .  row - the row location of the entry
    559: .  col - the column location of the entry
    560: .  value - the value to insert
    561: -  mode - either INSERT_VALUES or ADD_VALUES

    563:    Notes:
    564:    For efficiency one should use MatSetValues() and set several or many
    565:    values simultaneously if possible.

    567:    Level: beginner

    569: .seealso: MatSetValues(), MatSetValueLocal()
    570: M*/
    571: PETSC_STATIC_INLINE PetscErrorCode MatSetValue(Mat v,PetscInt i,PetscInt j,PetscScalar va,InsertMode mode) {return MatSetValues(v,1,&i,1,&j,&va,mode);}

    573: PETSC_STATIC_INLINE PetscErrorCode MatGetValue(Mat v,PetscInt i,PetscInt j,PetscScalar *va) {return MatGetValues(v,1,&i,1,&j,va);}

    575: PETSC_STATIC_INLINE PetscErrorCode MatSetValueLocal(Mat v,PetscInt i,PetscInt j,PetscScalar va,InsertMode mode) {return MatSetValuesLocal(v,1,&i,1,&j,&va,mode);}

    577: /*MC
    578:    MatPreallocateInitialize - Begins the block of code that will count the number of nonzeros per
    579:        row in a matrix providing the data that one can use to correctly preallocate the matrix.

    581:    Synopsis:
    582:    #include "petscmat.h"
    583:    PetscErrorCode MatPreallocateInitialize(MPI_Comm comm, PetscInt nrows, PetscInt ncols, PetscInt *dnz, PetscInt *onz)

    585:    Collective on MPI_Comm

    587:    Input Parameters:
    588: +  comm - the communicator that will share the eventually allocated matrix
    589: .  nrows - the number of LOCAL rows in the matrix
    590: -  ncols - the number of LOCAL columns in the matrix

    592:    Output Parameters:
    593: +  dnz - the array that will be passed to the matrix preallocation routines
    594: -  ozn - the other array passed to the matrix preallocation routines

    597:    Level: intermediate

    599:    Notes:
    600:     See the <A href="../../docs/manual.pdf#nameddest=Chapter 11 Hints for Performance Tuning">Hints for Performance Improvment</A> chapter in the users manual for more details.

    602:    Do not malloc or free dnz and onz, that is handled internally by these routines

    604:    Use MatPreallocateInitializeSymmetric() for symmetric matrices (MPISBAIJ matrices)

    606:    This is a MACRO not a function because it has a leading { that is closed by PetscPreallocateFinalize().

    608:   Concepts: preallocation^Matrix

    610: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
    611:           MatPreallocateInitializeSymmetric(), MatPreallocateSymmetricSetLocal()
    612: M*/
    613: #define MatPreallocateInitialize(comm,nrows,ncols,dnz,onz) 0; \
    614: { \
    615:   PetscErrorCode _4_ierr; PetscInt __nrows = (nrows),__ctmp = (ncols),__rstart,__start,__end; \
    616:   _4_PetscMalloc2(__nrows,PetscInt,&dnz,__nrows,PetscInt,&onz);CHKERRQ(_4_ierr); \
    617:   _4_PetscMemzero(dnz,__nrows*sizeof(PetscInt));CHKERRQ(_4_ierr);\
    618:   _4_PetscMemzero(onz,__nrows*sizeof(PetscInt));CHKERRQ(_4_ierr); __start = 0; __end = __start; \
    619:   _4_MPI_Scan(&__ctmp,&__end,1,MPIU_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __start = __end - __ctmp;\
    620:   _4_MPI_Scan(&__nrows,&__rstart,1,MPIU_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __rstart = __rstart - __nrows;

    622: /*MC
    623:    MatPreallocateSetLocal - Indicates the locations (rows and columns) in the matrix where nonzeros will be
    624:        inserted using a local number of the rows and columns

    626:    Synopsis:
    627:    #include "petscmat.h"
    628:    PetscErrorCode MatPreallocateSetLocal(ISLocalToGlobalMappping map,PetscInt nrows, PetscInt *rows,PetscInt ncols, PetscInt *cols,PetscInt *dnz, PetscInt *onz)

    630:    Not Collective

    632:    Input Parameters:
    633: +  map - the row mapping from local numbering to global numbering
    634: .  nrows - the number of rows indicated
    635: .  rows - the indices of the rows
    636: .  cmap - the column mapping from local to global numbering
    637: .  ncols - the number of columns in the matrix
    638: .  cols - the columns indicated
    639: .  dnz - the array that will be passed to the matrix preallocation routines
    640: -  ozn - the other array passed to the matrix preallocation routines

    643:    Level: intermediate

    645:    Notes:
    646:     See the <A href="../../docs/manual.pdf#nameddest=Chapter 11 Hints for Performance Tuning">Hints for Performance Improvment</A> chapter in the users manual for more details.

    648:    Do not malloc or free dnz and onz, that is handled internally by these routines

    650:   Concepts: preallocation^Matrix

    652: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
    653:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal()
    654: M*/
    655: #define MatPreallocateSetLocal(rmap,nrows,rows,cmap,ncols,cols,dnz,onz) 0; \
    656: {\
    657:   PetscInt __l;\
    658:   _4_ISLocalToGlobalMappingApply(rmap,nrows,rows,rows);CHKERRQ(_4_ierr);\
    659:   _4_ISLocalToGlobalMappingApply(cmap,ncols,cols,cols);CHKERRQ(_4_ierr);\
    660:   for (__l=0;__l<nrows;__l++) {\
    661:     _4_MatPreallocateSet((rows)[__l],ncols,cols,dnz,onz);CHKERRQ(_4_ierr);\
    662:   }\
    663: }

    665: /*MC
    666:    MatPreallocateSymmetricSetLocal - Indicates the locations (rows and columns) in the matrix where nonzeros will be
    667:        inserted using a local number of the rows and columns

    669:    Synopsis:
    670:    #include "petscmat.h"
    671:    PetscErrorCode MatPreallocateSymmetricSetLocal(ISLocalToGlobalMappping map,PetscInt nrows, PetscInt *rows,PetscInt ncols, PetscInt *cols,PetscInt *dnz, PetscInt *onz)

    673:    Not Collective

    675:    Input Parameters:
    676: +  map - the mapping between local numbering and global numbering
    677: .  nrows - the number of rows indicated
    678: .  rows - the indices of the rows
    679: .  ncols - the number of columns in the matrix
    680: .  cols - the columns indicated
    681: .  dnz - the array that will be passed to the matrix preallocation routines
    682: -  ozn - the other array passed to the matrix preallocation routines

    685:    Level: intermediate

    687:    Notes:
    688:     See the <A href="../../docs/manual.pdf#nameddest=Chapter 11 Hints for Performance Tuning">Hints for Performance Improvment</A> chapter in the users manual for more details.

    690:    Do not malloc or free dnz and onz that is handled internally by these routines

    692:   Concepts: preallocation^Matrix

    694: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
    695:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
    696: M*/
    697: #define MatPreallocateSymmetricSetLocal(map,nrows,rows,ncols,cols,dnz,onz) 0;\
    698: {\
    699:   PetscInt __l;\
    700:   _4_ISLocalToGlobalMappingApply(map,nrows,rows,rows);CHKERRQ(_4_ierr);\
    701:   _4_ISLocalToGlobalMappingApply(map,ncols,cols,cols);CHKERRQ(_4_ierr);\
    702:   for (__l=0;__l<nrows;__l++) {\
    703:     _4_MatPreallocateSymmetricSet((rows)[__l],ncols,cols,dnz,onz);CHKERRQ(_4_ierr);\
    704:   }\
    705: }

    707: /*MC
    708:    MatPreallocateSet - Indicates the locations (rows and columns) in the matrix where nonzeros will be
    709:        inserted using a local number of the rows and columns

    711:    Synopsis:
    712:    #include "petscmat.h"
    713:    PetscErrorCode MatPreallocateSet(PetscInt nrows, PetscInt *rows,PetscInt ncols, PetscInt *cols,PetscInt *dnz, PetscInt *onz)

    715:    Not Collective

    717:    Input Parameters:
    718: +  row - the row
    719: .  ncols - the number of columns in the matrix
    720: -  cols - the columns indicated

    722:    Output Parameters:
    723: +  dnz - the array that will be passed to the matrix preallocation routines
    724: -  ozn - the other array passed to the matrix preallocation routines

    727:    Level: intermediate

    729:    Notes:
    730:     See the <A href="../../docs/manual.pdf#nameddest=Chapter 11 Hints for Performance Tuning">Hints for Performance Improvment</A> chapter in the users manual for more details.

    732:    Do not malloc or free dnz and onz that is handled internally by these routines

    734:    This is a MACRO not a function because it uses variables declared in MatPreallocateInitialize().

    736:   Concepts: preallocation^Matrix

    738: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
    739:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
    740: M*/
    741: #define MatPreallocateSet(row,nc,cols,dnz,onz) 0;\
    742: { PetscInt __i; \
    743:   if (row < __rstart) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Trying to set preallocation for row %D less than first local row %D",row,__rstart);\
    744:   if (row >= __rstart+__nrows) SETERRQ2(PETSC_COMM_SELF,PETSC_ERR_ARG_OUTOFRANGE,"Trying to set preallocation for row %D greater than last local row %D",row,__rstart+__nrows-1);\
    745:   for (__i=0; __i<nc; __i++) {\
    746:     if ((cols)[__i] < __start || (cols)[__i] >= __end) onz[row - __rstart]++; \
    747:     else dnz[row - __rstart]++;\
    748:   }\
    749: }

    751: /*MC
    752:    MatPreallocateSymmetricSet - Indicates the locations (rows and columns) in the matrix where nonzeros will be
    753:        inserted using a local number of the rows and columns

    755:    Synopsis:
    756:    #include "petscmat.h"
    757:    PetscErrorCode MatPreallocateSymmetricSet(PetscInt nrows, PetscInt *rows,PetscInt ncols, PetscInt *cols,PetscInt *dnz, PetscInt *onz)

    759:    Not Collective

    761:    Input Parameters:
    762: +  nrows - the number of rows indicated
    763: .  rows - the indices of the rows
    764: .  ncols - the number of columns in the matrix
    765: .  cols - the columns indicated
    766: .  dnz - the array that will be passed to the matrix preallocation routines
    767: -  ozn - the other array passed to the matrix preallocation routines

    770:    Level: intermediate

    772:    Notes:
    773:     See the <A href="../../docs/manual.pdf#nameddest=Chapter 11 Hints for Performance Tuning">Hints for Performance Improvment</A> chapter in the users manual for more details.

    775:    Do not malloc or free dnz and onz that is handled internally by these routines

    777:    This is a MACRO not a function because it uses variables declared in MatPreallocateInitialize().

    779:   Concepts: preallocation^Matrix

    781: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
    782:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
    783: M*/
    784: #define MatPreallocateSymmetricSet(row,nc,cols,dnz,onz) 0;\
    785: { PetscInt __i; \
    786:   for (__i=0; __i<nc; __i++) {\
    787:     if (cols[__i] >= __end) onz[row - __rstart]++; \
    788:     else if (cols[__i] >= row) dnz[row - __rstart]++;\
    789:   }\
    790: }

    792: /*MC
    793:    MatPreallocateLocation -  An alternative to MatPreallocationSet() that puts the nonzero locations into the matrix if it exists

    795:    Synopsis:
    796:    #include "petscmat.h"
    797:    PetscErrorCode MatPreallocateLocations(Mat A,PetscInt row,PetscInt ncols,PetscInt *cols,PetscInt *dnz,PetscInt *onz)

    799:    Not Collective

    801:    Input Parameters:
    802: .  A - matrix
    803: .  row - row where values exist (must be local to this process)
    804: .  ncols - number of columns
    805: .  cols - columns with nonzeros
    806: .  dnz - the array that will be passed to the matrix preallocation routines
    807: -  ozn - the other array passed to the matrix preallocation routines

    810:    Level: intermediate

    812:    Notes:
    813:     See the <A href="../../docs/manual.pdf#nameddest=Chapter 11 Hints for Performance Tuning">Hints for Performance Improvment</A> chapter in the users manual for more details.

    815:    Do not malloc or free dnz and onz that is handled internally by these routines

    817:    This is a MACRO not a function because it uses a bunch of variables private to the MatPreallocation.... routines.

    819:   Concepts: preallocation^Matrix

    821: .seealso: MatPreallocateInitialize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
    822:           MatPreallocateSymmetricSetLocal()
    823: M*/
    824: #define MatPreallocateLocation(A,row,ncols,cols,dnz,onz) 0;if (A) {MatSetValues(A,1,&row,ncols,cols,NULL,INSERT_VALUES);} else { MatPreallocateSet(row,ncols,cols,dnz,onz);}

    827: /*MC
    828:    MatPreallocateFinalize - Ends the block of code that will count the number of nonzeros per
    829:        row in a matrix providing the data that one can use to correctly preallocate the matrix.

    831:    Synopsis:
    832:    #include "petscmat.h"
    833:    PetscErrorCode MatPreallocateFinalize(PetscInt *dnz, PetscInt *onz)

    835:    Collective on MPI_Comm

    837:    Input Parameters:
    838: +  dnz - the array that was be passed to the matrix preallocation routines
    839: -  ozn - the other array passed to the matrix preallocation routines

    842:    Level: intermediate

    844:    Notes:
    845:     See the <A href="../../docs/manual.pdf#nameddest=Chapter 11 Hints for Performance Tuning">Hints for Performance Improvment</A> chapter in the users manual for more details.

    847:    Do not malloc or free dnz and onz that is handled internally by these routines

    849:    This is a MACRO not a function because it closes the { started in MatPreallocateInitialize().

    851:   Concepts: preallocation^Matrix

    853: .seealso: MatPreallocateInitialize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
    854:           MatPreallocateSymmetricSetLocal()
    855: M*/
    856: #define MatPreallocateFinalize(dnz,onz) 0;_4_PetscFree2(dnz,onz);CHKERRQ(_4_ierr);}

    860: /* Routines unique to particular data structures */
    861: PETSC_EXTERN PetscErrorCode MatShellGetContext(Mat,void *);

    863: PETSC_EXTERN PetscErrorCode MatInodeAdjustForInodes(Mat,IS*,IS*);
    864: PETSC_EXTERN PetscErrorCode MatInodeGetInodeSizes(Mat,PetscInt *,PetscInt *[],PetscInt *);

    866: PETSC_EXTERN PetscErrorCode MatSeqAIJSetColumnIndices(Mat,PetscInt[]);
    867: PETSC_EXTERN PetscErrorCode MatSeqBAIJSetColumnIndices(Mat,PetscInt[]);
    868: PETSC_EXTERN PetscErrorCode MatCreateSeqAIJWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt[],PetscInt[],PetscScalar[],Mat*);
    869: PETSC_EXTERN PetscErrorCode MatCreateSeqBAIJWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt[],PetscInt[],PetscScalar[],Mat*);
    870: PETSC_EXTERN PetscErrorCode MatCreateSeqSBAIJWithArrays(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt[],PetscInt[],PetscScalar[],Mat*);
    871: PETSC_EXTERN PetscErrorCode MatCreateSeqAIJFromTriple(MPI_Comm,PetscInt,PetscInt,PetscInt[],PetscInt[],PetscScalar[],Mat*,PetscInt,PetscBool);

    873: #define MAT_SKIP_ALLOCATION -4

    875: PETSC_EXTERN PetscErrorCode MatSeqBAIJSetPreallocation(Mat,PetscInt,PetscInt,const PetscInt[]);
    876: PETSC_EXTERN PetscErrorCode MatSeqSBAIJSetPreallocation(Mat,PetscInt,PetscInt,const PetscInt[]);
    877: PETSC_EXTERN PetscErrorCode MatSeqAIJSetPreallocation(Mat,PetscInt,const PetscInt[]);

    879: PETSC_EXTERN PetscErrorCode MatMPIBAIJSetPreallocation(Mat,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[]);
    880: PETSC_EXTERN PetscErrorCode MatMPISBAIJSetPreallocation(Mat,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[]);
    881: PETSC_EXTERN PetscErrorCode MatMPIAIJSetPreallocation(Mat,PetscInt,const PetscInt[],PetscInt,const PetscInt[]);
    882: PETSC_EXTERN PetscErrorCode MatSeqAIJSetPreallocationCSR(Mat,const PetscInt [],const PetscInt [],const PetscScalar []);
    883: PETSC_EXTERN PetscErrorCode MatSeqBAIJSetPreallocationCSR(Mat,PetscInt,const PetscInt[],const PetscInt[],const PetscScalar[]);
    884: PETSC_EXTERN PetscErrorCode MatMPIAIJSetPreallocationCSR(Mat,const PetscInt[],const PetscInt[],const PetscScalar[]);
    885: PETSC_EXTERN PetscErrorCode MatMPIBAIJSetPreallocationCSR(Mat,PetscInt,const PetscInt[],const PetscInt[],const PetscScalar[]);
    886: PETSC_EXTERN PetscErrorCode MatMPIAdjSetPreallocation(Mat,PetscInt[],PetscInt[],PetscInt[]);
    887: PETSC_EXTERN PetscErrorCode MatMPIDenseSetPreallocation(Mat,PetscScalar[]);
    888: PETSC_EXTERN PetscErrorCode MatSeqDenseSetPreallocation(Mat,PetscScalar[]);
    889: PETSC_EXTERN PetscErrorCode MatMPIAIJGetSeqAIJ(Mat,Mat*,Mat*,const PetscInt*[]);
    890: PETSC_EXTERN PetscErrorCode MatMPIBAIJGetSeqBAIJ(Mat,Mat*,Mat*,const PetscInt*[]);
    891: PETSC_EXTERN PetscErrorCode MatMPIAdjCreateNonemptySubcommMat(Mat,Mat*);

    893: PETSC_EXTERN PetscErrorCode MatSeqDenseSetLDA(Mat,PetscInt);
    894: PETSC_EXTERN PetscErrorCode MatDenseGetLocalMatrix(Mat,Mat*);

    896: PETSC_EXTERN PetscErrorCode MatStoreValues(Mat);
    897: PETSC_EXTERN PetscErrorCode MatRetrieveValues(Mat);

    899: PETSC_EXTERN PetscErrorCode MatDAADSetCtx(Mat,void*);

    901: PETSC_EXTERN PetscErrorCode MatFindNonzeroRows(Mat,IS*);
    902: /*
    903:   These routines are not usually accessed directly, rather solving is
    904:   done through the KSP and PC interfaces.
    905: */

    907: /*J
    908:     MatOrderingType - String with the name of a PETSc matrix ordering

    910:    Level: beginner

    912: .seealso: MatGetOrdering()
    913: J*/
    914: typedef const char* MatOrderingType;
    915: #define MATORDERINGNATURAL     "natural"
    916: #define MATORDERINGND          "nd"
    917: #define MATORDERING1WD         "1wd"
    918: #define MATORDERINGRCM         "rcm"
    919: #define MATORDERINGQMD         "qmd"
    920: #define MATORDERINGROWLENGTH   "rowlength"
    921: #define MATORDERINGAMD         "amd"            /* only works if UMFPACK is installed with PETSc */

    923: PETSC_EXTERN PetscErrorCode MatGetOrdering(Mat,MatOrderingType,IS*,IS*);
    924: PETSC_EXTERN PetscErrorCode MatGetOrderingList(PetscFunctionList*);
    925: PETSC_EXTERN PetscErrorCode MatOrderingRegister(const char[],PetscErrorCode(*)(Mat,MatOrderingType,IS*,IS*));
    926: PETSC_EXTERN PetscErrorCode MatOrderingRegisterAll(void);
    927: PETSC_EXTERN PetscBool         MatOrderingRegisterAllCalled;
    928: PETSC_EXTERN PetscFunctionList MatOrderingList;

    930: PETSC_EXTERN PetscErrorCode MatReorderForNonzeroDiagonal(Mat,PetscReal,IS,IS);

    932: /*S
    933:     MatFactorShiftType - Numeric Shift.

    935:    Level: beginner

    937: S*/
    938: typedef enum {MAT_SHIFT_NONE,MAT_SHIFT_NONZERO,MAT_SHIFT_POSITIVE_DEFINITE,MAT_SHIFT_INBLOCKS} MatFactorShiftType;
    939: PETSC_EXTERN const char *const MatFactorShiftTypes[];

    941: /*S
    942:    MatFactorInfo - Data passed into the matrix factorization routines

    944:    In Fortran these are simply double precision arrays of size MAT_FACTORINFO_SIZE, that is use
    945: $     MatFactorInfo  info(MAT_FACTORINFO_SIZE)

    947:    Notes: These are not usually directly used by users, instead use PC type of LU, ILU, CHOLESKY or ICC.

    949:       You can use MatFactorInfoInitialize() to set default values.

    951:    Level: developer

    953: .seealso: MatLUFactorSymbolic(), MatILUFactorSymbolic(), MatCholeskyFactorSymbolic(), MatICCFactorSymbolic(), MatICCFactor(),
    954:           MatFactorInfoInitialize()

    956: S*/
    957: typedef struct {
    958:   PetscReal     diagonal_fill;  /* force diagonal to fill in if initially not filled */
    959:   PetscReal     usedt;
    960:   PetscReal     dt;             /* drop tolerance */
    961:   PetscReal     dtcol;          /* tolerance for pivoting */
    962:   PetscReal     dtcount;        /* maximum nonzeros to be allowed per row */
    963:   PetscReal     fill;           /* expected fill, nonzeros in factored matrix/nonzeros in original matrix */
    964:   PetscReal     levels;         /* ICC/ILU(levels) */
    965:   PetscReal     pivotinblocks;  /* for BAIJ and SBAIJ matrices pivot in factorization on blocks, default 1.0
    966:                                    factorization may be faster if do not pivot */
    967:   PetscReal     zeropivot;      /* pivot is called zero if less than this */
    968:   PetscReal     shifttype;      /* type of shift added to matrix factor to prevent zero pivots */
    969:   PetscReal     shiftamount;     /* how large the shift is */
    970: } MatFactorInfo;

    972: PETSC_EXTERN PetscErrorCode MatFactorInfoInitialize(MatFactorInfo*);
    973: PETSC_EXTERN PetscErrorCode MatCholeskyFactor(Mat,IS,const MatFactorInfo*);
    974: PETSC_EXTERN PetscErrorCode MatCholeskyFactorSymbolic(Mat,Mat,IS,const MatFactorInfo*);
    975: PETSC_EXTERN PetscErrorCode MatCholeskyFactorNumeric(Mat,Mat,const MatFactorInfo*);
    976: PETSC_EXTERN PetscErrorCode MatLUFactor(Mat,IS,IS,const MatFactorInfo*);
    977: PETSC_EXTERN PetscErrorCode MatILUFactor(Mat,IS,IS,const MatFactorInfo*);
    978: PETSC_EXTERN PetscErrorCode MatLUFactorSymbolic(Mat,Mat,IS,IS,const MatFactorInfo*);
    979: PETSC_EXTERN PetscErrorCode MatILUFactorSymbolic(Mat,Mat,IS,IS,const MatFactorInfo*);
    980: PETSC_EXTERN PetscErrorCode MatICCFactorSymbolic(Mat,Mat,IS,const MatFactorInfo*);
    981: PETSC_EXTERN PetscErrorCode MatICCFactor(Mat,IS,const MatFactorInfo*);
    982: PETSC_EXTERN PetscErrorCode MatLUFactorNumeric(Mat,Mat,const MatFactorInfo*);
    983: PETSC_EXTERN PetscErrorCode MatGetInertia(Mat,PetscInt*,PetscInt*,PetscInt*);
    984: PETSC_EXTERN PetscErrorCode MatSolve(Mat,Vec,Vec);
    985: PETSC_EXTERN PetscErrorCode MatForwardSolve(Mat,Vec,Vec);
    986: PETSC_EXTERN PetscErrorCode MatBackwardSolve(Mat,Vec,Vec);
    987: PETSC_EXTERN PetscErrorCode MatSolveAdd(Mat,Vec,Vec,Vec);
    988: PETSC_EXTERN PetscErrorCode MatSolveTranspose(Mat,Vec,Vec);
    989: PETSC_EXTERN PetscErrorCode MatSolveTransposeAdd(Mat,Vec,Vec,Vec);
    990: PETSC_EXTERN PetscErrorCode MatSolves(Mat,Vecs,Vecs);

    992: PETSC_EXTERN PetscErrorCode MatSetUnfactored(Mat);

    994: /*E
    995:     MatSORType - What type of (S)SOR to perform

    997:     Level: beginner

    999:    May be bitwise ORd together

    1001:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    1003:    MatSORType may be bitwise ORd together, so do not change the numbers

    1005: .seealso: MatSOR()
    1006: E*/
    1007: typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3,
    1008:               SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8,
    1009:               SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16,
    1010:               SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128} MatSORType;
    1011: PETSC_EXTERN PetscErrorCode MatSOR(Mat,Vec,PetscReal,MatSORType,PetscReal,PetscInt,PetscInt,Vec);

    1013: /*
    1014:     These routines are for efficiently computing Jacobians via finite differences.
    1015: */

    1017: /*J
    1018:     MatColoringType - String with the name of a PETSc matrix coloring

    1020:    Level: beginner

    1022: .seealso: MatGetColoring(), MatColoring
    1023: J*/
    1024: typedef const char* MatColoringType;
    1025: #define MATCOLORINGNATURAL "natural"
    1026: #define MATCOLORINGSL      "sl"
    1027: #define MATCOLORINGLF      "lf"
    1028: #define MATCOLORINGID      "id"

    1030: PETSC_EXTERN PetscErrorCode MatGetColoring(Mat,MatColoringType,ISColoring*);
    1031: PETSC_EXTERN PetscErrorCode MatColoringRegister(const char[],PetscErrorCode(*)(Mat,MatColoringType,ISColoring *));

    1033: PETSC_EXTERN PetscBool MatColoringRegisterAllCalled;

    1035: PETSC_EXTERN PetscErrorCode MatColoringRegisterAll(void);
    1036: PETSC_EXTERN PetscErrorCode MatColoringPatch(Mat,PetscInt,PetscInt,ISColoringValue[],ISColoring*);

    1038: /*S
    1039:      MatFDColoring - Object for computing a sparse Jacobian via finite differences
    1040:         and coloring

    1042:    Level: beginner

    1044:   Concepts: coloring, sparse Jacobian, finite differences

    1046: .seealso:  MatFDColoringCreate()
    1047: S*/
    1048: typedef struct _p_MatFDColoring* MatFDColoring;

    1050: PETSC_EXTERN PetscErrorCode MatFDColoringCreate(Mat,ISColoring,MatFDColoring *);
    1051: PETSC_EXTERN PetscErrorCode MatFDColoringDestroy(MatFDColoring*);
    1052: PETSC_EXTERN PetscErrorCode MatFDColoringView(MatFDColoring,PetscViewer);
    1053: PETSC_EXTERN PetscErrorCode MatFDColoringSetFunction(MatFDColoring,PetscErrorCode (*)(void),void*);
    1054: PETSC_EXTERN PetscErrorCode MatFDColoringGetFunction(MatFDColoring,PetscErrorCode (**)(void),void**);
    1055: PETSC_EXTERN PetscErrorCode MatFDColoringSetParameters(MatFDColoring,PetscReal,PetscReal);
    1056: PETSC_EXTERN PetscErrorCode MatFDColoringSetFromOptions(MatFDColoring);
    1057: PETSC_EXTERN PetscErrorCode MatFDColoringApply(Mat,MatFDColoring,Vec,MatStructure*,void *);
    1058: PETSC_EXTERN PetscErrorCode MatFDColoringSetF(MatFDColoring,Vec);
    1059: PETSC_EXTERN PetscErrorCode MatFDColoringGetPerturbedColumns(MatFDColoring,PetscInt*,PetscInt*[]);

    1061: /*S
    1062:      MatTransposeColoring - Object for computing a sparse matrix product C=A*B^T via coloring

    1064:    Level: beginner

    1066:   Concepts: coloring, sparse matrix product

    1068: .seealso:  MatTransposeColoringCreate()
    1069: S*/
    1070: typedef struct _p_MatTransposeColoring* MatTransposeColoring;

    1072: PETSC_EXTERN PetscErrorCode MatTransposeColoringCreate(Mat,ISColoring,MatTransposeColoring *);
    1073: PETSC_EXTERN PetscErrorCode MatTransColoringApplySpToDen(MatTransposeColoring,Mat,Mat);
    1074: PETSC_EXTERN PetscErrorCode MatTransColoringApplyDenToSp(MatTransposeColoring,Mat,Mat);
    1075: PETSC_EXTERN PetscErrorCode MatTransposeColoringDestroy(MatTransposeColoring*);

    1077: /*
    1078:     These routines are for partitioning matrices: currently used only
    1079:   for adjacency matrix, MatCreateMPIAdj().
    1080: */

    1082: /*S
    1083:      MatPartitioning - Object for managing the partitioning of a matrix or graph

    1085:    Level: beginner

    1087:   Concepts: partitioning

    1089: .seealso:  MatPartitioningCreate(), MatPartitioningType
    1090: S*/
    1091: typedef struct _p_MatPartitioning* MatPartitioning;

    1093: /*J
    1094:     MatPartitioningType - String with the name of a PETSc matrix partitioning

    1096:    Level: beginner
    1097: dm
    1098: .seealso: MatPartitioningCreate(), MatPartitioning
    1099: J*/
    1100: typedef const char* MatPartitioningType;
    1101: #define MATPARTITIONINGCURRENT  "current"
    1102: #define MATPARTITIONINGSQUARE   "square"
    1103: #define MATPARTITIONINGPARMETIS "parmetis"
    1104: #define MATPARTITIONINGCHACO    "chaco"
    1105: #define MATPARTITIONINGPARTY    "party"
    1106: #define MATPARTITIONINGPTSCOTCH "ptscotch"

    1109: PETSC_EXTERN PetscErrorCode MatPartitioningCreate(MPI_Comm,MatPartitioning*);
    1110: PETSC_EXTERN PetscErrorCode MatPartitioningSetType(MatPartitioning,MatPartitioningType);
    1111: PETSC_EXTERN PetscErrorCode MatPartitioningSetNParts(MatPartitioning,PetscInt);
    1112: PETSC_EXTERN PetscErrorCode MatPartitioningSetAdjacency(MatPartitioning,Mat);
    1113: PETSC_EXTERN PetscErrorCode MatPartitioningSetVertexWeights(MatPartitioning,const PetscInt[]);
    1114: PETSC_EXTERN PetscErrorCode MatPartitioningSetPartitionWeights(MatPartitioning,const PetscReal []);
    1115: PETSC_EXTERN PetscErrorCode MatPartitioningApply(MatPartitioning,IS*);
    1116: PETSC_EXTERN PetscErrorCode MatPartitioningDestroy(MatPartitioning*);

    1118: PETSC_EXTERN PetscErrorCode MatPartitioningRegister(const char[],PetscErrorCode (*)(MatPartitioning));

    1120: PETSC_EXTERN PetscBool MatPartitioningRegisterAllCalled;

    1122: PETSC_EXTERN PetscErrorCode MatPartitioningRegisterAll(void);

    1124: PETSC_EXTERN PetscErrorCode MatPartitioningView(MatPartitioning,PetscViewer);
    1125: PETSC_EXTERN PetscErrorCode MatPartitioningSetFromOptions(MatPartitioning);
    1126: PETSC_EXTERN PetscErrorCode MatPartitioningGetType(MatPartitioning,MatPartitioningType*);

    1128: PETSC_EXTERN PetscErrorCode MatPartitioningParmetisSetCoarseSequential(MatPartitioning);
    1129: PETSC_EXTERN PetscErrorCode MatPartitioningParmetisGetEdgeCut(MatPartitioning, PetscInt *);

    1131: typedef enum { MP_CHACO_MULTILEVEL=1,MP_CHACO_SPECTRAL=2,MP_CHACO_LINEAR=4,MP_CHACO_RANDOM=5,MP_CHACO_SCATTERED=6 } MPChacoGlobalType;
    1132: PETSC_EXTERN const char *const MPChacoGlobalTypes[];
    1133: typedef enum { MP_CHACO_KERNIGHAN=1,MP_CHACO_NONE=2 } MPChacoLocalType;
    1134: PETSC_EXTERN const char *const MPChacoLocalTypes[];
    1135: typedef enum { MP_CHACO_LANCZOS=0,MP_CHACO_RQI=1 } MPChacoEigenType;
    1136: PETSC_EXTERN const char *const MPChacoEigenTypes[];

    1138: PETSC_EXTERN PetscErrorCode MatPartitioningChacoSetGlobal(MatPartitioning,MPChacoGlobalType);
    1139: PETSC_EXTERN PetscErrorCode MatPartitioningChacoGetGlobal(MatPartitioning,MPChacoGlobalType*);
    1140: PETSC_EXTERN PetscErrorCode MatPartitioningChacoSetLocal(MatPartitioning,MPChacoLocalType);
    1141: PETSC_EXTERN PetscErrorCode MatPartitioningChacoGetLocal(MatPartitioning,MPChacoLocalType*);
    1142: PETSC_EXTERN PetscErrorCode MatPartitioningChacoSetCoarseLevel(MatPartitioning,PetscReal);
    1143: PETSC_EXTERN PetscErrorCode MatPartitioningChacoSetEigenSolver(MatPartitioning,MPChacoEigenType);
    1144: PETSC_EXTERN PetscErrorCode MatPartitioningChacoGetEigenSolver(MatPartitioning,MPChacoEigenType*);
    1145: PETSC_EXTERN PetscErrorCode MatPartitioningChacoSetEigenTol(MatPartitioning,PetscReal);
    1146: PETSC_EXTERN PetscErrorCode MatPartitioningChacoGetEigenTol(MatPartitioning,PetscReal*);
    1147: PETSC_EXTERN PetscErrorCode MatPartitioningChacoSetEigenNumber(MatPartitioning,PetscInt);
    1148: PETSC_EXTERN PetscErrorCode MatPartitioningChacoGetEigenNumber(MatPartitioning,PetscInt*);

    1150: #define MP_PARTY_OPT "opt"
    1151: #define MP_PARTY_LIN "lin"
    1152: #define MP_PARTY_SCA "sca"
    1153: #define MP_PARTY_RAN "ran"
    1154: #define MP_PARTY_GBF "gbf"
    1155: #define MP_PARTY_GCF "gcf"
    1156: #define MP_PARTY_BUB "bub"
    1157: #define MP_PARTY_DEF "def"
    1158: PETSC_EXTERN PetscErrorCode MatPartitioningPartySetGlobal(MatPartitioning,const char*);
    1159: #define MP_PARTY_HELPFUL_SETS "hs"
    1160: #define MP_PARTY_KERNIGHAN_LIN "kl"
    1161: #define MP_PARTY_NONE "no"
    1162: PETSC_EXTERN PetscErrorCode MatPartitioningPartySetLocal(MatPartitioning,const char*);
    1163: PETSC_EXTERN PetscErrorCode MatPartitioningPartySetCoarseLevel(MatPartitioning,PetscReal);
    1164: PETSC_EXTERN PetscErrorCode MatPartitioningPartySetBipart(MatPartitioning,PetscBool);
    1165: PETSC_EXTERN PetscErrorCode MatPartitioningPartySetMatchOptimization(MatPartitioning,PetscBool);

    1167: typedef enum { MP_PTSCOTCH_QUALITY,MP_PTSCOTCH_SPEED,MP_PTSCOTCH_BALANCE,MP_PTSCOTCH_SAFETY,MP_PTSCOTCH_SCALABILITY } MPPTScotchStrategyType;
    1168: PETSC_EXTERN const char *const MPPTScotchStrategyTypes[];

    1170: PETSC_EXTERN PetscErrorCode MatPartitioningPTScotchSetImbalance(MatPartitioning,PetscReal);
    1171: PETSC_EXTERN PetscErrorCode MatPartitioningPTScotchGetImbalance(MatPartitioning,PetscReal*);
    1172: PETSC_EXTERN PetscErrorCode MatPartitioningPTScotchSetStrategy(MatPartitioning,MPPTScotchStrategyType);
    1173: PETSC_EXTERN PetscErrorCode MatPartitioningPTScotchGetStrategy(MatPartitioning,MPPTScotchStrategyType*);

    1175: /*
    1176:     These routines are for coarsening matrices:
    1177: */

    1179: /*S
    1180:      MatCoarsen - Object for managing the coarsening of a graph (symmetric matrix)

    1182:    Level: beginner

    1184:   Concepts: coarsen

    1186: .seealso:  MatCoarsenCreate), MatCoarsenType
    1187: S*/
    1188: typedef struct _p_MatCoarsen* MatCoarsen;

    1190: /*J
    1191:     MatCoarsenType - String with the name of a PETSc matrix coarsen

    1193:    Level: beginner

    1195: .seealso: MatCoarsenCreate(), MatCoarsen
    1196: J*/
    1197: typedef const char* MatCoarsenType;
    1198: #define MATCOARSENMIS  "mis"
    1199: #define MATCOARSENHEM  "hem"

    1201: /* linked list for aggregates */
    1202: typedef struct _PetscCDIntNd{
    1203:   struct _PetscCDIntNd *next;
    1204:   PetscInt             gid;
    1205: }PetscCDIntNd;

    1207: /* only used by node pool */
    1208: typedef struct _PetscCDArrNd{
    1209:   struct _PetscCDArrNd *next;
    1210:   struct _PetscCDIntNd *array;
    1211: }PetscCDArrNd;

    1213: typedef struct _PetscCoarsenData{
    1214:   PetscCDArrNd pool_list;  /* node pool */
    1215:   PetscCDIntNd *new_node;
    1216:   PetscInt     new_left;
    1217:   PetscInt     chk_sz;
    1218:   PetscCDIntNd *extra_nodes;
    1219:   PetscCDIntNd **array;  /* Array of lists */
    1220:   PetscInt     size;
    1221:   Mat          mat;  /* cache a Mat for communication data */
    1222: }PetscCoarsenData;

    1224: PETSC_EXTERN PetscErrorCode MatCoarsenCreate(MPI_Comm,MatCoarsen*);
    1225: PETSC_EXTERN PetscErrorCode MatCoarsenSetType(MatCoarsen,MatCoarsenType);
    1226: PETSC_EXTERN PetscErrorCode MatCoarsenSetAdjacency(MatCoarsen,Mat);
    1227: PETSC_EXTERN PetscErrorCode MatCoarsenSetGreedyOrdering(MatCoarsen,const IS);
    1228: PETSC_EXTERN PetscErrorCode MatCoarsenSetStrictAggs(MatCoarsen,PetscBool);
    1229: PETSC_EXTERN PetscErrorCode MatCoarsenSetVerbose(MatCoarsen,PetscInt);
    1230: PETSC_EXTERN PetscErrorCode MatCoarsenGetData( MatCoarsen, PetscCoarsenData ** );
    1231: PETSC_EXTERN PetscErrorCode MatCoarsenApply(MatCoarsen);
    1232: PETSC_EXTERN PetscErrorCode MatCoarsenDestroy(MatCoarsen*);

    1234: PETSC_EXTERN PetscErrorCode MatCoarsenRegister(const char[],PetscErrorCode (*)(MatCoarsen));

    1236: PETSC_EXTERN PetscBool MatCoarsenRegisterAllCalled;

    1238: PETSC_EXTERN PetscErrorCode MatCoarsenRegisterAll(void);

    1240: PETSC_EXTERN PetscErrorCode MatCoarsenView(MatCoarsen,PetscViewer);
    1241: PETSC_EXTERN PetscErrorCode MatCoarsenSetFromOptions(MatCoarsen);
    1242: PETSC_EXTERN PetscErrorCode MatCoarsenGetType(MatCoarsen,MatCoarsenType*);

    1244: PETSC_EXTERN PetscErrorCode MatMeshToVertexGraph(Mat,PetscInt,Mat*);
    1245: PETSC_EXTERN PetscErrorCode MatMeshToCellGraph(Mat,PetscInt,Mat*);

    1247: /*
    1248:     If you add entries here you must also add them to finclude/petscmat.h
    1249: */
    1250: typedef enum { MATOP_SET_VALUES=0,
    1251:                MATOP_GET_ROW=1,
    1252:                MATOP_RESTORE_ROW=2,
    1253:                MATOP_MULT=3,
    1254:                MATOP_MULT_ADD=4,
    1255:                MATOP_MULT_TRANSPOSE=5,
    1256:                MATOP_MULT_TRANSPOSE_ADD=6,
    1257:                MATOP_SOLVE=7,
    1258:                MATOP_SOLVE_ADD=8,
    1259:                MATOP_SOLVE_TRANSPOSE=9,
    1260:                MATOP_SOLVE_TRANSPOSE_ADD=10,
    1261:                MATOP_LUFACTOR=11,
    1262:                MATOP_CHOLESKYFACTOR=12,
    1263:                MATOP_SOR=13,
    1264:                MATOP_TRANSPOSE=14,
    1265:                MATOP_GETINFO=15,
    1266:                MATOP_EQUAL=16,
    1267:                MATOP_GET_DIAGONAL=17,
    1268:                MATOP_DIAGONAL_SCALE=18,
    1269:                MATOP_NORM=19,
    1270:                MATOP_ASSEMBLY_BEGIN=20,
    1271:                MATOP_ASSEMBLY_END=21,
    1272:                MATOP_SET_OPTION=22,
    1273:                MATOP_ZERO_ENTRIES=23,
    1274:                MATOP_ZERO_ROWS=24,
    1275:                MATOP_LUFACTOR_SYMBOLIC=25,
    1276:                MATOP_LUFACTOR_NUMERIC=26,
    1277:                MATOP_CHOLESKY_FACTOR_SYMBOLIC=27,
    1278:                MATOP_CHOLESKY_FACTOR_NUMERIC=28,
    1279:                MATOP_SETUP_PREALLOCATION=29,
    1280:                MATOP_ILUFACTOR_SYMBOLIC=30,
    1281:                MATOP_ICCFACTOR_SYMBOLIC=31,
    1282:                MATOP_GET_ARRAY=32,
    1283:                MATOP_RESTORE_ARRAY=33,
    1284:                MATOP_DUPLICATE=34,
    1285:                MATOP_FORWARD_SOLVE=35,
    1286:                MATOP_BACKWARD_SOLVE=36,
    1287:                MATOP_ILUFACTOR=37,
    1288:                MATOP_ICCFACTOR=38,
    1289:                MATOP_AXPY=39,
    1290:                MATOP_GET_SUBMATRICES=40,
    1291:                MATOP_INCREASE_OVERLAP=41,
    1292:                MATOP_GET_VALUES=42,
    1293:                MATOP_COPY=43,
    1294:                MATOP_GET_ROW_MAX=44,
    1295:                MATOP_SCALE=45,
    1296:                MATOP_SHIFT=46,
    1297:                MATOP_DIAGONAL_SET=47,
    1298:                MATOP_ILUDT_FACTOR=48,
    1299:                MATOP_SET_BLOCK_SIZE=49,
    1300:                MATOP_GET_ROW_IJ=50,
    1301:                MATOP_RESTORE_ROW_IJ=51,
    1302:                MATOP_GET_COLUMN_IJ=52,
    1303:                MATOP_RESTORE_COLUMN_IJ=53,
    1304:                MATOP_FDCOLORING_CREATE=54,
    1305:                MATOP_COLORING_PATCH=55,
    1306:                MATOP_SET_UNFACTORED=56,
    1307:                MATOP_PERMUTE=57,
    1308:                MATOP_SET_VALUES_BLOCKED=58,
    1309:                MATOP_GET_SUBMATRIX=59,
    1310:                MATOP_DESTROY=60,
    1311:                MATOP_VIEW=61,
    1312:                MATOP_CONVERT_FROM=62,
    1313:                MATOP_MATMAT_MULT=63,
    1314:                MATOP_MATMAT_MULT_SYMBOLIC=64,
    1315:                MATOP_MATMAT_MULT_NUMERIC=65,
    1316:                MATOP_SET_LOCAL_TO_GLOBAL_MAP=66,
    1317:                MATOP_SET_VALUES_LOCAL=67,
    1318:                MATOP_ZERO_ROWS_LOCAL=68,
    1319:                MATOP_GET_ROW_MAX_ABS=69,
    1320:                MATOP_GET_ROW_MIN_ABS=70,
    1321:                MATOP_CONVERT=71,
    1322:                MATOP_SET_COLORING=72,
    1323:                MATOP_PLACEHOLDER=73,
    1324:                MATOP_SET_VALUES_ADIFOR=74,
    1325:                MATOP_FD_COLORING_APPLY=75,
    1326:                MATOP_SET_FROM_OPTIONS=76,
    1327:                MATOP_MULT_CONSTRAINED=77,
    1328:                MATOP_MULT_TRANSPOSE_CONSTRAIN=78,
    1329:                MATOP_PERMUTE_SPARSIFY=79,
    1330:                MATOP_MULT_MULTIPLE=80,
    1331:                MATOP_SOLVE_MULTIPLE=81,
    1332:                MATOP_GET_INERTIA=82,
    1333:                MATOP_LOAD=83,
    1334:                MATOP_IS_SYMMETRIC=84,
    1335:                MATOP_IS_HERMITIAN=85,
    1336:                MATOP_IS_STRUCTURALLY_SYMMETRIC=86,
    1337:                MATOP_SET_VALUES_BLOCKEDLOCAL=87,
    1338:                MATOP_GET_VECS=88,
    1339:                MATOP_MAT_MULT=89,
    1340:                MATOP_MAT_MULT_SYMBOLIC=90,
    1341:                MATOP_MAT_MULT_NUMERIC=91,
    1342:                MATOP_PTAP=92,
    1343:                MATOP_PTAP_SYMBOLIC=93,
    1344:                MATOP_PTAP_NUMERIC=94,
    1345:                MATOP_MAT_TRANSPOSE_MULT=95,
    1346:                MATOP_MAT_TRANSPOSE_MULT_SYMBO=96,
    1347:                MATOP_MAT_TRANSPOSE_MULT_NUMER=97,
    1348:                MATOP_DUMMY98=98,
    1349:                MATOP_DUMMY99=99,
    1350:                MATOP_DUMMY100=100,
    1351:                MATOP_DUMMY101=101,
    1352:                MATOP_CONJUGATE=102,
    1353:                MATOP_SET_SIZES=103,
    1354:                MATOP_SET_VALUES_ROW=104,
    1355:                MATOP_REAL_PART=105,
    1356:                MATOP_IMAGINARY_PART=106,
    1357:                MATOP_GET_ROW_UPPER_TRIANGULAR=107,
    1358:                MATOP_RESTORE_ROW_UPPER_TRIANG=108,
    1359:                MATOP_MAT_SOLVE=109,
    1360:                MATOP_GET_REDUNDANT_MATRIX=110,
    1361:                MATOP_GET_ROW_MIN=111,
    1362:                MATOP_GET_COLUMN_VECTOR=112,
    1363:                MATOP_MISSING_DIAGONAL=113,
    1364:                MATOP_GET_SEQ_NONZERO_STRUCTUR=114,
    1365:                MATOP_CREATE=115,
    1366:                MATOP_GET_GHOSTS=116,
    1367:                MATOP_GET_LOCAL_SUB_MATRIX=117,
    1368:                MATOP_RESTORE_LOCALSUB_MATRIX=118,
    1369:                MATOP_MULT_DIAGONAL_BLOCK=119,
    1370:                MATOP_HERMITIAN_TRANSPOSE=120,
    1371:                MATOP_MULT_HERMITIAN_TRANSPOSE=121,
    1372:                MATOP_MULT_HERMITIAN_TRANS_ADD=122,
    1373:                MATOP_GET_MULTI_PROC_BLOCK=123,
    1374:                MATOP_GET_COLUMN_NORMS=125,
    1375:                MATOP_GET_SUB_MATRICES_PARALLE=128,
    1376:                MATOP_SET_VALUES_BATCH=129,
    1377:                MATOP_TRANSPOSE_MAT_MULT=130,
    1378:                MATOP_TRANSPOSE_MAT_MULT_SYMBO=131,
    1379:                MATOP_TRANSPOSE_MAT_MULT_NUMER=132,
    1380:                MATOP_TRANSPOSE_COLORING_CREAT=133,
    1381:                MATOP_TRANS_COLORING_APPLY_SPT=134,
    1382:                MATOP_TRANS_COLORING_APPLY_DEN=135,
    1383:                MATOP_RART=136,
    1384:                MATOP_RART_SYMBOLIC=137,
    1385:                MATOP_RART_NUMERIC=138,
    1386:                MATOP_SET_BLOCK_SIZES=139,
    1387:                MATOP_AYPX=140
    1388:              } MatOperation;
    1389: PETSC_EXTERN PetscErrorCode MatHasOperation(Mat,MatOperation,PetscBool *);
    1390: PETSC_EXTERN PetscErrorCode MatShellSetOperation(Mat,MatOperation,void(*)(void));
    1391: PETSC_EXTERN PetscErrorCode MatShellGetOperation(Mat,MatOperation,void(**)(void));
    1392: PETSC_EXTERN PetscErrorCode MatShellSetContext(Mat,void*);

    1394: /*
    1395:    Codes for matrices stored on disk. By default they are
    1396:    stored in a universal format. By changing the format with
    1397:    PetscViewerSetFormat(viewer,PETSC_VIEWER_NATIVE); the matrices will
    1398:    be stored in a way natural for the matrix, for example dense matrices
    1399:    would be stored as dense. Matrices stored this way may only be
    1400:    read into matrices of the same type.
    1401: */
    1402: #define MATRIX_BINARY_FORMAT_DENSE -1

    1404: PETSC_EXTERN PetscErrorCode MatMPIBAIJSetHashTableFactor(Mat,PetscReal);
    1405: PETSC_EXTERN PetscErrorCode MatISGetLocalMat(Mat,Mat*);
    1406: PETSC_EXTERN PetscErrorCode MatISSetLocalMat(Mat,Mat);

    1408: /*S
    1409:      MatNullSpace - Object that removes a null space from a vector, i.e.
    1410:          orthogonalizes the vector to a subsapce

    1412:    Level: advanced

    1414:   Concepts: matrix; linear operator, null space

    1416:   Users manual sections:
    1417: .   Section 4.17 Solving Singular Systems

    1419: .seealso:  MatNullSpaceCreate()
    1420: S*/
    1421: typedef struct _p_MatNullSpace* MatNullSpace;

    1423: PETSC_EXTERN PetscErrorCode MatNullSpaceCreate(MPI_Comm,PetscBool ,PetscInt,const Vec[],MatNullSpace*);
    1424: PETSC_EXTERN PetscErrorCode MatNullSpaceSetFunction(MatNullSpace,PetscErrorCode (*)(MatNullSpace,Vec,void*),void*);
    1425: PETSC_EXTERN PetscErrorCode MatNullSpaceDestroy(MatNullSpace*);
    1426: PETSC_EXTERN PetscErrorCode MatNullSpaceRemove(MatNullSpace,Vec,Vec*);
    1427: PETSC_EXTERN PetscErrorCode MatGetNullSpace(Mat, MatNullSpace *);
    1428: PETSC_EXTERN PetscErrorCode MatSetNullSpace(Mat,MatNullSpace);
    1429: PETSC_EXTERN PetscErrorCode MatSetNearNullSpace(Mat,MatNullSpace);
    1430: PETSC_EXTERN PetscErrorCode MatGetNearNullSpace(Mat,MatNullSpace*);
    1431: PETSC_EXTERN PetscErrorCode MatNullSpaceTest(MatNullSpace,Mat,PetscBool  *);
    1432: PETSC_EXTERN PetscErrorCode MatNullSpaceView(MatNullSpace,PetscViewer);
    1433: PETSC_EXTERN PetscErrorCode MatNullSpaceGetVecs(MatNullSpace,PetscBool*,PetscInt*,const Vec**);
    1434: PETSC_EXTERN PetscErrorCode MatNullSpaceCreateRigidBody(Vec,MatNullSpace*);

    1436: PETSC_EXTERN PetscErrorCode MatReorderingSeqSBAIJ(Mat,IS);
    1437: PETSC_EXTERN PetscErrorCode MatMPISBAIJSetHashTableFactor(Mat,PetscReal);
    1438: PETSC_EXTERN PetscErrorCode MatSeqSBAIJSetColumnIndices(Mat,PetscInt *);
    1439: PETSC_EXTERN PetscErrorCode MatSeqBAIJInvertBlockDiagonal(Mat);

    1441: PETSC_EXTERN PetscErrorCode MatCreateMAIJ(Mat,PetscInt,Mat*);
    1442: PETSC_EXTERN PetscErrorCode MatMAIJRedimension(Mat,PetscInt,Mat*);
    1443: PETSC_EXTERN PetscErrorCode MatMAIJGetAIJ(Mat,Mat*);

    1445: PETSC_EXTERN PetscErrorCode MatComputeExplicitOperator(Mat,Mat*);

    1447: PETSC_EXTERN PetscErrorCode MatDiagonalScaleLocal(Mat,Vec);

    1449: PETSC_EXTERN PetscErrorCode MatCreateMFFD(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,Mat*);
    1450: PETSC_EXTERN PetscErrorCode MatMFFDSetBase(Mat,Vec,Vec);
    1451: PETSC_EXTERN PetscErrorCode MatMFFDSetFunction(Mat,PetscErrorCode(*)(void*,Vec,Vec),void*);
    1452: PETSC_EXTERN PetscErrorCode MatMFFDSetFunctioni(Mat,PetscErrorCode (*)(void*,PetscInt,Vec,PetscScalar*));
    1453: PETSC_EXTERN PetscErrorCode MatMFFDSetFunctioniBase(Mat,PetscErrorCode (*)(void*,Vec));
    1454: PETSC_EXTERN PetscErrorCode MatMFFDAddNullSpace(Mat,MatNullSpace);
    1455: PETSC_EXTERN PetscErrorCode MatMFFDSetHHistory(Mat,PetscScalar[],PetscInt);
    1456: PETSC_EXTERN PetscErrorCode MatMFFDResetHHistory(Mat);
    1457: PETSC_EXTERN PetscErrorCode MatMFFDSetFunctionError(Mat,PetscReal);
    1458: PETSC_EXTERN PetscErrorCode MatMFFDSetPeriod(Mat,PetscInt);
    1459: PETSC_EXTERN PetscErrorCode MatMFFDGetH(Mat,PetscScalar *);
    1460: PETSC_EXTERN PetscErrorCode MatMFFDSetOptionsPrefix(Mat,const char[]);
    1461: PETSC_EXTERN PetscErrorCode MatMFFDCheckPositivity(void*,Vec,Vec,PetscScalar*);
    1462: PETSC_EXTERN PetscErrorCode MatMFFDSetCheckh(Mat,PetscErrorCode (*)(void*,Vec,Vec,PetscScalar*),void*);

    1464: /*S
    1465:     MatMFFD - A data structured used to manage the computation of the h differencing parameter for matrix-free
    1466:               Jacobian vector products

    1468:     Notes: MATMFFD is a specific MatType which uses the MatMFFD data structure

    1470:            MatMFFD*() methods actually take the Mat as their first argument. Not a MatMFFD data structure

    1472:     Level: developer

    1474: .seealso: MATMFFD, MatCreateMFFD(), MatMFFDSetFuction(), MatMFFDSetType(), MatMFFDRegister()
    1475: S*/
    1476: typedef struct _p_MatMFFD* MatMFFD;

    1478: /*J
    1479:     MatMFFDType - algorithm used to compute the h used in computing matrix-vector products via differencing of the function

    1481:    Level: beginner

    1483: .seealso: MatMFFDSetType(), MatMFFDRegister()
    1484: J*/
    1485: typedef const char* MatMFFDType;
    1486: #define MATMFFD_DS  "ds"
    1487: #define MATMFFD_WP  "wp"

    1489: PETSC_EXTERN PetscErrorCode MatMFFDSetType(Mat,MatMFFDType);
    1490: PETSC_EXTERN PetscErrorCode MatMFFDRegister(const char[],PetscErrorCode (*)(MatMFFD));

    1492: PETSC_EXTERN PetscErrorCode MatMFFDRegisterAll(void);
    1493: PETSC_EXTERN PetscErrorCode MatMFFDDSSetUmin(Mat,PetscReal);
    1494: PETSC_EXTERN PetscErrorCode MatMFFDWPSetComputeNormU(Mat,PetscBool );

    1496: PETSC_EXTERN PetscErrorCode PetscViewerMathematicaPutMatrix(PetscViewer, PetscInt, PetscInt, PetscReal *);
    1497: PETSC_EXTERN PetscErrorCode PetscViewerMathematicaPutCSRMatrix(PetscViewer, PetscInt, PetscInt, PetscInt *, PetscInt *, PetscReal *);

    1499: /*
    1500:    PETSc interface to MUMPS
    1501: */
    1502: #ifdef PETSC_HAVE_MUMPS
    1503: PETSC_EXTERN PetscErrorCode MatMumpsSetIcntl(Mat,PetscInt,PetscInt);
    1504: PETSC_EXTERN PetscErrorCode MatMumpsSetCntl(Mat,PetscInt,PetscReal);
    1505: #endif

    1507: /*
    1508:    PETSc interface to SUPERLU
    1509: */
    1510: #ifdef PETSC_HAVE_SUPERLU
    1511: PETSC_EXTERN PetscErrorCode MatSuperluSetILUDropTol(Mat,PetscReal);
    1512: #endif

    1514: #if defined PETSC_HAVE_TXPETSCGPU

    1516: /*E
    1517:     MatCUSPARSEStorageFormat - indicates the storage format for CUSPARSE (GPU)
    1518:     matrices. Requires the txpetscgpu package to use. Configure with
    1519:     --download-txpetscgpu to build/install petsc with the txpetscgpu library.

    1521:     Not Collective

    1523: +   MAT_CUSPARSE_CSR - Compressed Sparse Row
    1524: .   MAT_CUSPARSE_ELL - Ellpack
    1525: -   MAT_CUSPARSE_HYB - Hybrid, a combination of Ellpack and Coordinate format.

    1527:     Level: intermediate

    1529:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    1531: .seealso: MatCUSPARSESetFormat(), MatCUSPARSEFormatOperation
    1532: E*/

    1534: typedef enum {MAT_CUSPARSE_CSR, MAT_CUSPARSE_ELL, MAT_CUSPARSE_HYB} MatCUSPARSEStorageFormat;

    1536: /* these will be strings associated with enumerated type defined above */
    1537: PETSC_EXTERN const char *const MatCUSPARSEStorageFormats[];

    1539: /*E
    1540:     MatCUSPARSEFormatOperation - indicates the operation of CUSPARSE (GPU)
    1541:     matrices whose operation should use a particular storage format. Requires
    1542:     the txpetscgpu package to use. Configure with --download-txpetscgpu to
    1543:     build/install petsc with the txpetscgpu library.

    1545:     Not Collective

    1547: +   MAT_CUSPARSE_MULT_DIAG - sets the storage format for the diagonal matrix in the parallel MatMult
    1548: .   MAT_CUSPARSE_MULT_OFFDIAG - sets the storage format for the offdiagonal matrix in the parallel MatMult
    1549: .   MAT_CUSPARSE_MULT - sets the storage format for the entire matrix in the serial (single GPU) MatMult
    1550: .   MAT_CUSPARSE_SOLVE - sets the storage format for the triangular factors in the serial (single GPU) MatSolve
    1551: -   MAT_CUSPARSE_ALL - sets the storage format for all CUSPARSE (GPU) matrices

    1553:     Level: intermediate

    1555: .seealso: MatCUSPARSESetFormat(), MatCUSPARSEStorageFormat
    1556: E*/
    1557: typedef enum {MAT_CUSPARSE_MULT_DIAG, MAT_CUSPARSE_MULT_OFFDIAG, MAT_CUSPARSE_MULT, MAT_CUSPARSE_SOLVE, MAT_CUSPARSE_ALL} MatCUSPARSEFormatOperation;

    1559: PETSC_EXTERN PetscErrorCode MatCreateSeqAIJCUSPARSE(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);
    1560: PETSC_EXTERN PetscErrorCode MatCreateAIJCUSPARSE(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);
    1561: PETSC_EXTERN PetscErrorCode MatCUSPARSESetFormat(Mat,MatCUSPARSEFormatOperation,MatCUSPARSEStorageFormat);

    1563: #endif

    1565: #if defined(PETSC_HAVE_CUSP)
    1566: PETSC_EXTERN PetscErrorCode MatCreateSeqAIJCUSP(MPI_Comm,PetscInt,PetscInt,PetscInt,const PetscInt[],Mat*);
    1567: PETSC_EXTERN PetscErrorCode MatCreateAIJCUSP(MPI_Comm,PetscInt,PetscInt,PetscInt,PetscInt,PetscInt,const PetscInt[],PetscInt,const PetscInt[],Mat*);

    1569: /*E
    1570:     MatCUSPStorageFormat - indicates the storage format for CUSP (GPU)
    1571:     matrices. Requires the txpetscgpu package to use. Configure with
    1572:     --download-txpetscgpu to build/install petsc with the txpetscgpu library.

    1574:     Not Collective

    1576: +   MAT_CUSP_CSR - Compressed Sparse Row
    1577: .   MAT_CUSP_DIA - Diagonal
    1578: -   MAT_CUSP_ELL - Ellpack

    1580:     Level: intermediate

    1582:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    1584: .seealso: MatCUSPSetFormat(), MatCUSPFormatOperation
    1585: E*/
    1586: typedef enum {MAT_CUSP_CSR, MAT_CUSP_DIA, MAT_CUSP_ELL} MatCUSPStorageFormat;

    1588: /* these will be strings associated with enumerated type defined above */
    1589: PETSC_EXTERN const char *const MatCUSPStorageFormats[];

    1591: /*E
    1592:     MatCUSPFormatOperation - indicates the operation of CUSP (GPU)
    1593:     matrices whose operation should use a particular storage format. Requires
    1594:     the txpetscgpu package to use. Configure with --download-txpetscgpu to
    1595:     build/install petsc with the txpetscgpu library.

    1597:     Not Collective

    1599: +   MAT_CUSP_MULT_DIAG - sets the storage format for the diagonal matrix in the parallel MatMult
    1600: .   MAT_CUSP_MULT_OFFDIAG - sets the storage format for the offdiagonal matrix in the parallel MatMult
    1601: .   MAT_CUSP_MULT - sets the storage format for the entire matrix in the serial (single GPU) MatMult
    1602: .   MAT_CUSP_SOLVE - sets the storage format for the triangular factors in the serial (single GPU) MatSolve
    1603: -   MAT_CUSP_ALL - sets the storage format for all CUSP (GPU) matrices

    1605:     Level: intermediate

    1607:    Any additions/changes here MUST also be made in include/finclude/petscmat.h

    1609: .seealso: MatCUSPSetFormat(), MatCUSPStorageFormat
    1610: E*/
    1611: typedef enum {MAT_CUSP_MULT_DIAG, MAT_CUSP_MULT_OFFDIAG, MAT_CUSP_MULT, MAT_CUSP_SOLVE, MAT_CUSP_ALL} MatCUSPFormatOperation;

    1613: PETSC_EXTERN PetscErrorCode MatCUSPSetFormat(Mat,MatCUSPFormatOperation,MatCUSPStorageFormat);
    1614: #endif

    1616: /*
    1617:    PETSc interface to FFTW
    1618: */
    1619: #if defined(PETSC_HAVE_FFTW)
    1620: PETSC_EXTERN PetscErrorCode VecScatterPetscToFFTW(Mat,Vec,Vec);
    1621: PETSC_EXTERN PetscErrorCode VecScatterFFTWToPetsc(Mat,Vec,Vec);
    1622: PETSC_EXTERN PetscErrorCode MatGetVecsFFTW(Mat,Vec*,Vec*,Vec*);
    1623: #endif

    1625: #if defined(PETSC_HAVE_ELEMENTAL)
    1626: PETSC_EXTERN PetscErrorCode PetscElementalInitializePackage(void);
    1627: PETSC_EXTERN PetscErrorCode PetscElementalFinalizePackage(void);
    1628: #endif

    1630: PETSC_EXTERN PetscErrorCode MatCreateNest(MPI_Comm,PetscInt,const IS[],PetscInt,const IS[],const Mat[],Mat*);
    1631: PETSC_EXTERN PetscErrorCode MatNestGetSize(Mat,PetscInt*,PetscInt*);
    1632: PETSC_EXTERN PetscErrorCode MatNestGetISs(Mat,IS[],IS[]);
    1633: PETSC_EXTERN PetscErrorCode MatNestGetLocalISs(Mat,IS[],IS[]);
    1634: PETSC_EXTERN PetscErrorCode MatNestGetSubMats(Mat,PetscInt*,PetscInt*,Mat***);
    1635: PETSC_EXTERN PetscErrorCode MatNestGetSubMat(Mat,PetscInt,PetscInt,Mat*);
    1636: PETSC_EXTERN PetscErrorCode MatNestSetVecType(Mat,VecType);
    1637: PETSC_EXTERN PetscErrorCode MatNestSetSubMats(Mat,PetscInt,const IS[],PetscInt,const IS[],const Mat[]);
    1638: PETSC_EXTERN PetscErrorCode MatNestSetSubMat(Mat,PetscInt,PetscInt,Mat);

    1640: PETSC_EXTERN PetscErrorCode MatChop(Mat,PetscReal);

    1642: #endif