Actual source code: petscmat.h

  1: /* $Id: petscmat.h,v 1.228 2001/09/07 20:09:08 bsmith Exp $ */
  2: /*
  3:      Include file for the matrix component of PETSc
  4: */
  5: #ifndef __PETSCMAT_H
 7:  #include petscvec.h

  9: /*S
 10:      Mat - Abstract PETSc matrix object

 12:    Level: beginner

 14:   Concepts: matrix; linear operator

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

 20: /*E
 21:     MatType - String with the name of a PETSc matrix or the creation function
 22:        with an optional dynamic library name, for example
 23:        http://www.mcs.anl.gov/petsc/lib.a:mymatcreate()

 25:    Level: beginner

 27: .seealso: MatSetType(), Mat
 28: E*/
 29: #define MATSAME            "same"
 30: #define MATSEQMAIJ         "seqmaij"
 31: #define MATMPIMAIJ         "mpimaij"
 32: #define MATMAIJ            "maij"
 33: #define MATIS              "is"
 34: #define MATMPIROWBS        "mpirowbs"
 35: #define MATSEQAIJ          "seqaij"
 36: #define MATMPIAIJ          "mpiaij"
 37: #define MATAIJ             "aij"
 38: #define MATSHELL           "shell"
 39: #define MATSEQBDIAG        "seqbdiag"
 40: #define MATMPIBDIAG        "mpibdiag"
 41: #define MATBDIAG           "bdiag"
 42: #define MATSEQDENSE        "seqdense"
 43: #define MATMPIDENSE        "mpidense"
 44: #define MATDENSE           "dense"
 45: #define MATSEQBAIJ         "seqbaij"
 46: #define MATMPIBAIJ         "mpibaij"
 47: #define MATBAIJ            "baij"
 48: #define MATMPIADJ          "mpiadj"
 49: #define MATSEQSBAIJ        "seqsbaij"
 50: #define MATMPISBAIJ        "mpisbaij"
 51: #define MATSBAIJ           "sbaij"
 52: #define MATDAAD            "daad"
 53: #define MATMFFD            "mffd"
 54: #define MATESI             "esi"
 55: #define MATPETSCESI        "petscesi"
 56: #define MATNORMAL          "normal"
 57: #define MATSEQAIJSPOOLES   "seqaijspooles"
 58: #define MATMPIAIJSPOOLES   "mpiaijspooles"
 59: #define MATSEQSBAIJSPOOLES "seqsbaijspooles"
 60: #define MATMPISBAIJSPOOLES "mpisbaijspooles"
 61: #define MATSUPERLU         "superlu"
 62: #define MATSUPERLU_DIST    "superlu_dist"
 63: #define MATUMFPACK         "umfpack"
 64: #define MATESSL            "essl"
 65: #define MATLUSOL           "lusol"
 66: #define MATAIJMUMPS        "aijmumps"
 67: #define MATSBAIJMUMPS      "sbaijmumps"
 68: #define MATDSCPACK         "dscpack"
 69: typedef char* MatType;

 71: #define MAT_SER_SEQAIJ_BINARY "seqaij_binary"
 72: #define MAT_SER_MPIAIJ_BINARY "mpiaij_binary"
 73: typedef char *MatSerializeType;

 75: /* Logging support */
 76: #define    MAT_FILE_COOKIE 1211216    /* used to indicate matrices in binary files */
 77: extern int MAT_COOKIE;
 78: extern int MATSNESMFCTX_COOKIE;
 79: extern int MAT_FDCOLORING_COOKIE;
 80: extern int MAT_PARTITIONING_COOKIE;
 81: extern int MAT_NULLSPACE_COOKIE;
 82: extern int MAT_Mult, MAT_MultMatrixFree, MAT_Mults, MAT_MultConstrained, MAT_MultAdd, MAT_MultTranspose;
 83: extern int MAT_MultTransposeConstrained, MAT_MultTransposeAdd, MAT_Solve, MAT_Solves, MAT_SolveAdd, MAT_SolveTranspose;
 84: extern int MAT_SolveTransposeAdd, MAT_Relax, MAT_ForwardSolve, MAT_BackwardSolve, MAT_LUFactor, MAT_LUFactorSymbolic;
 85: extern int MAT_LUFactorNumeric, MAT_CholeskyFactor, MAT_CholeskyFactorSymbolic, MAT_CholeskyFactorNumeric, MAT_ILUFactor;
 86: extern int MAT_ILUFactorSymbolic, MAT_ICCFactorSymbolic, MAT_Copy, MAT_Convert, MAT_Scale, MAT_AssemblyBegin;
 87: extern int MAT_AssemblyEnd, MAT_SetValues, MAT_GetValues, MAT_GetRow, MAT_GetSubMatrices, MAT_GetColoring, MAT_GetOrdering;
 88: extern int MAT_IncreaseOverlap, MAT_Partitioning, MAT_ZeroEntries, MAT_Load, MAT_View, MAT_AXPY, MAT_FDColoringCreate;
 89: extern int MAT_FDColoringApply, MAT_Transpose, MAT_FDColoringFunction;

 91: EXTERN int MatInitializePackage(char *);

 93: EXTERN int MatCreate(MPI_Comm,int,int,int,int,Mat*);
 94: EXTERN int MatSetType(Mat,MatType);
 95: EXTERN int MatSetFromOptions(Mat);
 96: EXTERN int MatSetUpPreallocation(Mat);
 97: EXTERN int MatRegisterAll(char*);
 98: EXTERN int MatRegister(char*,char*,char*,int(*)(Mat));
 99: EXTERN int MatSerializeRegister(const char [], const char [], const char [], int (*)(MPI_Comm, Mat *, PetscViewer, PetscTruth));

101: /*MC
102:    MatRegisterDynamic - Adds a new matrix type

104:    Synopsis:
105:    int MatRegisterDynamic(char *name,char *path,char *name_create,int (*routine_create)(Mat))

107:    Not Collective

109:    Input Parameters:
110: +  name - name of a new user-defined matrix type
111: .  path - path (either absolute or relative) the library containing this solver
112: .  name_create - name of routine to create method context
113: -  routine_create - routine to create method context

115:    Notes:
116:    MatRegisterDynamic() may be called multiple times to add several user-defined solvers.

118:    If dynamic libraries are used, then the fourth input argument (routine_create)
119:    is ignored.

121:    Sample usage:
122: .vb
123:    MatRegisterDynamic("my_mat",/home/username/my_lib/lib/libO/solaris/mylib.a,
124:                "MyMatCreate",MyMatCreate);
125: .ve

127:    Then, your solver can be chosen with the procedural interface via
128: $     MatSetType(Mat,"my_mat")
129:    or at runtime via the option
130: $     -mat_type my_mat

132:    Level: advanced

134:    Notes: ${PETSC_ARCH} and ${BOPT} occuring in pathname will be replaced with appropriate values.
135:          If your function is not being put into a shared library then use VecRegister() instead

137: .keywords: Mat, register

139: .seealso: MatRegisterAll(), MatRegisterDestroy()

141: M*/
142: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
143: #define MatRegisterDynamic(a,b,c,d) MatRegister(a,b,c,0)
144: #else
145: #define MatRegisterDynamic(a,b,c,d) MatRegister(a,b,c,d)
146: #endif

148: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
149: #define MatSerializeRegisterDynamic(a,b,c,d) MatSerializeRegister(a,b,c,0)
150: #else
151: #define MatSerializeRegisterDynamic(a,b,c,d) MatSerializeRegister(a,b,c,d)
152: #endif

