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
  8: PETSC_EXTERN_CXX_BEGIN

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

 13:    Level: beginner

 15:   Concepts: matrix; linear operator

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

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

 26:    Level: beginner

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

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

 89: EXTERN int MatInitializePackage(char *);

 91: EXTERN int MatCreate(MPI_Comm,int,int,int,int,Mat*);
 92: EXTERN int MatSetType(Mat,const MatType);
 93: EXTERN int MatSetFromOptions(Mat);
 94: EXTERN int MatSetUpPreallocation(Mat);
 95: EXTERN int MatRegisterAll(const char[]);
 96: EXTERN int MatRegister(const char[],const char[],const char[],int(*)(Mat));

 98: /*MC
 99:    MatRegisterDynamic - Adds a new matrix type

101:    Synopsis:
102:    int MatRegisterDynamic(char *name,char *path,char *name_create,int (*routine_create)(Mat))

104:    Not Collective

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

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

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

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

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

129:    Level: advanced

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

134: .keywords: Mat, register

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

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

145: extern PetscTruth MatRegisterAllCalled;
146: extern PetscFList MatList;

148: EXTERN int MatCreateSeqDense(MPI_Comm,int,int,PetscScalar[],Mat*);
149: EXTERN int MatCreateMPIDense(MPI_Comm,int,int,int,int,PetscScalar[],Mat*);
150: EXTERN int MatCreateSeqAIJ(MPI_Comm,int,int,int,const int[],Mat*);
151: EXTERN int MatCreateMPIAIJ(MPI_Comm,int,int,int,int,int,const int[],int,const int[],Mat*);
152: EXTERN int MatCreateMPIRowbs(MPI_Comm,int,int,int,const int[],Mat*);
153: EXTERN int MatCreateSeqBDiag(MPI_Comm,int,int,int,int,const int[],PetscScalar*[],Mat*);
154: EXTERN int MatCreateMPIBDiag(MPI_Comm,int,int,int,int,int,const int[],PetscScalar*[],Mat*);
155: EXTERN int MatCreateSeqBAIJ(MPI_Comm,int,int,int,int,const int[],Mat*);
156: EXTERN int MatCreateMPIBAIJ(MPI_Comm,int,int,int,int,int,int,const int[],int,const int[],Mat*);
157: EXTERN int MatCreateMPIAdj(MPI_Comm,int,int,int[],int[],int[],Mat*);
158: EXTERN int MatCreateSeqSBAIJ(MPI_Comm,int,int,int,int,const int[],Mat*);
159: EXTERN int MatCreateMPISBAIJ(MPI_Comm,int,int,int,int,int,int,const int[],int,const int[],Mat*);
160: EXTERN int MatCreateShell(MPI_Comm,int,int,int,int,void *,Mat*);
161: EXTERN int MatCreateAdic(MPI_Comm,int,int,int,int,int,void (*)(void),Mat*);
162: EXTERN int MatCreateNormal(Mat,Mat*);
163: EXTERN int MatDestroy(Mat);

165: EXTERN int MatPrintHelp(Mat);
166: EXTERN int MatGetPetscMaps(Mat,PetscMap*,PetscMap*);

168: /* ------------------------------------------------------------*/
169: EXTERN int MatSetValues(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);
170: EXTERN int MatSetValuesBlocked(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);

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

176:    Level: beginner

178:   Concepts: matrix; linear operator

180: .seealso:  MatSetValuesStencil(), MatSetStencil(), MatSetValuesBlockStencil()
181: S*/
182: typedef struct {
183:   int k,j,i,c;
184: } MatStencil;

186: EXTERN int MatSetValuesStencil(Mat,int,const MatStencil[],int,const MatStencil[],const PetscScalar[],InsertMode);
187: EXTERN int MatSetValuesBlockedStencil(Mat,int,const MatStencil[],int,const MatStencil[],const PetscScalar[],InsertMode);
188: EXTERN int MatSetStencil(Mat,int,const int[],const int[],int);

190: EXTERN int MatSetColoring(Mat,ISColoring);
191: EXTERN int MatSetValuesAdic(Mat,void*);
192: EXTERN int MatSetValuesAdifor(Mat,int,void*);

194: /*E
195:     MatAssemblyType - Indicates if the matrix is now to be used, or if you plan 
196:      to continue to add values to it

198:     Level: beginner

200: .seealso: MatAssemblyBegin(), MatAssemblyEnd()
201: E*/
202: typedef enum {MAT_FLUSH_ASSEMBLY=1,MAT_FINAL_ASSEMBLY=0} MatAssemblyType;
203: EXTERN int MatAssemblyBegin(Mat,MatAssemblyType);
204: EXTERN int MatAssemblyEnd(Mat,MatAssemblyType);
205: EXTERN int MatAssembled(Mat,PetscTruth*);

207: extern int         MatSetValue_Row, MatSetValue_Column;
208: extern PetscScalar MatSetValue_Value;

210: /*MC
211:    MatSetValue - Set a single entry into a matrix.

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

216:    Not collective

218:    Input Parameters:
219: +  m - the matrix
220: .  row - the row location of the entry
221: .  col - the column location of the entry
222: .  value - the value to insert
223: -  mode - either INSERT_VALUES or ADD_VALUES

225:    Notes: 
226:    For efficiency one should use MatSetValues() and set several or many
227:    values simultaneously if possible.

229:    Level: beginner

231: .seealso: MatSetValues(), MatSetValueLocal()
232: M*/
233: #define MatSetValue(v,i,j,va,mode) \
234:   (MatSetValue_Row = i,MatSetValue_Column = j,MatSetValue_Value = va, \
235:    MatSetValues(v,1,&MatSetValue_Row,1,&MatSetValue_Column,&MatSetValue_Value,mode))

237: #define MatGetValue(v,i,j,va) \
238:   (MatSetValue_Row = i,MatSetValue_Column = j,\
239:    MatGetValues(v,1,&MatSetValue_Row,1,&MatSetValue_Column,&va))