154: extern PetscTruth MatRegisterAllCalled;
155: extern PetscFList MatList;

157: EXTERN PetscFList MatSerializeList;
158: EXTERN int MatSerializeRegisterAll(const char []);
159: EXTERN int MatSerializeRegisterDestroy(void);
160: EXTERN int MatSerializeRegisterAllCalled;
161: EXTERN int MatSerialize(MPI_Comm, Mat *, PetscViewer, PetscTruth);
162: EXTERN int MatSetSerializeType(Mat, MatSerializeType);

164: EXTERN int MatCreateSeqDense(MPI_Comm,int,int,PetscScalar[],Mat*);
165: EXTERN int MatCreateMPIDense(MPI_Comm,int,int,int,int,PetscScalar[],Mat*);
166: EXTERN int MatCreateSeqAIJ(MPI_Comm,int,int,int,const int[],Mat*);
167: EXTERN int MatCreateMPIAIJ(MPI_Comm,int,int,int,int,int,const int[],int,const int[],Mat*);
168: EXTERN int MatCreateMPIRowbs(MPI_Comm,int,int,int,const int[],Mat*);
169: EXTERN int MatCreateSeqBDiag(MPI_Comm,int,int,int,int,const int[],PetscScalar*[],Mat*);
170: EXTERN int MatCreateMPIBDiag(MPI_Comm,int,int,int,int,int,const int[],PetscScalar*[],Mat*);
171: EXTERN int MatCreateSeqBAIJ(MPI_Comm,int,int,int,int,const int[],Mat*);
172: EXTERN int MatCreateMPIBAIJ(MPI_Comm,int,int,int,int,int,int,const int[],int,const int[],Mat*);
173: EXTERN int MatCreateMPIAdj(MPI_Comm,int,int,int[],int[],int[],Mat*);
174: EXTERN int MatCreateSeqSBAIJ(MPI_Comm,int,int,int,int,const int[],Mat*);
175: EXTERN int MatCreateMPISBAIJ(MPI_Comm,int,int,int,int,int,int,const int[],int,const int[],Mat*);
176: EXTERN int MatCreateShell(MPI_Comm,int,int,int,int,void *,Mat*);
177: EXTERN int MatCreateAdic(MPI_Comm,int,int,int,int,int,void (*)(void),Mat*);
178: EXTERN int MatCreateNormal(Mat,Mat*);
179: EXTERN int MatDestroy(Mat);

181: EXTERN int MatPrintHelp(Mat);
182: EXTERN int MatGetPetscMaps(Mat,PetscMap*,PetscMap*);

184: /* ------------------------------------------------------------*/
185: EXTERN int MatSetValues(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);
186: EXTERN int MatSetValuesBlocked(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);

188: /*S
189:      MatStencil - Data structure (C struct) for storing information about a single row or
190:         column of a matrix as index on an associated grid.

192:    Level: beginner

194:   Concepts: matrix; linear operator

196: .seealso:  MatSetValuesStencil(), MatSetStencil()
197: S*/
198: typedef struct {
199:   int k,j,i,c;
200: } MatStencil;

202: EXTERN int MatSetValuesStencil(Mat,int,const MatStencil[],int,const MatStencil[],const PetscScalar[],InsertMode);
203: EXTERN int MatSetValuesBlockedStencil(Mat,int,const MatStencil[],int,const MatStencil[],const PetscScalar[],InsertMode);
204: EXTERN int MatSetStencil(Mat,int,const int[],const int[],int);

206: EXTERN int MatSetColoring(Mat,ISColoring);
207: EXTERN int MatSetValuesAdic(Mat,void*);
208: EXTERN int MatSetValuesAdifor(Mat,int,void*);

210: /*E
211:     MatAssemblyType - Indicates if the matrix is now to be used, or if you plan 
212:      to continue to add values to it

214:     Level: beginner

216: .seealso: MatAssemblyBegin(), MatAssemblyEnd()
217: E*/
218: typedef enum {MAT_FLUSH_ASSEMBLY=1,MAT_FINAL_ASSEMBLY=0} MatAssemblyType;
219: EXTERN int MatAssemblyBegin(Mat,MatAssemblyType);
220: EXTERN int MatAssemblyEnd(Mat,MatAssemblyType);
221: EXTERN int MatAssembled(Mat,PetscTruth*);

223: /*MC
224:    MatSetValue - Set a single entry into a matrix.

226:    Synopsis:
227:    int MatSetValue(Mat m,int row,int col,PetscScalar value,InsertMode mode);

229:    Not collective

231:    Input Parameters:
232: +  m - the matrix
233: .  row - the row location of the entry
234: .  col - the column location of the entry
235: .  value - the value to insert
236: -  mode - either INSERT_VALUES or ADD_VALUES

238:    Notes: 
239:    For efficiency one should use MatSetValues() and set several or many
240:    values simultaneously if possible.

242:    Note that MatSetValue() does NOT return an error code (since this
243:    is checked internally).

245:    Level: beginner

247: .seealso: MatSetValues(), MatSetValueLocal()
248: M*/
249: #define MatSetValue(v,i,j,va,mode) \
250: 0; {int _ierr,_row = i,_col = j; PetscScalar _va = va; \
251:   _MatSetValues(v,1,&_row,1,&_col,&_va,mode);CHKERRQ(_ierr); \
252: }

254: #define MatGetValue(v,i,j,va) \
255: 0; {int _ierr,_row = i,_col = j; \
256:   _MatGetValues(v,1,&_row,1,&_col,&va);CHKERRQ(_ierr); \
257: }

259: #define MatSetValueLocal(v,i,j,va,mode) \
260: 0; {int _ierr,_row = i,_col = j; PetscScalar _va = va; \
261:   _MatSetValuesLocal(v,1,&_row,1,&_col,&_va,mode);CHKERRQ(_ierr); \
262: }

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

267:     Level: beginner

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

271: .seealso: MatSetOption()
272: E*/
273: typedef enum {MAT_ROW_ORIENTED=1,MAT_COLUMN_ORIENTED=2,MAT_ROWS_SORTED=4,
274:               MAT_COLUMNS_SORTED=8,MAT_NO_NEW_NONZERO_LOCATIONS=16,
275:               MAT_YES_NEW_NONZERO_LOCATIONS=32,MAT_SYMMETRIC=64,
276:               MAT_STRUCTURALLY_SYMMETRIC=65,MAT_NO_NEW_DIAGONALS=66,
277:               MAT_YES_NEW_DIAGONALS=67,MAT_INODE_LIMIT_1=68,MAT_INODE_LIMIT_2=69,
278:               MAT_INODE_LIMIT_3=70,MAT_INODE_LIMIT_4=71,MAT_INODE_LIMIT_5=72,
279:               MAT_IGNORE_OFF_PROC_ENTRIES=73,MAT_ROWS_UNSORTED=74,
280:               MAT_COLUMNS_UNSORTED=75,MAT_NEW_NONZERO_LOCATION_ERR=76,
281:               MAT_NEW_NONZERO_ALLOCATION_ERR=77,MAT_USE_HASH_TABLE=78,
282:               MAT_KEEP_ZEROED_ROWS=79,MAT_IGNORE_ZERO_ENTRIES=80,MAT_USE_INODES=81,
283:               MAT_DO_NOT_USE_INODES=82} MatOption;
284: EXTERN int MatSetOption(Mat,MatOption);
285: EXTERN int MatGetType(Mat,MatType*);

287: EXTERN int MatGetValues(Mat,int,const int[],int,const int[],PetscScalar[]);
288: EXTERN int MatGetRow(Mat,int,int *,int *[],PetscScalar*[]);
289: EXTERN int MatRestoreRow(Mat,int,int *,int *[],PetscScalar*[]);
290: EXTERN int MatGetColumn(Mat,int,int *,int *[],PetscScalar*[]);
291: EXTERN int MatRestoreColumn(Mat,int,int *,int *[],PetscScalar*[]);
292: EXTERN int MatGetColumnVector(Mat,Vec,int);
293: EXTERN int MatGetArray(Mat,PetscScalar *[]);
294: EXTERN int MatRestoreArray(Mat,PetscScalar *[]);
295: EXTERN int MatGetBlockSize(Mat,int *);

297: EXTERN int MatMult(Mat,Vec,Vec);
298: EXTERN int MatMultAdd(Mat,Vec,Vec,Vec);
299: EXTERN int MatMultTranspose(Mat,Vec,Vec);
300: EXTERN int MatIsSymmetric(Mat,Mat,PetscTruth*);
301: EXTERN int MatMultTransposeAdd(Mat,Vec,Vec,Vec);
302: EXTERN int MatMultConstrained(Mat,Vec,Vec);
303: EXTERN int MatMultTransposeConstrained(Mat,Vec,Vec);

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

309:     Level: beginner

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

313: .seealso: MatDuplicate()
314: E*/
315: typedef enum {MAT_DO_NOT_COPY_VALUES,MAT_COPY_VALUES} MatDuplicateOption;

317: EXTERN int MatConvertRegister(char*,char*,char*,int (*)(Mat,MatType,Mat*));
318: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
319: #define MatConvertRegisterDynamic(a,b,c,d) MatConvertRegister(a,b,c,0)
320: #else
321: #define MatConvertRegisterDynamic(a,b,c,d) MatConvertRegister(a,b,c,d)
322: #endif
323: EXTERN int        MatConvertRegisterAll(char*);
324: EXTERN int        MatConvertRegisterDestroy(void);
325: extern PetscTruth MatConvertRegisterAllCalled;
326: extern PetscFList MatConvertList;
327: EXTERN int        MatConvert(Mat,MatType,Mat*);
328: EXTERN int        MatDuplicate(Mat,MatDuplicateOption,Mat*);

330: /*E
331:     MatStructure - Indicates if the matrix has the same nonzero structure

333:     Level: beginner

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

337: .seealso: MatCopy(), SLESSetOperators(), PCSetOperators()
338: E*/
339: typedef enum {SAME_NONZERO_PATTERN,DIFFERENT_NONZERO_PATTERN,SAME_PRECONDITIONER,SUBSET_NONZERO_PATTERN} MatStructure;

341: EXTERN int MatCopy(Mat,Mat,MatStructure);
342: EXTERN int MatView(Mat,PetscViewer);

344: EXTERN int MatLoad(PetscViewer,MatType,Mat*);
345: EXTERN int MatMerge(MPI_Comm,Mat,Mat*);

347: EXTERN int MatGetRowIJ(Mat,int,PetscTruth,int*,int *[],int *[],PetscTruth *);
348: EXTERN int MatRestoreRowIJ(Mat,int,PetscTruth,int *,int *[],int *[],PetscTruth *);
349: EXTERN int MatGetColumnIJ(Mat,int,PetscTruth,int*,int *[],int *[],PetscTruth *);
350: EXTERN int MatRestoreColumnIJ(Mat,int,PetscTruth,int *,int *[],int *[],PetscTruth *);

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

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

357:    Level: intermediate

359:   Concepts: matrix^nonzero information

361: .seealso:  MatGetInfo(), MatInfoType
362: S*/
363: typedef struct {
364:   PetscLogDouble rows_global,columns_global;         /* number of global rows and columns */
365:   PetscLogDouble rows_local,columns_local;           /* number of local rows and columns */
366:   PetscLogDouble block_size;                         /* block size */
367:   PetscLogDouble nz_allocated,nz_used,nz_unneeded;   /* number of nonzeros */
368:   PetscLogDouble memory;                             /* memory allocated */
369:   PetscLogDouble assemblies;                         /* number of matrix assemblies called */
370:   PetscLogDouble mallocs;                            /* number of mallocs during MatSetValues() */
371:   PetscLogDouble fill_ratio_given,fill_ratio_needed; /* fill ratio for LU/ILU */
372:   PetscLogDouble factor_mallocs;                     /* number of mallocs during factorization */
373: } MatInfo;

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

379:     Level: beginner

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

383: .seealso: MatGetInfo(), MatInfo
384: E*/
385: typedef enum {MAT_LOCAL=1,MAT_GLOBAL_MAX=2,MAT_GLOBAL_SUM=3} MatInfoType;
386: EXTERN int MatGetInfo(Mat,MatInfoType,MatInfo*);
387: EXTERN int MatValid(Mat,PetscTruth*);
388: EXTERN int MatGetDiagonal(Mat,Vec);
389: EXTERN int MatGetRowMax(Mat,Vec);
390: EXTERN int MatTranspose(Mat,Mat*);
391: EXTERN int MatPermute(Mat,IS,IS,Mat *);
392: EXTERN int MatPermuteSparsify(Mat,int,PetscReal,PetscReal,IS,IS,Mat *);
393: EXTERN int MatDiagonalScale(Mat,Vec,Vec);
394: EXTERN int MatDiagonalSet(Mat,Vec,InsertMode);
395: EXTERN int MatEqual(Mat,Mat,PetscTruth*);

397: EXTERN int MatNorm(Mat,NormType,PetscReal *);
398: EXTERN int MatZeroEntries(Mat);
399: EXTERN int MatZeroRows(Mat,IS,const PetscScalar*);
400: EXTERN int MatZeroColumns(Mat,IS,const PetscScalar*);

402: EXTERN int MatUseScaledForm(Mat,PetscTruth);
403: EXTERN int MatScaleSystem(Mat,Vec,Vec);
404: EXTERN int MatUnScaleSystem(Mat,Vec,Vec);

406: EXTERN int MatGetSize(Mat,int*,int*);
407: EXTERN int MatGetLocalSize(Mat,int*,int*);
408: EXTERN int MatGetOwnershipRange(Mat,int*,int*);

410: /*E
411:     MatReuse - Indicates if matrices obtained from a previous call to MatGetSubMatrices()
412:      or MatGetSubMatrix() are to be reused to store the new matrix values.

414:     Level: beginner

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

418: .seealso: MatGetSubMatrices(), MatGetSubMatrix(), MatDestroyMatrices()
419: E*/
420: typedef enum {MAT_INITIAL_MATRIX,MAT_REUSE_MATRIX} MatReuse;
421: EXTERN int MatGetSubMatrices(Mat,int,const IS[],const IS[],MatReuse,Mat *[]);
422: EXTERN int MatDestroyMatrices(int,Mat *[]);
423: EXTERN int MatGetSubMatrix(Mat,IS,IS,int,MatReuse,Mat *);

425: EXTERN int MatIncreaseOverlap(Mat,int,IS[],int);

427: EXTERN int MatAXPY(const PetscScalar *,Mat,Mat,MatStructure);
428: EXTERN int MatAYPX(const PetscScalar *,Mat,Mat);
429: EXTERN int MatCompress(Mat);

431: EXTERN int MatScale(const PetscScalar *,Mat);
432: EXTERN int MatShift(const PetscScalar *,Mat);