241: #define MatSetValueLocal(v,i,j,va,mode) \
242:   (MatSetValue_Row = i,MatSetValue_Column = j,MatSetValue_Value = va, \
243:    MatSetValuesLocal(v,1,&MatSetValue_Row,1,&MatSetValue_Column,&MatSetValue_Value,mode))

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

248:     Level: beginner

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

252: .seealso: MatSetOption()
253: E*/
254: typedef enum {MAT_ROW_ORIENTED=1,MAT_COLUMN_ORIENTED=2,MAT_ROWS_SORTED=4,
255:               MAT_COLUMNS_SORTED=8,MAT_NO_NEW_NONZERO_LOCATIONS=16,
256:               MAT_YES_NEW_NONZERO_LOCATIONS=32,MAT_SYMMETRIC=64,
257:               MAT_STRUCTURALLY_SYMMETRIC=65,MAT_NO_NEW_DIAGONALS=66,
258:               MAT_YES_NEW_DIAGONALS=67,MAT_INODE_LIMIT_1=68,MAT_INODE_LIMIT_2=69,
259:               MAT_INODE_LIMIT_3=70,MAT_INODE_LIMIT_4=71,MAT_INODE_LIMIT_5=72,
260:               MAT_IGNORE_OFF_PROC_ENTRIES=73,MAT_ROWS_UNSORTED=74,
261:               MAT_COLUMNS_UNSORTED=75,MAT_NEW_NONZERO_LOCATION_ERR=76,
262:               MAT_NEW_NONZERO_ALLOCATION_ERR=77,MAT_USE_HASH_TABLE=78,
263:               MAT_KEEP_ZEROED_ROWS=79,MAT_IGNORE_ZERO_ENTRIES=80,MAT_USE_INODES=81,
264:               MAT_DO_NOT_USE_INODES=82,MAT_NOT_SYMMETRIC=83,MAT_HERMITIAN=84,
265:               MAT_NOT_STRUCTURALLY_SYMMETRIC=85,MAT_NOT_HERMITIAN=86,
266:               MAT_SYMMETRY_ETERNAL=87,MAT_NOT_SYMMETRY_ETERNAL=88} MatOption;
267: EXTERN int MatSetOption(Mat,MatOption);
268: EXTERN int MatGetType(Mat,MatType*);

270: EXTERN int MatGetValues(Mat,int,const int[],int,const int[],PetscScalar[]);
271: EXTERN int MatGetRow(Mat,int,int *,int *[],PetscScalar*[]);
272: EXTERN int MatRestoreRow(Mat,int,int *,int *[],PetscScalar*[]);
273: EXTERN int MatGetColumn(Mat,int,int *,int *[],PetscScalar*[]);
274: EXTERN int MatRestoreColumn(Mat,int,int *,int *[],PetscScalar*[]);
275: EXTERN int MatGetColumnVector(Mat,Vec,int);
276: EXTERN int MatGetArray(Mat,PetscScalar *[]);
277: EXTERN int MatRestoreArray(Mat,PetscScalar *[]);
278: EXTERN int MatGetBlockSize(Mat,int *);

280: EXTERN int MatMult(Mat,Vec,Vec);
281: EXTERN int MatMultAdd(Mat,Vec,Vec,Vec);
282: EXTERN int MatMultTranspose(Mat,Vec,Vec);
283: EXTERN int MatIsTranspose(Mat,Mat,PetscTruth*);
284: EXTERN int MatMultTransposeAdd(Mat,Vec,Vec,Vec);
285: EXTERN int MatMultConstrained(Mat,Vec,Vec);
286: EXTERN int MatMultTransposeConstrained(Mat,Vec,Vec);

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

292:     Level: beginner

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

296: .seealso: MatDuplicate()
297: E*/
298: typedef enum {MAT_DO_NOT_COPY_VALUES,MAT_COPY_VALUES} MatDuplicateOption;

300: EXTERN int MatConvertRegister(const char[],const char[],const char[],int (*)(Mat,MatType,Mat*));
301: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
302: #define MatConvertRegisterDynamic(a,b,c,d) MatConvertRegister(a,b,c,0)
303: #else
304: #define MatConvertRegisterDynamic(a,b,c,d) MatConvertRegister(a,b,c,d)
305: #endif
306: EXTERN int        MatConvertRegisterAll(const char[]);
307: EXTERN int        MatConvertRegisterDestroy(void);
308: extern PetscTruth MatConvertRegisterAllCalled;
309: extern PetscFList MatConvertList;
310: EXTERN int        MatConvert(Mat,const MatType,Mat*);
311: EXTERN int        MatDuplicate(Mat,MatDuplicateOption,Mat*);

313: /*E
314:     MatStructure - Indicates if the matrix has the same nonzero structure

316:     Level: beginner

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

320: .seealso: MatCopy(), KSPSetOperators(), PCSetOperators()
321: E*/
322: typedef enum {SAME_NONZERO_PATTERN,DIFFERENT_NONZERO_PATTERN,SAME_PRECONDITIONER,SUBSET_NONZERO_PATTERN} MatStructure;

324: EXTERN int MatCopy(Mat,Mat,MatStructure);
325: EXTERN int MatView(Mat,PetscViewer);
326: EXTERN int MatIsSymmetric(Mat,PetscTruth*);
327: EXTERN int MatLoad(PetscViewer,const MatType,Mat*);
328: EXTERN int MatMerge(MPI_Comm,Mat,Mat*);

330: EXTERN int MatGetRowIJ(Mat,int,PetscTruth,int*,int *[],int *[],PetscTruth *);
331: EXTERN int MatRestoreRowIJ(Mat,int,PetscTruth,int *,int *[],int *[],PetscTruth *);
332: EXTERN int MatGetColumnIJ(Mat,int,PetscTruth,int*,int *[],int *[],PetscTruth *);
333: EXTERN int MatRestoreColumnIJ(Mat,int,PetscTruth,int *,int *[],int *[],PetscTruth *);

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

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

340:    Level: intermediate

342:   Concepts: matrix^nonzero information