434: EXTERN int MatSetLocalToGlobalMapping(Mat,ISLocalToGlobalMapping);
435: EXTERN int MatSetLocalToGlobalMappingBlock(Mat,ISLocalToGlobalMapping);
436: EXTERN int MatZeroRowsLocal(Mat,IS,const PetscScalar*);
437: EXTERN int MatSetValuesLocal(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);
438: EXTERN int MatSetValuesBlockedLocal(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);

440: EXTERN int MatSetStashInitialSize(Mat,int,int);

442: EXTERN int MatInterpolateAdd(Mat,Vec,Vec,Vec);
443: EXTERN int MatInterpolate(Mat,Vec,Vec);
444: EXTERN int MatRestrict(Mat,Vec,Vec);


447: /*MC
448:    MatPreallocInitialize - Begins the block of code that will count the number of nonzeros per
449:        row in a matrix providing the data that one can use to correctly preallocate the matrix.

451:    Synopsis:
452:    int MatPreallocateInitialize(MPI_Comm comm, int nrows, int ncols, int *dnz, int *onz)

454:    Collective on MPI_Comm

456:    Input Parameters:
457: +  comm - the communicator that will share the eventually allocated matrix
458: .  nrows - the number of rows in the matrix
459: -  ncols - the number of columns in the matrix

461:    Output Parameters:
462: +  dnz - the array that will be passed to the matrix preallocation routines
463: -  ozn - the other array passed to the matrix preallocation routines


466:    Level: intermediate

468:    Notes:
469:    See the chapter in the users manual on performance for more details

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

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

475:   Concepts: preallocation^Matrix

477: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
478:           MatPreallocateInitializeSymmetric(), MatPreallocateSymmetricSetLocal()
479: M*/
480: #define MatPreallocateInitialize(comm,nrows,ncols,dnz,onz) 0; \
481: { \
482:   int _4_ierr,__tmp = (nrows),__ctmp = (ncols),__rstart,__start,__end; \
483:   _4_PetscMalloc(2*__tmp*sizeof(int),&dnz);CHKERRQ(_4_ierr);onz = dnz + __tmp;\
484:   _4_PetscMemzero(dnz,2*__tmp*sizeof(int));CHKERRQ(_4_ierr);\
485:   _4_MPI_Scan(&__ctmp,&__end,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __start = __end - __ctmp;\
486:   _4_MPI_Scan(&__tmp,&__rstart,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __rstart = __rstart - __tmp;

488: /*MC
489:    MatPreallocSymmetricInitialize - Begins the block of code that will count the number of nonzeros per
490:        row in a matrix providing the data that one can use to correctly preallocate the matrix.

492:    Synopsis:
493:    int MatPreallocateSymmetricInitialize(MPI_Comm comm, int nrows, int ncols, int *dnz, int *onz)

495:    Collective on MPI_Comm

497:    Input Parameters:
498: +  comm - the communicator that will share the eventually allocated matrix
499: .  nrows - the number of rows in the matrix
500: -  ncols - the number of columns in the matrix

502:    Output Parameters:
503: +  dnz - the array that will be passed to the matrix preallocation routines
504: -  ozn - the other array passed to the matrix preallocation routines


507:    Level: intermediate

509:    Notes:
510:    See the chapter in the users manual on performance for more details

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

514:   Concepts: preallocation^Matrix

516: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
517:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal()
518: M*/
519: #define MatPreallocateSymmetricInitialize(comm,nrows,ncols,dnz,onz) 0; \
520: { \
521:   int _4_ierr,__tmp = (nrows),__ctmp = (ncols),__rstart,__end; \
522:   _4_PetscMalloc(2*__tmp*sizeof(int),&dnz);CHKERRQ(_4_ierr);onz = dnz + __tmp;\
523:   _4_PetscMemzero(dnz,2*__tmp*sizeof(int));CHKERRQ(_4_ierr);\
524:   _4_MPI_Scan(&__ctmp,&__end,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr);\
525:   _4_MPI_Scan(&__tmp,&__rstart,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __rstart = __rstart - __tmp;

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

531:    Synopsis:
532:    int MatPreallocateSetLocal(ISLocalToGlobalMappping map,int nrows, int *rows,int ncols, int *cols,int *dnz, int *onz)

534:    Not Collective

536:    Input Parameters:
537: +  map - the mapping between local numbering and global numbering
538: .  nrows - the number of rows indicated
539: .  rows - the indices of the rows (these will be mapped in the 
540: .  ncols - the number of columns in the matrix
541: .  cols - the columns indicated
542: .  dnz - the array that will be passed to the matrix preallocation routines
543: -  ozn - the other array passed to the matrix preallocation routines


546:    Level: intermediate

548:    Notes:
549:    See the chapter in the users manual on performance for more details

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

553:   Concepts: preallocation^Matrix

555: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
556:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal()
557: M*/
558: #define MatPreallocateSetLocal(map,nrows,rows,ncols,cols,dnz,onz) 0;\
559: {\
560:   int __l;\
561:   _4_ISLocalToGlobalMappingApply(map,nrows,rows,rows);CHKERRQ(_4_ierr);\
562:   _4_ISLocalToGlobalMappingApply(map,ncols,cols,cols);CHKERRQ(_4_ierr);\
563:   for (__l=0;__l<nrows;__l++) {\
564:     _4_MatPreallocateSet((rows)[__l],ncols,cols,dnz,onz);CHKERRQ(_4_ierr);\
565:   }\
566: }
567: 
568: /*MC
569:    MatPreallocateSymmetricSetLocal - Indicates the locations (rows and columns) in the matrix where nonzeros will be
570:        inserted using a local number of the rows and columns

572:    Synopsis:
573:    int MatPreallocateSymmetricSetLocal(ISLocalToGlobalMappping map,int nrows, int *rows,int ncols, int *cols,int *dnz, int *onz)

575:    Not Collective

577:    Input Parameters:
578: +  map - the mapping between local numbering and global numbering
579: .  nrows - the number of rows indicated
580: .  rows - the indices of the rows (these will be mapped in the 
581: .  ncols - the number of columns in the matrix
582: .  cols - the columns indicated
583: .  dnz - the array that will be passed to the matrix preallocation routines
584: -  ozn - the other array passed to the matrix preallocation routines


587:    Level: intermediate

589:    Notes:
590:    See the chapter in the users manual on performance for more details

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

594:   Concepts: preallocation^Matrix

596: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
597:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
598: M*/
599: #define MatPreallocateSymmetricSetLocal(map,nrows,rows,ncols,cols,dnz,onz) 0;\
600: {\
601:   int __l;\
602:   _4_ISLocalToGlobalMappingApply(map,nrows,rows,rows);CHKERRQ(_4_ierr);\
603:   _4_ISLocalToGlobalMappingApply(map,ncols,cols,cols);CHKERRQ(_4_ierr);\
604:   for (__l=0;__l<nrows;__l++) {\
605:     _4_MatPreallocateSymmetricSet((rows)[__l],ncols,cols,dnz,onz);CHKERRQ(_4_ierr);\
606:   }\
607: }

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

613:    Synopsis:
614:    int MatPreallocateSet(int nrows, int *rows,int ncols, int *cols,int *dnz, int *onz)

616:    Not Collective

618:    Input Parameters:
619: +  nrows - the number of rows indicated
620: .  rows - the indices of the rows (these will be mapped in the 
621: .  ncols - the number of columns in the matrix
622: .  cols - the columns indicated
623: .  dnz - the array that will be passed to the matrix preallocation routines
624: -  ozn - the other array passed to the matrix preallocation routines


627:    Level: intermediate

629:    Notes:
630:    See the chapter in the users manual on performance for more details

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

634:   Concepts: preallocation^Matrix

636: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
637:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
638: M*/
639: #define MatPreallocateSet(row,nc,cols,dnz,onz) 0;\
640: { int __i; \
641:   for (__i=0; __i<nc; __i++) {\
642:     if (cols[__i] < __start || cols[__i] >= __end) onz[row - __rstart]++; \
643:   }\
644:   dnz[row - __rstart] = nc - onz[row - __rstart];\
645: }

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

651:    Synopsis:
652:    int MatPreallocateSymmetricSet(int nrows, int *rows,int ncols, int *cols,int *dnz, int *onz)

654:    Not Collective

656:    Input Parameters:
657: +  nrows - the number of rows indicated
658: .  rows - the indices of the rows (these will be mapped in the 
659: .  ncols - the number of columns in the matrix
660: .  cols - the columns indicated
661: .  dnz - the array that will be passed to the matrix preallocation routines
662: -  ozn - the other array passed to the matrix preallocation routines


665:    Level: intermediate

667:    Notes:
668:    See the chapter in the users manual on performance for more details

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

672:   Concepts: preallocation^Matrix

674: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
675:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
676: M*/
677: #define MatPreallocateSymmetricSet(row,nc,cols,dnz,onz) 0;\
678: { int __i; \
679:   for (__i=0; __i<nc; __i++) {\
680:     if (cols[__i] >= __end) onz[row - __rstart]++; \
681:     else if (cols[__i] >= row) dnz[row - __rstart]++;\
682:   }\
683: }

685: /*MC
686:    MatPreallocFinalize - Ends the block of code that will count the number of nonzeros per
687:        row in a matrix providing the data that one can use to correctly preallocate the matrix.

689:    Synopsis:
690:    int MatPreallocateFinalize(int *dnz, int *onz)

692:    Collective on MPI_Comm

694:    Input Parameters:
695: +  dnz - the array that will be passed to the matrix preallocation routines
696: -  ozn - the other array passed to the matrix preallocation routines


699:    Level: intermediate

701:    Notes:
702:    See the chapter in the users manual on performance for more details

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

706:   Concepts: preallocation^Matrix

708: .seealso: MatPreallocateInitialize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
709:           MatPreallocateSymmetricInitialize(), MatPreallocateSymmetricSetLocal()
710: M*/
711: #define MatPreallocateFinalize(dnz,onz) 0;_4_PetscFree(dnz);CHKERRQ(_4_ierr);}



715: /* Routines unique to particular data structures */
716: EXTERN int MatShellGetContext(Mat,void **);

718: EXTERN int MatBDiagGetData(Mat,int*,int*,int*[],int*[],PetscScalar***);
719: EXTERN int MatSeqAIJSetColumnIndices(Mat,int[]);
720: EXTERN int MatSeqBAIJSetColumnIndices(Mat,int[]);
721: EXTERN int MatCreateSeqAIJWithArrays(MPI_Comm,int,int,int[],int[],PetscScalar[],Mat*);

723: EXTERN int MatSeqBAIJSetPreallocation(Mat,int,int,const int[]);
724: EXTERN int MatSeqSBAIJSetPreallocation(Mat,int,int,const int[]);
725: EXTERN int MatSeqAIJSetPreallocation(Mat,int,const int[]);
726: EXTERN int MatSeqDensePreallocation(Mat,PetscScalar[]);
727: EXTERN int MatSeqBDiagSetPreallocation(Mat,int,int,const int[],PetscScalar*[]);
728: EXTERN int MatSeqDenseSetPreallocation(Mat,PetscScalar[]);

730: EXTERN int MatMPIBAIJSetPreallocation(Mat,int,int,const int[],int,const int[]);
731: EXTERN int MatMPISBAIJSetPreallocation(Mat,int,int,const int[],int,const int[]);
732: EXTERN int MatMPIAIJSetPreallocation(Mat,int,const int[],int,const int[]);
733: EXTERN int MatMPIDensePreallocation(Mat,PetscScalar[]);
734: EXTERN int MatMPIBDiagSetPreallocation(Mat,int,int,const int[],PetscScalar*[]);
735: EXTERN int MatMPIAdjSetPreallocation(Mat,int[],int[],int[]);
736: EXTERN int MatMPIDenseSetPreallocation(Mat,PetscScalar[]);
737: EXTERN int MatMPIRowbsSetPreallocation(Mat,int,const int[]);
738: EXTERN int MatMPIAIJGetSeqAIJ(Mat,Mat*,Mat*,int*[]);
739: EXTERN int MatMPIBAIJGetSeqBAIJ(Mat,Mat*,Mat*,int*[]);
740: EXTERN int MatAdicSetLocalFunction(Mat,void (*)(void));

742: EXTERN int MatSeqDenseSetLDA(Mat,int);

744: EXTERN int MatStoreValues(Mat);
745: EXTERN int MatRetrieveValues(Mat);

747: EXTERN int MatDAADSetCtx(Mat,void*);

749: /* 
750:   These routines are not usually accessed directly, rather solving is 
751:   done through the SLES, KSP and PC interfaces.
752: */

754: /*E
755:     MatOrderingType - String with the name of a PETSc matrix ordering or the creation function
756:        with an optional dynamic library name, for example 
757:        http://www.mcs.anl.gov/petsc/lib.a:orderingcreate()

759:    Level: beginner

761: .seealso: MatGetOrdering()
762: E*/
763: typedef char* MatOrderingType;
764: #define MATORDERING_NATURAL   "natural"
765: #define MATORDERING_ND        "nd"
766: #define MATORDERING_1WD       "1wd"
767: #define MATORDERING_RCM       "rcm"
768: #define MATORDERING_QMD       "qmd"
769: #define MATORDERING_ROWLENGTH "rowlength"
770: #define MATORDERING_DSC_ND    "dsc_nd"
771: #define MATORDERING_DSC_MMD   "dsc_mmd"
772: #define MATORDERING_DSC_MDF   "dsc_mdf"
773: #define MATORDERING_CONSTRAINED "constrained"
774: #define MATORDERING_IDENTITY  "identity"
775: #define MATORDERING_REVERSE   "reverse"

777: EXTERN int MatGetOrdering(Mat,MatOrderingType,IS*,IS*);
778: EXTERN int MatOrderingRegister(char*,char*,char*,int(*)(Mat,MatOrderingType,IS*,IS*));

780: /*MC
781:    MatOrderingRegisterDynamic - Adds a new sparse matrix ordering to the 
782:                                matrix package. 

784:    Synopsis:
785:    int MatOrderingRegisterDynamic(char *name_ordering,char *path,char *name_create,int (*routine_create)(MatOrdering))

787:    Not Collective

789:    Input Parameters:
790: +  sname - name of ordering (for example MATORDERING_ND)
791: .  path - location of library where creation routine is 
792: .  name - name of function that creates the ordering type,a string
793: -  function - function pointer that creates the ordering

795:    Level: developer

797:    If dynamic libraries are used, then the fourth input argument (function)
798:    is ignored.

800:    Sample usage:
801: .vb
802:    MatOrderingRegisterDynamic("my_order",/home/username/my_lib/lib/libO/solaris/mylib.a,
803:                "MyOrder",MyOrder);
804: .ve

806:    Then, your partitioner can be chosen with the procedural interface via
807: $     MatOrderingSetType(part,"my_order)
808:    or at runtime via the option
809: $     -pc_ilu_mat_ordering_type my_order
810: $     -pc_lu_mat_ordering_type my_order

812:    ${PETSC_ARCH} and ${BOPT} occuring in pathname will be replaced with appropriate values.

814: .keywords: matrix, ordering, register

816: .seealso: MatOrderingRegisterDestroy(), MatOrderingRegisterAll()
817: M*/
818: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
819: #define MatOrderingRegisterDynamic(a,b,c,d) MatOrderingRegister(a,b,c,0)
820: #else
821: #define MatOrderingRegisterDynamic(a,b,c,d) MatOrderingRegister(a,b,c,d)
822: #endif

824: EXTERN int        MatOrderingRegisterDestroy(void);
825: EXTERN int        MatOrderingRegisterAll(char*);
826: extern PetscTruth MatOrderingRegisterAllCalled;
827: extern PetscFList MatOrderingList;

829: EXTERN int MatReorderForNonzeroDiagonal(Mat,PetscReal,IS,IS);

831: /*S 
832:    MatFactorInfo - Data based into the matrix factorization routines

834:    In Fortran these are simply double precision arrays of size MAT_FACTORINFO_SIZE

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

838:    Level: developer

840: .seealso: MatLUFactorSymbolic(), MatILUFactorSymbolic(), MatCholeskyFactorSymbolic(), MatICCFactorSymbolic(), MatICCFactor()

842: S*/
843: typedef struct {
844:   PetscReal     damping;        /* scaling of identity added to matrix to prevent zero pivots */
845:   PetscReal     shift;          /* if true, shift until positive pivots */
846:   PetscReal     shift_fraction; /* record shift fraction taken */
847:   PetscReal     diagonal_fill;  /* force diagonal to fill in if initially not filled */
848:   PetscReal     dt;             /* drop tolerance */
849:   PetscReal     dtcol;          /* tolerance for pivoting */
850:   PetscReal     dtcount;        /* maximum nonzeros to be allowed per row */
851:   PetscReal     fill;           /* expected fill; nonzeros in factored matrix/nonzeros in original matrix*/
852:   PetscReal     levels;         /* ICC/ILU(levels) */
853:   PetscReal     pivotinblocks;  /* for BAIJ and SBAIJ matrices pivot in factorization on blocks, default 1.0 
854:                                    factorization may be faster if do not pivot */
855:   PetscReal     zeropivot;      /* pivot is called zero if less than this */
856: } MatFactorInfo;

858: EXTERN int MatCholeskyFactor(Mat,IS,MatFactorInfo*);
859: EXTERN int MatCholeskyFactorSymbolic(Mat,IS,MatFactorInfo*,Mat*);
860: EXTERN int MatCholeskyFactorNumeric(Mat,Mat*);
861: EXTERN int MatLUFactor(Mat,IS,IS,MatFactorInfo*);
862: EXTERN int MatILUFactor(Mat,IS,IS,MatFactorInfo*);
863: EXTERN int MatLUFactorSymbolic(Mat,IS,IS,MatFactorInfo*,Mat*);
864: EXTERN int MatILUFactorSymbolic(Mat,IS,IS,MatFactorInfo*,Mat*);
865: EXTERN int MatICCFactorSymbolic(Mat,IS,MatFactorInfo*,Mat*);
866: EXTERN int MatICCFactor(Mat,IS,MatFactorInfo*);
867: EXTERN int MatLUFactorNumeric(Mat,Mat*);
868: EXTERN int MatILUDTFactor(Mat,MatFactorInfo*,IS,IS,Mat *);
869: EXTERN int MatGetInertia(Mat,int*,int*,int*);
870: EXTERN int MatSolve(Mat,Vec,Vec);
871: EXTERN int MatForwardSolve(Mat,Vec,Vec);
872: EXTERN int MatBackwardSolve(Mat,Vec,Vec);
873: EXTERN int MatSolveAdd(Mat,Vec,Vec,Vec);
874: EXTERN int MatSolveTranspose(Mat,Vec,Vec);
875: EXTERN int MatSolveTransposeAdd(Mat,Vec,Vec,Vec);
876: EXTERN int MatSolves(Mat,Vecs,Vecs);

878: EXTERN int MatSetUnfactored(Mat);

880: /*E
881:     MatSORType - What type of (S)SOR to perform

883:     Level: beginner

885:    May be bitwise ORd together

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

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

891: .seealso: MatRelax()
892: E*/
893: typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3,
894:               SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8,
895:               SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16,
896:               SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128} MatSORType;
897: EXTERN int MatRelax(Mat,Vec,PetscReal,MatSORType,PetscReal,int,int,Vec);

899: /* 
900:     These routines are for efficiently computing Jacobians via finite differences.
901: */

903: /*E
904:     MatColoringType - String with the name of a PETSc matrix coloring or the creation function
905:        with an optional dynamic library name, for example 
906:        http://www.mcs.anl.gov/petsc/lib.a:coloringcreate()

908:    Level: beginner

910: .seealso: MatGetColoring()
911: E*/
912: typedef char* MatColoringType;
913: #define MATCOLORING_NATURAL "natural"
914: #define MATCOLORING_SL      "sl"
915: #define MATCOLORING_LF      "lf"
916: #define MATCOLORING_ID      "id"

918: EXTERN int MatGetColoring(Mat,MatColoringType,ISColoring*);
919: EXTERN int MatColoringRegister(char*,char*,char*,int(*)(Mat,MatColoringType,ISColoring *));

921: /*MC
922:    MatColoringRegisterDynamic - Adds a new sparse matrix coloring to the 
923:                                matrix package. 

925:    Synopsis:
926:    int MatColoringRegisterDynamic(char *name_coloring,char *path,char *name_create,int (*routine_create)(MatColoring))

928:    Not Collective

930:    Input Parameters:
931: +  sname - name of Coloring (for example MATCOLORING_SL)
932: .  path - location of library where creation routine is 
933: .  name - name of function that creates the Coloring type, a string
934: -  function - function pointer that creates the coloring

936:    Level: developer

938:    If dynamic libraries are used, then the fourth input argument (function)
939:    is ignored.

941:    Sample usage:
942: .vb
943:    MatColoringRegisterDynamic("my_color",/home/username/my_lib/lib/libO/solaris/mylib.a,
944:                "MyColor",MyColor);
945: .ve

947:    Then, your partitioner can be chosen with the procedural interface via
948: $     MatColoringSetType(part,"my_color")
949:    or at runtime via the option
950: $     -mat_coloring_type my_color

952:    $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values.

954: .keywords: matrix, Coloring, register

956: .seealso: MatColoringRegisterDestroy(), MatColoringRegisterAll()
957: M*/
958: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
959: #define MatColoringRegisterDynamic(a,b,c,d) MatColoringRegister(a,b,c,0)
960: #else
961: #define MatColoringRegisterDynamic(a,b,c,d) MatColoringRegister(a,b,c,d)
962: #endif

964: EXTERN int        MatColoringRegisterAll(char *);
965: extern PetscTruth MatColoringRegisterAllCalled;
966: EXTERN int        MatColoringRegisterDestroy(void);
967: EXTERN int        MatColoringPatch(Mat,int,int,const ISColoringValue[],ISColoring*);

969: /*S
970:      MatFDColoring - Object for computing a sparse Jacobian via finite differences
971:         and coloring

973:    Level: beginner

975:   Concepts: coloring, sparse Jacobian, finite differences

977: .seealso:  MatFDColoringCreate()
978: S*/
979: typedef struct _p_MatFDColoring *MatFDColoring;

981: EXTERN int MatFDColoringCreate(Mat,ISColoring,MatFDColoring *);
982: EXTERN int MatFDColoringDestroy(MatFDColoring);
983: EXTERN int MatFDColoringView(MatFDColoring,PetscViewer);
984: EXTERN int MatFDColoringSetFunction(MatFDColoring,int (*)(void),void*);
985: EXTERN int MatFDColoringSetParameters(MatFDColoring,PetscReal,PetscReal);
986: EXTERN int MatFDColoringSetFrequency(MatFDColoring,int);
987: EXTERN int MatFDColoringGetFrequency(MatFDColoring,int*);
988: EXTERN int MatFDColoringSetFromOptions(MatFDColoring);
989: EXTERN int MatFDColoringApply(Mat,MatFDColoring,Vec,MatStructure*,void *);
990: EXTERN int MatFDColoringApplyTS(Mat,MatFDColoring,PetscReal,Vec,MatStructure*,void *);
991: EXTERN int MatFDColoringSetRecompute(MatFDColoring);
992: EXTERN int MatFDColoringSetF(MatFDColoring,Vec);
993: EXTERN int MatFDColoringGetPerturbedColumns(MatFDColoring,int*,int*[]);
994: /* 
995:     These routines are for partitioning matrices: currently used only 
996:   for adjacency matrix, MatCreateMPIAdj().
997: */

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

1002:    Level: beginner

1004:   Concepts: partitioning

1006: .seealso:  MatPartitioningCreate(), MatPartitioningType
1007: S*/
1008: typedef struct _p_MatPartitioning *MatPartitioning;

1010: /*E
1011:     MatPartitioningType - String with the name of a PETSc matrix partitioning or the creation function
1012:        with an optional dynamic library name, for example 
1013:        http://www.mcs.anl.gov/petsc/lib.a:partitioningcreate()

1015:    Level: beginner

1017: .seealso: MatPartitioningCreate(), MatPartitioning
1018: E*/
1019: typedef char* MatPartitioningType;
1020: #define MAT_PARTITIONING_CURRENT  "current"
1021: #define MAT_PARTITIONING_PARMETIS "parmetis"

1023: EXTERN int MatPartitioningCreate(MPI_Comm,MatPartitioning*);
1024: EXTERN int MatPartitioningSetType(MatPartitioning,MatPartitioningType);
1025: EXTERN int MatPartitioningSetNParts(MatPartitioning,int);
1026: EXTERN int MatPartitioningSetAdjacency(MatPartitioning,Mat);
1027: EXTERN int MatPartitioningSetVertexWeights(MatPartitioning,const int[]);
1028: EXTERN int MatPartitioningSetPartitionWeights(MatPartitioning,const PetscReal []);
1029: EXTERN int MatPartitioningApply(MatPartitioning,IS*);
1030: EXTERN int MatPartitioningDestroy(MatPartitioning);

1032: EXTERN int MatPartitioningRegister(char*,char*,char*,int(*)(MatPartitioning));

1034: /*MC
1035:    MatPartitioningRegisterDynamic - Adds a new sparse matrix partitioning to the 
1036:    matrix package. 

1038:    Synopsis:
1039:    int MatPartitioningRegisterDynamic(char *name_partitioning,char *path,char *name_create,int (*routine_create)(MatPartitioning))

1041:    Not Collective

1043:    Input Parameters:
1044: +  sname - name of partitioning (for example MAT_PARTITIONING_CURRENT) or parmetis
1045: .  path - location of library where creation routine is 
1046: .  name - name of function that creates the partitioning type, a string
1047: -  function - function pointer that creates the partitioning type

1049:    Level: developer

1051:    If dynamic libraries are used, then the fourth input argument (function)
1052:    is ignored.

1054:    Sample usage:
1055: .vb
1056:    MatPartitioningRegisterDynamic("my_part",/home/username/my_lib/lib/libO/solaris/mylib.a,
1057:                "MyPartCreate",MyPartCreate);
1058: .ve

1060:    Then, your partitioner can be chosen with the procedural interface via
1061: $     MatPartitioningSetType(part,"my_part")
1062:    or at runtime via the option
1063: $     -mat_partitioning_type my_part

1065:    $PETSC_ARCH and $BOPT occuring in pathname will be replaced with appropriate values.

1067: .keywords: matrix, partitioning, register

1069: .seealso: MatPartitioningRegisterDestroy(), MatPartitioningRegisterAll()
1070: M*/
1071: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
1072: #define MatPartitioningRegisterDynamic(a,b,c,d) MatPartitioningRegister(a,b,c,0)
1073: #else
1074: #define MatPartitioningRegisterDynamic(a,b,c,d) MatPartitioningRegister(a,b,c,d)
1075: #endif

1077: EXTERN int        MatPartitioningRegisterAll(char *);
1078: extern PetscTruth MatPartitioningRegisterAllCalled;
1079: EXTERN int        MatPartitioningRegisterDestroy(void);

1081: EXTERN int MatPartitioningView(MatPartitioning,PetscViewer);
1082: EXTERN int MatPartitioningSetFromOptions(MatPartitioning);
1083: EXTERN int MatPartitioningGetType(MatPartitioning,MatPartitioningType*);

1085: EXTERN int MatPartitioningParmetisSetCoarseSequential(MatPartitioning);

1087: /*
1088:     If you add entries here you must also add them to finclude/petscmat.h
1089: */
1090: typedef enum { MATOP_SET_VALUES=0,
1091:                MATOP_GET_ROW=1,
1092:                MATOP_RESTORE_ROW=2,
1093:                MATOP_MULT=3,
1094:                MATOP_MULT_ADD=4,
1095:                MATOP_MULT_TRANSPOSE=5,
1096:                MATOP_MULT_TRANSPOSE_ADD=6,
1097:                MATOP_SOLVE=7,
1098:                MATOP_SOLVE_ADD=8,
1099:                MATOP_SOLVE_TRANSPOSE=9,
1100:                MATOP_SOLVE_TRANSPOSE_ADD=10,
1101:                MATOP_LUFACTOR=11,
1102:                MATOP_CHOLESKYFACTOR=12,
1103:                MATOP_RELAX=13,
1104:                MATOP_TRANSPOSE=14,
1105:                MATOP_GETINFO=15,
1106:                MATOP_EQUAL=16,
1107:                MATOP_GET_DIAGONAL=17,
1108:                MATOP_DIAGONAL_SCALE=18,
1109:                MATOP_NORM=19,
1110:                MATOP_ASSEMBLY_BEGIN=20,
1111:                MATOP_ASSEMBLY_END=21,
1112:                MATOP_COMPRESS=22,
1113:                MATOP_SET_OPTION=23,
1114:                MATOP_ZERO_ENTRIES=24,
1115:                MATOP_ZERO_ROWS=25,
1116:                MATOP_LUFACTOR_SYMBOLIC=26,
1117:                MATOP_LUFACTOR_NUMERIC=27,
1118:                MATOP_CHOLESKY_FACTOR_SYMBOLIC=28,
1119:                MATOP_CHOLESKY_FACTOR_NUMERIC=29,
1120:                MATOP_SETUP_PREALLOCATION=30,
1121:                MATOP_ILUFACTOR_SYMBOLIC=31,
1122:                MATOP_ICCFACTOR_SYMBOLIC=32,
1123:                MATOP_GET_ARRAY=33,
1124:                MATOP_RESTORE_ARRAY=34,
1125:                MATOP_DUPLCIATE=35,
1126:                MATOP_FORWARD_SOLVE=36,
1127:                MATOP_BACKWARD_SOLVE=37,
1128:                MATOP_ILUFACTOR=38,
1129:                MATOP_ICCFACTOR=39,
1130:                MATOP_AXPY=40,
1131:                MATOP_GET_SUBMATRICES=41,
1132:                MATOP_INCREASE_OVERLAP=42,
1133:                MATOP_GET_VALUES=43,
1134:                MATOP_COPY=44,
1135:                MATOP_PRINT_HELP=45,
1136:                MATOP_SCALE=46,
1137:                MATOP_SHIFT=47,
1138:                MATOP_DIAGONAL_SHIFT=48,
1139:                MATOP_ILUDT_FACTOR=49,
1140:                MATOP_GET_BLOCK_SIZE=50,
1141:                MATOP_GET_ROW_IJ=51,
1142:                MATOP_RESTORE_ROW_IJ=52,
1143:                MATOP_GET_COLUMN_IJ=53,
1144:                MATOP_RESTORE_COLUMN_IJ=54,
1145:                MATOP_FDCOLORING_CREATE=55,
1146:                MATOP_COLORING_PATCH=56,
1147:                MATOP_SET_UNFACTORED=57,
1148:                MATOP_PERMUTE=58,
1149:                MATOP_SET_VALUES_BLOCKED=59,
1150:                MATOP_GET_SUBMATRIX=60,
1151:                MATOP_DESTROY=61,
1152:                MATOP_VIEW=62,
1153:                MATOP_GET_MAPS=63,
1154:                MATOP_USE_SCALED_FORM=64,
1155:                MATOP_SCALE_SYSTEM=65,
1156:                MATOP_UNSCALE_SYSTEM=66,
1157:                MATOP_SET_LOCAL_TO_GLOBAL_MAPPING=67,
1158:                MATOP_SET_VALUES_LOCAL=68,
1159:                MATOP_ZERO_ROWS_LOCAL=69,
1160:                MATOP_GET_ROW_MAX=70,
1161:                MATOP_CONVERT=71,
1162:                MATOP_SET_COLORING=72,
1163:                MATOP_SET_VALUES_ADIC=73,
1164:                MATOP_SET_VALUES_ADIFOR=74,
1165:                MATOP_FD_COLORING_APPLY=75,
1166:                MATOP_SET_FROM_OPTIONS=76,
1167:                MATOP_MULT_CONSTRAINED=77,
1168:                MATOP_MULT_TRANSPOSE_CONSTRAINED=78,
1169:                MATOP_ILU_FACTOR_SYMBOLIC_CONSTRAINED=79,
1170:                MATOP_PERMUTE_SPARSIFY=80,
1171:                MATOP_MULT_MULTIPLE=81,
1172:                MATOP_SOLVE_MULTIPLE=82
1173:              } MatOperation;
1174: EXTERN int MatHasOperation(Mat,MatOperation,PetscTruth*);
1175: EXTERN int MatShellSetOperation(Mat,MatOperation,void(*)(void));
1176: EXTERN int MatShellGetOperation(Mat,MatOperation,void(**)(void));
1177: EXTERN int MatShellSetContext(Mat,void*);

1179: /*
1180:    Codes for matrices stored on disk. By default they are
1181:  stored in a universal format. By changing the format with 
1182:  PetscViewerSetFormat(viewer,PETSC_VIEWER_BINARY_NATIVE); the matrices will
1183:  be stored in a way natural for the matrix, for example dense matrices
1184:  would be stored as dense. Matrices stored this way may only be
1185:  read into matrices of the same time.
1186: */
1187: #define MATRIX_BINARY_FORMAT_DENSE -1

1189: EXTERN int MatMPIBAIJSetHashTableFactor(Mat,PetscReal);
1190: EXTERN int MatSeqAIJGetInodeSizes(Mat,int *,int *[],int *);
1191: EXTERN int MatMPIRowbsGetColor(Mat,ISColoring *);

1193: /*S
1194:      MatNullSpace - Object that removes a null space from a vector, i.e.
1195:          orthogonalizes the vector to a subsapce

1197:    Level: advanced

1199:   Concepts: matrix; linear operator, null space

1201:   Users manual sections:
1202: .   Section 4.15 Solving Singular Systems

1204: .seealso:  MatNullSpaceCreate()
1205: S*/
1206: typedef struct _p_MatNullSpace* MatNullSpace;

1208: EXTERN int MatNullSpaceCreate(MPI_Comm,int,int,const Vec[],MatNullSpace*);
1209: EXTERN int MatNullSpaceDestroy(MatNullSpace);
1210: EXTERN int MatNullSpaceRemove(MatNullSpace,Vec,Vec*);
1211: EXTERN int MatNullSpaceAttach(Mat,MatNullSpace);
1212: EXTERN int MatNullSpaceTest(MatNullSpace,Mat);

1214: EXTERN int MatReorderingSeqSBAIJ(Mat A,IS isp);
1215: EXTERN int MatMPISBAIJSetHashTableFactor(Mat,PetscReal);
1216: EXTERN int MatSeqSBAIJSetColumnIndices(Mat,int *);

1218: EXTERN int MatMatMult(Mat A,Mat B, Mat *C);
1219: EXTERN int MatMatMultSymbolic(Mat A,Mat B,Mat *C);
1220: EXTERN int MatMatMultNumeric(Mat A,Mat B,Mat C);

1222: EXTERN int MatCreateMAIJ(Mat,int,Mat*);
1223: EXTERN int MatMAIJRedimension(Mat,int,Mat*);
1224: EXTERN int MatMAIJGetAIJ(Mat,Mat*);

1226: EXTERN int MatComputeExplicitOperator(Mat,Mat*);

1228: EXTERN int MatESISetType(Mat,char*);
1229: EXTERN int MatESISetFromOptions(Mat);

1231: EXTERN int MatDiagonalScaleLocal(Mat,Vec);

1233: EXTERN int PetscViewerMathematicaPutMatrix(PetscViewer, int, int, PetscReal *);
1234: EXTERN int PetscViewerMathematicaPutCSRMatrix(PetscViewer, int, int, int *, int *, PetscReal *);

1236: EXTERN int MatUseSpooles_SeqAIJ(Mat);
1237: EXTERN int MatUseUMFPACK_SeqAIJ(Mat);
1238: EXTERN int MatUseSuperLU_SeqAIJ(Mat);
1239: EXTERN int MatUseEssl_SeqAIJ(Mat);
1240: EXTERN int MatUseLUSOL_SeqAIJ(Mat);
1241: EXTERN int MatUseMatlab_SeqAIJ(Mat);
1242: EXTERN int MatUseDXML_SeqAIJ(Mat);
1243: EXTERN int MatUsePETSc_SeqAIJ(Mat);
1244: EXTERN int MatUseSuperLU_DIST_MPIAIJ(Mat);
1245: EXTERN int MatUseSpooles_MPIAIJ(Mat);
1246: EXTERN int MatUseSpooles_SeqSBAIJ(Mat);
1247: EXTERN int MatUseSpooles_MPISBAIJ(Mat);
1248: EXTERN int MatUseMUMPS_MPIAIJ(Mat);

1250: #endif