344: .seealso:  MatGetInfo(), MatInfoType
345: S*/
346: typedef struct {
347:   PetscLogDouble rows_global,columns_global;         /* number of global rows and columns */
348:   PetscLogDouble rows_local,columns_local;           /* number of local rows and columns */
349:   PetscLogDouble block_size;                         /* block size */
350:   PetscLogDouble nz_allocated,nz_used,nz_unneeded;   /* number of nonzeros */
351:   PetscLogDouble memory;                             /* memory allocated */
352:   PetscLogDouble assemblies;                         /* number of matrix assemblies called */
353:   PetscLogDouble mallocs;                            /* number of mallocs during MatSetValues() */
354:   PetscLogDouble fill_ratio_given,fill_ratio_needed; /* fill ratio for LU/ILU */
355:   PetscLogDouble factor_mallocs;                     /* number of mallocs during factorization */
356: } MatInfo;

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

362:     Level: beginner

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

366: .seealso: MatGetInfo(), MatInfo
367: E*/
368: typedef enum {MAT_LOCAL=1,MAT_GLOBAL_MAX=2,MAT_GLOBAL_SUM=3} MatInfoType;
369: EXTERN int MatGetInfo(Mat,MatInfoType,MatInfo*);
370: EXTERN int MatValid(Mat,PetscTruth*);
371: EXTERN int MatGetDiagonal(Mat,Vec);
372: EXTERN int MatGetRowMax(Mat,Vec);
373: EXTERN int MatTranspose(Mat,Mat*);
374: EXTERN int MatPermute(Mat,IS,IS,Mat *);
375: EXTERN int MatPermuteSparsify(Mat,int,PetscReal,PetscReal,IS,IS,Mat *);
376: EXTERN int MatDiagonalScale(Mat,Vec,Vec);
377: EXTERN int MatDiagonalSet(Mat,Vec,InsertMode);
378: EXTERN int MatEqual(Mat,Mat,PetscTruth*);

380: EXTERN int MatNorm(Mat,NormType,PetscReal *);
381: EXTERN int MatZeroEntries(Mat);
382: EXTERN int MatZeroRows(Mat,IS,const PetscScalar*);
383: EXTERN int MatZeroColumns(Mat,IS,const PetscScalar*);

385: EXTERN int MatUseScaledForm(Mat,PetscTruth);
386: EXTERN int MatScaleSystem(Mat,Vec,Vec);
387: EXTERN int MatUnScaleSystem(Mat,Vec,Vec);

389: EXTERN int MatGetSize(Mat,int*,int*);
390: EXTERN int MatGetLocalSize(Mat,int*,int*);
391: EXTERN int MatGetOwnershipRange(Mat,int*,int*);

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

397:     Level: beginner

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

401: .seealso: MatGetSubMatrices(), MatGetSubMatrix(), MatDestroyMatrices()
402: E*/
403: typedef enum {MAT_INITIAL_MATRIX,MAT_REUSE_MATRIX} MatReuse;
404: EXTERN int MatGetSubMatrices(Mat,int,const IS[],const IS[],MatReuse,Mat *[]);
405: EXTERN int MatDestroyMatrices(int,Mat *[]);
406: EXTERN int MatGetSubMatrix(Mat,IS,IS,int,MatReuse,Mat *);

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

410: EXTERN int MatAXPY(const PetscScalar *,Mat,Mat,MatStructure);
411: EXTERN int MatAYPX(const PetscScalar *,Mat,Mat);
412: EXTERN int MatCompress(Mat);

414: EXTERN int MatScale(const PetscScalar *,Mat);
415: EXTERN int MatShift(const PetscScalar *,Mat);

417: EXTERN int MatSetLocalToGlobalMapping(Mat,ISLocalToGlobalMapping);
418: EXTERN int MatSetLocalToGlobalMappingBlock(Mat,ISLocalToGlobalMapping);
419: EXTERN int MatZeroRowsLocal(Mat,IS,const PetscScalar*);
420: EXTERN int MatSetValuesLocal(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);
421: EXTERN int MatSetValuesBlockedLocal(Mat,int,const int[],int,const int[],const PetscScalar[],InsertMode);

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

425: EXTERN int MatInterpolateAdd(Mat,Vec,Vec,Vec);
426: EXTERN int MatInterpolate(Mat,Vec,Vec);
427: EXTERN int MatRestrict(Mat,Vec,Vec);


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

434:    Synopsis:
435:    int MatPreallocateInitialize(MPI_Comm comm, int nrows, int ncols, int *dnz, int *onz)

437:    Collective on MPI_Comm

439:    Input Parameters:
440: +  comm - the communicator that will share the eventually allocated matrix
441: .  nrows - the number of rows in the matrix
442: -  ncols - the number of columns in the matrix

444:    Output Parameters:
445: +  dnz - the array that will be passed to the matrix preallocation routines
446: -  ozn - the other array passed to the matrix preallocation routines


449:    Level: intermediate

451:    Notes:
452:    See the chapter in the users manual on performance for more details

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

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

458:   Concepts: preallocation^Matrix

460: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
461:           MatPreallocateInitializeSymmetric(), MatPreallocateSymmetricSetLocal()
462: M*/
463: #define MatPreallocateInitialize(comm,nrows,ncols,dnz,onz) 0; \
464: { \
465:   int _4_ierr,__tmp = (nrows),__ctmp = (ncols),__rstart,__start,__end; \
466:   _4_PetscMalloc(2*__tmp*sizeof(int),&dnz);CHKERRQ(_4_ierr);onz = dnz + __tmp;\
467:   _4_PetscMemzero(dnz,2*__tmp*sizeof(int));CHKERRQ(_4_ierr);\
468:   _4_MPI_Scan(&__ctmp,&__end,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __start = __end - __ctmp;\
469:   _4_MPI_Scan(&__tmp,&__rstart,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __rstart = __rstart - __tmp;

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

475:    Synopsis:
476:    int MatPreallocateSymmetricInitialize(MPI_Comm comm, int nrows, int ncols, int *dnz, int *onz)

478:    Collective on MPI_Comm

480:    Input Parameters:
481: +  comm - the communicator that will share the eventually allocated matrix
482: .  nrows - the number of rows in the matrix
483: -  ncols - the number of columns in the matrix

485:    Output Parameters:
486: +  dnz - the array that will be passed to the matrix preallocation routines
487: -  ozn - the other array passed to the matrix preallocation routines


490:    Level: intermediate

492:    Notes:
493:    See the chapter in the users manual on performance for more details

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

497:   Concepts: preallocation^Matrix

499: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
500:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal()
501: M*/
502: #define MatPreallocateSymmetricInitialize(comm,nrows,ncols,dnz,onz) 0; \
503: { \
504:   int _4_ierr,__tmp = (nrows),__ctmp = (ncols),__rstart,__end; \
505:   _4_PetscMalloc(2*__tmp*sizeof(int),&dnz);CHKERRQ(_4_ierr);onz = dnz + __tmp;\
506:   _4_PetscMemzero(dnz,2*__tmp*sizeof(int));CHKERRQ(_4_ierr);\
507:   _4_MPI_Scan(&__ctmp,&__end,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr);\
508:   _4_MPI_Scan(&__tmp,&__rstart,1,MPI_INT,MPI_SUM,comm);CHKERRQ(_4_ierr); __rstart = __rstart - __tmp;

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

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

517:    Not Collective

519:    Input Parameters:
520: +  map - the mapping between local numbering and global numbering
521: .  nrows - the number of rows indicated
522: .  rows - the indices of the rows 
523: .  ncols - the number of columns in the matrix
524: .  cols - the columns indicated
525: .  dnz - the array that will be passed to the matrix preallocation routines
526: -  ozn - the other array passed to the matrix preallocation routines


529:    Level: intermediate

531:    Notes:
532:    See the chapter in the users manual on performance for more details

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

536:   Concepts: preallocation^Matrix

538: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
539:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal()
540: M*/
541: #define MatPreallocateSetLocal(map,nrows,rows,ncols,cols,dnz,onz) 0;\
542: {\
543:   int __l;\
544:   _4_ISLocalToGlobalMappingApply(map,nrows,rows,rows);CHKERRQ(_4_ierr);\
545:   _4_ISLocalToGlobalMappingApply(map,ncols,cols,cols);CHKERRQ(_4_ierr);\
546:   for (__l=0;__l<nrows;__l++) {\
547:     _4_MatPreallocateSet((rows)[__l],ncols,cols,dnz,onz);CHKERRQ(_4_ierr);\
548:   }\
549: }
550: 
551: /*MC
552:    MatPreallocateSymmetricSetLocal - Indicates the locations (rows and columns) in the matrix where nonzeros will be
553:        inserted using a local number of the rows and columns

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

558:    Not Collective

560:    Input Parameters:
561: +  map - the mapping between local numbering and global numbering
562: .  nrows - the number of rows indicated
563: .  rows - the indices of the rows 
564: .  ncols - the number of columns in the matrix
565: .  cols - the columns indicated
566: .  dnz - the array that will be passed to the matrix preallocation routines
567: -  ozn - the other array passed to the matrix preallocation routines


570:    Level: intermediate

572:    Notes:
573:    See the chapter in the users manual on performance for more details

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

577:   Concepts: preallocation^Matrix

579: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
580:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
581: M*/
582: #define MatPreallocateSymmetricSetLocal(map,nrows,rows,ncols,cols,dnz,onz) 0;\
583: {\
584:   int __l;\
585:   _4_ISLocalToGlobalMappingApply(map,nrows,rows,rows);CHKERRQ(_4_ierr);\
586:   _4_ISLocalToGlobalMappingApply(map,ncols,cols,cols);CHKERRQ(_4_ierr);\
587:   for (__l=0;__l<nrows;__l++) {\
588:     _4_MatPreallocateSymmetricSet((rows)[__l],ncols,cols,dnz,onz);CHKERRQ(_4_ierr);\
589:   }\
590: }

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

596:    Synopsis:
597:    int MatPreallocateSet(int nrows, int *rows,int ncols, int *cols,int *dnz, int *onz)

599:    Not Collective

601:    Input Parameters:
602: +  nrows - the number of rows indicated
603: .  rows - the indices of the rows 
604: .  ncols - the number of columns in the matrix
605: .  cols - the columns indicated
606: .  dnz - the array that will be passed to the matrix preallocation routines
607: -  ozn - the other array passed to the matrix preallocation routines


610:    Level: intermediate

612:    Notes:
613:    See the chapter in the users manual on performance for more details

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

617:   Concepts: preallocation^Matrix

619: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
620:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
621: M*/
622: #define MatPreallocateSet(row,nc,cols,dnz,onz) 0;\
623: { int __i; \
624:   for (__i=0; __i<nc; __i++) {\
625:     if (cols[__i] < __start || cols[__i] >= __end) onz[row - __rstart]++; \
626:   }\
627:   dnz[row - __rstart] = nc - onz[row - __rstart];\
628: }

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

634:    Synopsis:
635:    int MatPreallocateSymmetricSet(int nrows, int *rows,int ncols, int *cols,int *dnz, int *onz)

637:    Not Collective

639:    Input Parameters:
640: +  nrows - the number of rows indicated
641: .  rows - the indices of the rows 
642: .  ncols - the number of columns in the matrix
643: .  cols - the columns indicated
644: .  dnz - the array that will be passed to the matrix preallocation routines
645: -  ozn - the other array passed to the matrix preallocation routines


648:    Level: intermediate

650:    Notes:
651:    See the chapter in the users manual on performance for more details

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

655:   Concepts: preallocation^Matrix

657: .seealso: MatPreallocateFinalize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateInitialize(),
658:           MatPreallocateInitialize(), MatPreallocateSymmetricSetLocal(), MatPreallocateSetLocal()
659: M*/
660: #define MatPreallocateSymmetricSet(row,nc,cols,dnz,onz) 0;\
661: { int __i; \
662:   for (__i=0; __i<nc; __i++) {\
663:     if (cols[__i] >= __end) onz[row - __rstart]++; \
664:     else if (cols[__i] >= row) dnz[row - __rstart]++;\
665:   }\
666: }

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

672:    Synopsis:
673:    int MatPreallocateFinalize(int *dnz, int *onz)

675:    Collective on MPI_Comm

677:    Input Parameters:
678: +  dnz - the array that will be passed to the matrix preallocation routines
679: -  ozn - the other array passed to the matrix preallocation routines


682:    Level: intermediate

684:    Notes:
685:    See the chapter in the users manual on performance for more details

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

689:   Concepts: preallocation^Matrix

691: .seealso: MatPreallocateInitialize(), MatPreallocateSet(), MatPreallocateSymmetricSet(), MatPreallocateSetLocal(),
692:           MatPreallocateSymmetricInitialize(), MatPreallocateSymmetricSetLocal()
693: M*/
694: #define MatPreallocateFinalize(dnz,onz) 0;_4_PetscFree(dnz);CHKERRQ(_4_ierr);}



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

701: EXTERN int MatBDiagGetData(Mat,int*,int*,int*[],int*[],PetscScalar***);
702: EXTERN int MatSeqAIJSetColumnIndices(Mat,int[]);
703: EXTERN int MatSeqBAIJSetColumnIndices(Mat,int[]);
704: EXTERN int MatCreateSeqAIJWithArrays(MPI_Comm,int,int,int[],int[],PetscScalar[],Mat*);

706: EXTERN int MatSeqBAIJSetPreallocation(Mat,int,int,const int[]);
707: EXTERN int MatSeqSBAIJSetPreallocation(Mat,int,int,const int[]);
708: EXTERN int MatSeqAIJSetPreallocation(Mat,int,const int[]);
709: EXTERN int MatSeqDensePreallocation(Mat,PetscScalar[]);
710: EXTERN int MatSeqBDiagSetPreallocation(Mat,int,int,const int[],PetscScalar*[]);
711: EXTERN int MatSeqDenseSetPreallocation(Mat,PetscScalar[]);

713: EXTERN int MatMPIBAIJSetPreallocation(Mat,int,int,const int[],int,const int[]);
714: EXTERN int MatMPISBAIJSetPreallocation(Mat,int,int,const int[],int,const int[]);
715: EXTERN int MatMPIAIJSetPreallocation(Mat,int,const int[],int,const int[]);
716: EXTERN int MatMPIDensePreallocation(Mat,PetscScalar[]);
717: EXTERN int MatMPIBDiagSetPreallocation(Mat,int,int,const int[],PetscScalar*[]);
718: EXTERN int MatMPIAdjSetPreallocation(Mat,int[],int[],int[]);
719: EXTERN int MatMPIDenseSetPreallocation(Mat,PetscScalar[]);
720: EXTERN int MatMPIRowbsSetPreallocation(Mat,int,const int[]);
721: EXTERN int MatMPIAIJGetSeqAIJ(Mat,Mat*,Mat*,int*[]);
722: EXTERN int MatMPIBAIJGetSeqBAIJ(Mat,Mat*,Mat*,int*[]);
723: EXTERN int MatAdicSetLocalFunction(Mat,void (*)(void));

725: EXTERN int MatSeqDenseSetLDA(Mat,int);

727: EXTERN int MatStoreValues(Mat);
728: EXTERN int MatRetrieveValues(Mat);

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

732: /* 
733:   These routines are not usually accessed directly, rather solving is 
734:   done through the KSP and PC interfaces.
735: */

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

742:    Level: beginner

744: .seealso: MatGetOrdering()
745: E*/
746: #define MatOrderingType char*
747: #define MATORDERING_NATURAL   "natural"
748: #define MATORDERING_ND        "nd"
749: #define MATORDERING_1WD       "1wd"
750: #define MATORDERING_RCM       "rcm"
751: #define MATORDERING_QMD       "qmd"
752: #define MATORDERING_ROWLENGTH "rowlength"
753: #define MATORDERING_DSC_ND    "dsc_nd"
754: #define MATORDERING_DSC_MMD   "dsc_mmd"
755: #define MATORDERING_DSC_MDF   "dsc_mdf"
756: #define MATORDERING_CONSTRAINED "constrained"
757: #define MATORDERING_IDENTITY  "identity"
758: #define MATORDERING_REVERSE   "reverse"

760: EXTERN int MatGetOrdering(Mat,const MatOrderingType,IS*,IS*);
761: EXTERN int MatOrderingRegister(const char[],const char[],const char[],int(*)(Mat,const MatOrderingType,IS*,IS*));

763: /*MC
764:    MatOrderingRegisterDynamic - Adds a new sparse matrix ordering to the 
765:                                matrix package. 

767:    Synopsis:
768:    int MatOrderingRegisterDynamic(char *name_ordering,char *path,char *name_create,int (*routine_create)(MatOrdering))

770:    Not Collective

772:    Input Parameters:
773: +  sname - name of ordering (for example MATORDERING_ND)
774: .  path - location of library where creation routine is 
775: .  name - name of function that creates the ordering type,a string
776: -  function - function pointer that creates the ordering

778:    Level: developer

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

783:    Sample usage:
784: .vb
785:    MatOrderingRegisterDynamic("my_order",/home/username/my_lib/lib/libO/solaris/mylib.a,
786:                "MyOrder",MyOrder);
787: .ve

789:    Then, your partitioner can be chosen with the procedural interface via
790: $     MatOrderingSetType(part,"my_order)
791:    or at runtime via the option
792: $     -pc_ilu_mat_ordering_type my_order
793: $     -pc_lu_mat_ordering_type my_order

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

797: .keywords: matrix, ordering, register

799: .seealso: MatOrderingRegisterDestroy(), MatOrderingRegisterAll()
800: M*/
801: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
802: #define MatOrderingRegisterDynamic(a,b,c,d) MatOrderingRegister(a,b,c,0)
803: #else
804: #define MatOrderingRegisterDynamic(a,b,c,d) MatOrderingRegister(a,b,c,d)
805: #endif

807: EXTERN int        MatOrderingRegisterDestroy(void);
808: EXTERN int        MatOrderingRegisterAll(const char[]);
809: extern PetscTruth MatOrderingRegisterAllCalled;
810: extern PetscFList MatOrderingList;

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

814: /*S 
815:    MatFactorInfo - Data based into the matrix factorization routines

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

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

821:    Level: developer

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

825: S*/
826: typedef struct {
827:   PetscReal     damping;        /* scaling of identity added to matrix to prevent zero pivots */
828:   PetscReal     shift;          /* if true, shift until positive pivots */
829:   PetscReal     shift_fraction; /* record shift fraction taken */
830:   PetscReal     diagonal_fill;  /* force diagonal to fill in if initially not filled */
831:   PetscReal     dt;             /* drop tolerance */
832:   PetscReal     dtcol;          /* tolerance for pivoting */
833:   PetscReal     dtcount;        /* maximum nonzeros to be allowed per row */
834:   PetscReal     fill;           /* expected fill; nonzeros in factored matrix/nonzeros in original matrix*/
835:   PetscReal     levels;         /* ICC/ILU(levels) */
836:   PetscReal     pivotinblocks;  /* for BAIJ and SBAIJ matrices pivot in factorization on blocks, default 1.0 
837:                                    factorization may be faster if do not pivot */
838:   PetscReal     zeropivot;      /* pivot is called zero if less than this */
839: } MatFactorInfo;

841: EXTERN int MatCholeskyFactor(Mat,IS,MatFactorInfo*);
842: EXTERN int MatCholeskyFactorSymbolic(Mat,IS,MatFactorInfo*,Mat*);
843: EXTERN int MatCholeskyFactorNumeric(Mat,Mat*);
844: EXTERN int MatLUFactor(Mat,IS,IS,MatFactorInfo*);
845: EXTERN int MatILUFactor(Mat,IS,IS,MatFactorInfo*);
846: EXTERN int MatLUFactorSymbolic(Mat,IS,IS,MatFactorInfo*,Mat*);
847: EXTERN int MatILUFactorSymbolic(Mat,IS,IS,MatFactorInfo*,Mat*);
848: EXTERN int MatICCFactorSymbolic(Mat,IS,MatFactorInfo*,Mat*);
849: EXTERN int MatICCFactor(Mat,IS,MatFactorInfo*);
850: EXTERN int MatLUFactorNumeric(Mat,Mat*);
851: EXTERN int MatILUDTFactor(Mat,MatFactorInfo*,IS,IS,Mat *);
852: EXTERN int MatGetInertia(Mat,int*,int*,int*);
853: EXTERN int MatSolve(Mat,Vec,Vec);
854: EXTERN int MatForwardSolve(Mat,Vec,Vec);
855: EXTERN int MatBackwardSolve(Mat,Vec,Vec);
856: EXTERN int MatSolveAdd(Mat,Vec,Vec,Vec);
857: EXTERN int MatSolveTranspose(Mat,Vec,Vec);
858: EXTERN int MatSolveTransposeAdd(Mat,Vec,Vec,Vec);
859: EXTERN int MatSolves(Mat,Vecs,Vecs);

861: EXTERN int MatSetUnfactored(Mat);

863: /*E
864:     MatSORType - What type of (S)SOR to perform

866:     Level: beginner

868:    May be bitwise ORd together

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

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

874: .seealso: MatRelax(), MatPBRelax()
875: E*/
876: typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3,
877:               SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8,
878:               SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16,
879:               SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128} MatSORType;
880: EXTERN int MatRelax(Mat,Vec,PetscReal,MatSORType,PetscReal,int,int,Vec);
881: EXTERN int MatPBRelax(Mat,Vec,PetscReal,MatSORType,PetscReal,int,int,Vec);

883: /* 
884:     These routines are for efficiently computing Jacobians via finite differences.
885: */

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

892:    Level: beginner

894: .seealso: MatGetColoring()
895: E*/
896: #define MatColoringType char*
897: #define MATCOLORING_NATURAL "natural"
898: #define MATCOLORING_SL      "sl"
899: #define MATCOLORING_LF      "lf"
900: #define MATCOLORING_ID      "id"

902: EXTERN int MatGetColoring(Mat,const MatColoringType,ISColoring*);
903: EXTERN int MatColoringRegister(const char[],const char[],const char[],int(*)(Mat,const MatColoringType,ISColoring *));

905: /*MC
906:    MatColoringRegisterDynamic - Adds a new sparse matrix coloring to the 
907:                                matrix package. 

909:    Synopsis:
910:    int MatColoringRegisterDynamic(char *name_coloring,char *path,char *name_create,int (*routine_create)(MatColoring))

912:    Not Collective

914:    Input Parameters:
915: +  sname - name of Coloring (for example MATCOLORING_SL)
916: .  path - location of library where creation routine is 
917: .  name - name of function that creates the Coloring type, a string
918: -  function - function pointer that creates the coloring

920:    Level: developer

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

925:    Sample usage:
926: .vb
927:    MatColoringRegisterDynamic("my_color",/home/username/my_lib/lib/libO/solaris/mylib.a,
928:                "MyColor",MyColor);
929: .ve

931:    Then, your partitioner can be chosen with the procedural interface via
932: $     MatColoringSetType(part,"my_color")
933:    or at runtime via the option
934: $     -mat_coloring_type my_color

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

938: .keywords: matrix, Coloring, register

940: .seealso: MatColoringRegisterDestroy(), MatColoringRegisterAll()
941: M*/
942: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
943: #define MatColoringRegisterDynamic(a,b,c,d) MatColoringRegister(a,b,c,0)
944: #else
945: #define MatColoringRegisterDynamic(a,b,c,d) MatColoringRegister(a,b,c,d)
946: #endif

948: EXTERN int        MatColoringRegisterAll(const char[]);
949: extern PetscTruth MatColoringRegisterAllCalled;
950: EXTERN int        MatColoringRegisterDestroy(void);
951: EXTERN int        MatColoringPatch(Mat,int,int,const ISColoringValue[],ISColoring*);

953: /*S
954:      MatFDColoring - Object for computing a sparse Jacobian via finite differences
955:         and coloring

957:    Level: beginner

959:   Concepts: coloring, sparse Jacobian, finite differences

961: .seealso:  MatFDColoringCreate()
962: S*/
963: typedef struct _p_MatFDColoring *MatFDColoring;

965: EXTERN int MatFDColoringCreate(Mat,ISColoring,MatFDColoring *);
966: EXTERN int MatFDColoringDestroy(MatFDColoring);
967: EXTERN int MatFDColoringView(MatFDColoring,PetscViewer);
968: EXTERN int MatFDColoringSetFunction(MatFDColoring,int (*)(void),void*);
969: EXTERN int MatFDColoringSetParameters(MatFDColoring,PetscReal,PetscReal);
970: EXTERN int MatFDColoringSetFrequency(MatFDColoring,int);
971: EXTERN int MatFDColoringGetFrequency(MatFDColoring,int*);
972: EXTERN int MatFDColoringSetFromOptions(MatFDColoring);
973: EXTERN int MatFDColoringApply(Mat,MatFDColoring,Vec,MatStructure*,void *);
974: EXTERN int MatFDColoringApplyTS(Mat,MatFDColoring,PetscReal,Vec,MatStructure*,void *);
975: EXTERN int MatFDColoringSetRecompute(MatFDColoring);
976: EXTERN int MatFDColoringSetF(MatFDColoring,Vec);
977: EXTERN int MatFDColoringGetPerturbedColumns(MatFDColoring,int*,int*[]);
978: /* 
979:     These routines are for partitioning matrices: currently used only 
980:   for adjacency matrix, MatCreateMPIAdj().
981: */

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

986:    Level: beginner

988:   Concepts: partitioning

990: .seealso:  MatPartitioningCreate(), MatPartitioningType
991: S*/
992: typedef struct _p_MatPartitioning *MatPartitioning;

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

999:    Level: beginner

1001: .seealso: MatPartitioningCreate(), MatPartitioning
1002: E*/
1003: #define MatPartitioningType char*
1004: #define MAT_PARTITIONING_CURRENT  "current"
1005: #define MAT_PARTITIONING_PARMETIS "parmetis"
1006: #define MAT_PARTITIONING_CHACO    "chaco"
1007: #define MAT_PARTITIONING_JOSTLE   "jostle"
1008: #define MAT_PARTITIONING_PARTY    "party"
1009: #define MAT_PARTITIONING_SCOTCH   "scotch"


1012: EXTERN int MatPartitioningCreate(MPI_Comm,MatPartitioning*);
1013: EXTERN int MatPartitioningSetType(MatPartitioning,const MatPartitioningType);
1014: EXTERN int MatPartitioningSetNParts(MatPartitioning,int);
1015: EXTERN int MatPartitioningSetAdjacency(MatPartitioning,Mat);
1016: EXTERN int MatPartitioningSetVertexWeights(MatPartitioning,const int[]);
1017: EXTERN int MatPartitioningSetPartitionWeights(MatPartitioning,const PetscReal []);
1018: EXTERN int MatPartitioningApply(MatPartitioning,IS*);
1019: EXTERN int MatPartitioningDestroy(MatPartitioning);

1021: EXTERN int MatPartitioningRegister(const char[],const char[],const char[],int(*)(MatPartitioning));

1023: /*MC
1024:    MatPartitioningRegisterDynamic - Adds a new sparse matrix partitioning to the 
1025:    matrix package. 

1027:    Synopsis:
1028:    int MatPartitioningRegisterDynamic(char *name_partitioning,char *path,char *name_create,int (*routine_create)(MatPartitioning))

1030:    Not Collective

1032:    Input Parameters:
1033: +  sname - name of partitioning (for example MAT_PARTITIONING_CURRENT) or parmetis
1034: .  path - location of library where creation routine is 
1035: .  name - name of function that creates the partitioning type, a string
1036: -  function - function pointer that creates the partitioning type

1038:    Level: developer

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

1043:    Sample usage:
1044: .vb
1045:    MatPartitioningRegisterDynamic("my_part",/home/username/my_lib/lib/libO/solaris/mylib.a,
1046:                "MyPartCreate",MyPartCreate);
1047: .ve

1049:    Then, your partitioner can be chosen with the procedural interface via
1050: $     MatPartitioningSetType(part,"my_part")
1051:    or at runtime via the option
1052: $     -mat_partitioning_type my_part

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

1056: .keywords: matrix, partitioning, register

1058: .seealso: MatPartitioningRegisterDestroy(), MatPartitioningRegisterAll()
1059: M*/
1060: #if defined(PETSC_USE_DYNAMIC_LIBRARIES)
1061: #define MatPartitioningRegisterDynamic(a,b,c,d) MatPartitioningRegister(a,b,c,0)
1062: #else
1063: #define MatPartitioningRegisterDynamic(a,b,c,d) MatPartitioningRegister(a,b,c,d)
1064: #endif

1066: EXTERN int        MatPartitioningRegisterAll(const char[]);
1067: extern PetscTruth MatPartitioningRegisterAllCalled;
1068: EXTERN int        MatPartitioningRegisterDestroy(void);

1070: EXTERN int MatPartitioningView(MatPartitioning,PetscViewer);
1071: EXTERN int MatPartitioningSetFromOptions(MatPartitioning);
1072: EXTERN int MatPartitioningGetType(MatPartitioning,MatPartitioningType*);

1074: EXTERN int MatPartitioningParmetisSetCoarseSequential(MatPartitioning);

1076: EXTERN int MatPartitioningJostleSetCoarseLevel(MatPartitioning,PetscReal);
1077: EXTERN int MatPartitioningJostleSetCoarseSequential(MatPartitioning);

1079: typedef enum { MP_CHACO_MULTILEVEL_KL, MP_CHACO_SPECTRAL, MP_CHACO_LINEAR,
1080:     MP_CHACO_RANDOM, MP_CHACO_SCATTERED } MPChacoGlobalType;
1081: EXTERN int MatPartitioningChacoSetGlobal(MatPartitioning, MPChacoGlobalType);
1082: typedef enum { MP_CHACO_KERNIGHAN_LIN, MP_CHACO_NONE } MPChacoLocalType;
1083: EXTERN int MatPartitioningChacoSetLocal(MatPartitioning, MPChacoLocalType);
1084: EXTERN int MatPartitioningChacoSetCoarseLevel(MatPartitioning,PetscReal);
1085: typedef enum { MP_CHACO_LANCZOS, MP_CHACO_RQI_SYMMLQ } MPChacoEigenType;
1086: EXTERN int MatPartitioningChacoSetEigenSolver(MatPartitioning,MPChacoEigenType);
1087: EXTERN int MatPartitioningChacoSetEigenTol(MatPartitioning, PetscReal);
1088: EXTERN int MatPartitioningChacoSetEigenNumber(MatPartitioning, int);

1090: #define MP_PARTY_OPT "opt"
1091: #define MP_PARTY_LIN "lin"
1092: #define MP_PARTY_SCA "sca"
1093: #define MP_PARTY_RAN "ran"
1094: #define MP_PARTY_GBF "gbf"
1095: #define MP_PARTY_GCF "gcf"
1096: #define MP_PARTY_BUB "bub"
1097: #define MP_PARTY_DEF "def"
1098: EXTERN int MatPartitioningPartySetGlobal(MatPartitioning, const char*);
1099: #define MP_PARTY_HELPFUL_SETS "hs"
1100: #define MP_PARTY_KERNIGHAN_LIN "kl"
1101: #define MP_PARTY_NONE "no"
1102: EXTERN int MatPartitioningPartySetLocal(MatPartitioning, const char*);
1103: EXTERN int MatPartitioningPartySetCoarseLevel(MatPartitioning,PetscReal);
1104: EXTERN int MatPartitioningPartySetBipart(MatPartitioning,PetscTruth);
1105: EXTERN int MatPartitioningPartySetMatchOptimization(MatPartitioning,PetscTruth);

1107: typedef enum { MP_SCOTCH_GREEDY, MP_SCOTCH_GPS, MP_SCOTCH_GR_GPS } MPScotchGlobalType;
1108: EXTERN int MatPartitioningScotchSetArch(MatPartitioning,const char*);
1109: EXTERN int MatPartitioningScotchSetMultilevel(MatPartitioning);
1110: EXTERN int MatPartitioningScotchSetGlobal(MatPartitioning,MPScotchGlobalType);
1111: EXTERN int MatPartitioningScotchSetCoarseLevel(MatPartitioning,PetscReal);
1112: EXTERN int MatPartitioningScotchSetHostList(MatPartitioning,const char*);
1113: typedef enum { MP_SCOTCH_KERNIGHAN_LIN, MP_SCOTCH_NONE } MPScotchLocalType;
1114: EXTERN int MatPartitioningScotchSetLocal(MatPartitioning,MPScotchLocalType);
1115: EXTERN int MatPartitioningScotchSetMapping(MatPartitioning);
1116: EXTERN int MatPartitioningScotchSetStrategy(MatPartitioning,char*);

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

1210: /*
1211:    Codes for matrices stored on disk. By default they are
1212:  stored in a universal format. By changing the format with 
1213:  PetscViewerSetFormat(viewer,PETSC_VIEWER_BINARY_NATIVE); the matrices will
1214:  be stored in a way natural for the matrix, for example dense matrices
1215:  would be stored as dense. Matrices stored this way may only be
1216:  read into matrices of the same time.
1217: */
1218: #define MATRIX_BINARY_FORMAT_DENSE -1

1220: EXTERN int MatMPIBAIJSetHashTableFactor(Mat,PetscReal);
1221: EXTERN int MatSeqAIJGetInodeSizes(Mat,int *,int *[],int *);
1222: EXTERN int MatMPIRowbsGetColor(Mat,ISColoring *);

1224: EXTERN int MatISGetLocalMat(Mat,Mat*);

1226: /*S
1227:      MatNullSpace - Object that removes a null space from a vector, i.e.
1228:          orthogonalizes the vector to a subsapce

1230:    Level: advanced

1232:   Concepts: matrix; linear operator, null space

1234:   Users manual sections:
1235: .   Section 4.15 Solving Singular Systems

1237: .seealso:  MatNullSpaceCreate()
1238: S*/
1239: typedef struct _p_MatNullSpace* MatNullSpace;

1241: EXTERN int MatNullSpaceCreate(MPI_Comm,int,int,const Vec[],MatNullSpace*);
1242: EXTERN int MatNullSpaceDestroy(MatNullSpace);
1243: EXTERN int MatNullSpaceRemove(MatNullSpace,Vec,Vec*);
1244: EXTERN int MatNullSpaceAttach(Mat,MatNullSpace);
1245: EXTERN int MatNullSpaceTest(MatNullSpace,Mat);

1247: EXTERN int MatReorderingSeqSBAIJ(Mat A,IS isp);
1248: EXTERN int MatMPISBAIJSetHashTableFactor(Mat,PetscReal);
1249: EXTERN int MatSeqSBAIJSetColumnIndices(Mat,int *);

1251: EXTERN int MatMatMult(Mat A,Mat B, Mat *C);
1252: EXTERN int MatMatMultSymbolic(Mat A,Mat B,Mat *C);
1253: EXTERN int MatMatMultNumeric(Mat A,Mat B,Mat C);

1255: EXTERN int MatCreateMAIJ(Mat,int,Mat*);
1256: EXTERN int MatMAIJRedimension(Mat,int,Mat*);
1257: EXTERN int MatMAIJGetAIJ(Mat,Mat*);

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

1261: EXTERN int MatESISetType(Mat,const char*);
1262: EXTERN int MatESISetFromOptions(Mat);

1264: EXTERN int MatDiagonalScaleLocal(Mat,Vec);

1266: EXTERN int PetscViewerMathematicaPutMatrix(PetscViewer, int, int, PetscReal *);
1267: EXTERN int PetscViewerMathematicaPutCSRMatrix(PetscViewer, int, int, int *, int *, PetscReal *);

1269: EXTERN int MatSeqAIJPtAP(Mat,Mat,Mat*);

1271: PETSC_EXTERN_CXX_END
1272: #endif