petsc/include/petscmat.h

*d4fbbf0eSBarry Smith/* $Id: mat.h,v 1.113 1996/08/22 22:25:21 curfman Exp bsmith $ */
2eac72dbSBarry Smith/*
2eac72dbSBarry Smith     Include file for the matrix component of PETSc
2eac72dbSBarry Smith*/
1eb62cbbSBarry Smith#ifndef __MAT_PACKAGE
1eb62cbbSBarry Smith#define __MAT_PACKAGE
8ed539a5SBarry Smith#include "vec.h"
2eac72dbSBarry Smith
9cd28387SBarry Smith#define MAT_COOKIE         PETSC_COOKIE+5
f0479e8cSBarry Smith
2eac72dbSBarry Smithtypedef struct _Mat*           Mat;
2eac72dbSBarry Smith
4ac9ca07SLois Curfman McInnestypedef enum { MATSAME=-1, MATSEQDENSE, MATSEQAIJ, MATMPIAIJ, MATSHELL,
c456f294SBarry Smith               MATMPIROWBS, MATSEQBDIAG, MATMPIBDIAG,
a20e3d60SSatish Balay               MATMPIDENSE, MATSEQBAIJ, MATMPIBAIJ} MatType;
28988994SBarry Smith
0e998a85SBarry Smithextern int MatCreate(MPI_Comm,int,int,Mat*);
df6e0191SLois Curfman McInnesextern int MatCreateSeqDense(MPI_Comm,int,int,Scalar*,Mat*);
d5bc1036SLois Curfman McInnesextern int MatCreateMPIDense(MPI_Comm,int,int,int,int,Scalar*,Mat*);
de7da479SBarry Smithextern int MatCreateSeqAIJ(MPI_Comm,int,int,int,int*,Mat*);
9717bf64SBarry Smithextern int MatCreateMPIAIJ(MPI_Comm,int,int,int,int,int,int*,int,int*,Mat*);
cfe223acSLois Curfman McInnesextern int MatCreateMPIRowbs(MPI_Comm,int,int,int,int*,void*,Mat*);
f26ada1bSBarry Smithextern int MatCreateSeqBDiag(MPI_Comm,int,int,int,int,int*,Scalar**,Mat*);
f26ada1bSBarry Smithextern int MatCreateMPIBDiag(MPI_Comm,int,int,int,int,int,int*,Scalar**,Mat*);
df8a92d1SBarry Smithextern int MatCreateSeqBAIJ(MPI_Comm,int,int,int,int,int*,Mat*);
eba03b66SLois Curfman McInnesextern int MatCreateMPIBAIJ(MPI_Comm,int,int,int,int,int,int,int*,int,int*,Mat*);
9717bf64SBarry Smith
7b80b807SBarry Smithextern int MatDestroy(Mat);
7b80b807SBarry Smith
7ddc982cSLois Curfman McInnesextern int MatCreateShell(MPI_Comm,int,int,int,int,void *,Mat*);
17116c71SBarry Smithextern int MatShellGetContext(Mat,void **);
21c89e3eSBarry Smith
2eac72dbSBarry Smith
ec0117caSBarry Smithextern int MatPrintHelp(Mat);
ec0117caSBarry Smith
8ed539a5SBarry Smith/* ------------------------------------------------------------*/
ee50ffe9SBarry Smithextern int MatSetValues(Mat,int,int*,int,int*,Scalar*,InsertMode);
6d4a8577SBarry Smithtypedef enum {MAT_FLUSH_ASSEMBLY=1,MAT_FINAL_ASSEMBLY=0} MatAssemblyType;
ee50ffe9SBarry Smithextern int MatAssemblyBegin(Mat,MatAssemblyType);
ee50ffe9SBarry Smithextern int MatAssemblyEnd(Mat,MatAssemblyType);
ee50ffe9SBarry Smith
6d4a8577SBarry Smithtypedef enum {MAT_ROW_ORIENTED=1,MAT_COLUMN_ORIENTED=2,MAT_ROWS_SORTED=4,
6d4a8577SBarry Smith              MAT_COLUMNS_SORTED=8,MAT_NO_NEW_NONZERO_LOCATIONS=16,
6d4a8577SBarry Smith              MAT_YES_NEW_NONZERO_LOCATIONS=32,MAT_SYMMETRIC=64,
6d4a8577SBarry Smith              MAT_STRUCTURALLY_SYMMETRIC,MAT_NO_NEW_DIAGONALS,
6d4a8577SBarry Smith              MAT_YES_NEW_DIAGONALS,MAT_INODE_LIMIT_1,MAT_INODE_LIMIT_2,
6d4a8577SBarry Smith              MAT_INODE_LIMIT_3,MAT_INODE_LIMIT_4,MAT_INODE_LIMIT_5} MatOption;
ee50ffe9SBarry Smithextern int MatSetOption(Mat,MatOption);
4b0e389bSBarry Smithextern int MatGetType(Mat,MatType*,char**);
77c4ece6SBarry Smithextern int MatGetTypeFromOptions(MPI_Comm,char*,MatType*,int*);
ee50ffe9SBarry Smithextern int MatGetValues(Mat,int,int*,int,int*,Scalar*);
8ed539a5SBarry Smithextern int MatGetRow(Mat,int,int *,int **,Scalar**);
8ed539a5SBarry Smithextern int MatRestoreRow(Mat,int,int *,int **,Scalar**);
77c4ece6SBarry Smithextern int MatGetColumn(Mat,int,int *,int **,Scalar**);
77c4ece6SBarry Smithextern int MatRestoreColumn(Mat,int,int *,int **,Scalar**);
64e87e97SBarry Smithextern int MatGetArray(Mat,Scalar **);
09883261SBarry Smithextern int MatRestoreArray(Mat,Scalar **);
870582ebSSatish Balayextern int MatGetBlockSize(Mat,int *);
7b80b807SBarry Smith
8ed539a5SBarry Smithextern int MatMult(Mat,Vec,Vec);
8ed539a5SBarry Smithextern int MatMultAdd(Mat,Vec,Vec,Vec);
8ed539a5SBarry Smithextern int MatMultTrans(Mat,Vec,Vec);
8ed539a5SBarry Smithextern int MatMultTransAdd(Mat,Vec,Vec,Vec);
2eac72dbSBarry Smith
7b80b807SBarry Smithextern int MatConvert(Mat,MatType,Mat*);
7b80b807SBarry Smithextern int MatCopy(Mat,Mat);
7b80b807SBarry Smithextern int MatView(Mat,Viewer);
7b80b807SBarry Smithextern int MatLoad(Viewer,MatType,Mat*);
7b80b807SBarry Smith
*d4fbbf0eSBarry Smithextern int MatGetRowIJ(Mat,int,PetscTruth,int*,int **,int **,PetscTruth *);
*d4fbbf0eSBarry Smithextern int MatRestoreRowIJ(Mat,int,PetscTruth,int *,int **,int **,PetscTruth *);
*d4fbbf0eSBarry Smithextern int MatGetColumnIJ(Mat,int,PetscTruth,int*,int **,int **,PetscTruth *);
*d4fbbf0eSBarry Smithextern int MatRestoreColumnIJ(Mat,int,PetscTruth,int *,int **,int **,PetscTruth *);
*d4fbbf0eSBarry Smith
1d607229SLois Curfman McInnes/*
1d607229SLois Curfman McInnes   Context of matrix information, used with MatGetInfo()
1d607229SLois Curfman McInnes   Note: If any entries are added to this context, be sure
1d607229SLois Curfman McInnes         to adjust MAT_INFO_SIZE in FINCLUDE/mat.h
1d607229SLois Curfman McInnes */
4e220ebcSLois Curfman McInnestypedef struct {
4e220ebcSLois Curfman McInnes  double rows_global, columns_global;         /* number of global rows and columns */
4e220ebcSLois Curfman McInnes  double rows_local, columns_local;           /* number of local rows and columns */
4e220ebcSLois Curfman McInnes  double block_size;                          /* block size */
4e220ebcSLois Curfman McInnes  double nz_allocated, nz_used, nz_unneeded;  /* number of nonzeros */
4e220ebcSLois Curfman McInnes  double memory;                              /* memory allocated */
4e220ebcSLois Curfman McInnes  double assemblies;                          /* number of matrix assemblies */
4e220ebcSLois Curfman McInnes  double mallocs;                             /* number of mallocs during MatSetValues() */
4e220ebcSLois Curfman McInnes  double fill_ratio_given, fill_ratio_needed; /* fill ration for LU/ILU */
4e220ebcSLois Curfman McInnes  double factor_mallocs;                      /* number of mallocs during factorization */
4e220ebcSLois Curfman McInnes} MatInfo;
4e220ebcSLois Curfman McInnes
7b80b807SBarry Smithtypedef enum {MAT_LOCAL=1,MAT_GLOBAL_MAX=2,MAT_GLOBAL_SUM=3} MatInfoType;
4e220ebcSLois Curfman McInnesextern int MatGetInfo(Mat,MatInfoType,MatInfo*);
77c4ece6SBarry Smithextern int MatValid(Mat,PetscTruth*);
7b80b807SBarry Smithextern int MatGetDiagonal(Mat,Vec);
cd8486b4SBarry Smithextern int MatTranspose(Mat,Mat*);
f4c33d5aSBarry Smithextern int MatDiagonalScale(Mat,Vec,Vec);
8b3e568eSBarry Smithextern int MatDiagonalShift(Mat,Vec);
77c4ece6SBarry Smithextern int MatEqual(Mat,Mat, PetscTruth*);
7b80b807SBarry Smith
7b80b807SBarry Smithextern int MatNorm(Mat,NormType,double *);
7b80b807SBarry Smithextern int MatZeroEntries(Mat);
7b80b807SBarry Smithextern int MatZeroRows(Mat,IS,Scalar*);
7b80b807SBarry Smithextern int MatZeroColumns(Mat,IS,Scalar*);
7b80b807SBarry Smith
7b80b807SBarry Smithextern int MatGetSize(Mat,int*,int*);
7b80b807SBarry Smithextern int MatGetLocalSize(Mat,int*,int*);
7b80b807SBarry Smithextern int MatGetOwnershipRange(Mat,int*,int*);
7b80b807SBarry Smith
7b80b807SBarry Smithtypedef enum {MAT_INITIAL_MATRIX, MAT_REUSE_MATRIX} MatGetSubMatrixCall;
7b80b807SBarry Smithextern int MatGetSubMatrices(Mat,int,IS *,IS *,MatGetSubMatrixCall,Mat **);
905e6a2fSBarry Smithextern int MatDestroyMatrices(int, Mat **);
7b80b807SBarry Smithextern int MatIncreaseOverlap(Mat,int,IS *,int);
7b80b807SBarry Smith
7b80b807SBarry Smithextern int MatAXPY(Scalar *,Mat,Mat);
7b80b807SBarry Smithextern int MatCompress(Mat);
7b80b807SBarry Smith
052efed2SBarry Smithextern int MatScale(Scalar *,Mat);
052efed2SBarry Smithextern int MatShift(Scalar *,Mat);
052efed2SBarry Smith
7b80b807SBarry Smith/* Routines unique to particular data structures */
7b80b807SBarry Smithextern int MatBDiagGetData(Mat,int*,int*,int**,int**,Scalar***);
7b80b807SBarry Smith
7b80b807SBarry Smith/*
7b80b807SBarry Smith  These routines are not usually accessed directly, rather solving is
7b80b807SBarry Smith  done through the SLES, KSP and PC interfaces.
7b80b807SBarry Smith*/
7b80b807SBarry Smith
83f0b094SBarry Smithtypedef enum {ORDER_NATURAL=0,ORDER_ND=1,ORDER_1WD=2,
a2ce50c7SBarry Smith              ORDER_RCM=3,ORDER_QMD=4,ORDER_ROWLENGTH=5,ORDER_FLOW,
a2ce50c7SBarry Smith              ORDER_APPLICATION_1,ORDER_APPLICATION_2} MatReordering;
a2ce50c7SBarry Smithextern int MatGetReordering(Mat,MatReordering,IS*,IS*);
a2ce50c7SBarry Smithextern int MatGetReorderingTypeFromOptions(char *,MatReordering*);
*d4fbbf0eSBarry Smithextern int MatReorderingRegister(MatReordering *,char*,int (*)(Mat,MatReordering,IS*,IS*));
464493b3SBarry Smithextern int MatReorderingRegisterAll();
464493b3SBarry Smithextern int MatReorderingRegisterDestroy();
a2ce50c7SBarry Smithextern int MatReorderingGetName(MatReordering,char **);
*d4fbbf0eSBarry Smith
*d4fbbf0eSBarry Smithtypedef enum {COLORING_NATURAL, COLORING_SL, COLORING_LD, COLORING_IF,
*d4fbbf0eSBarry Smith              COLORING_APPLICATION_1,COLORING_APPLICATION_2} MatColoring;
*d4fbbf0eSBarry Smithextern int MatGetColoring(Mat,MatColoring,int *,IS**);
*d4fbbf0eSBarry Smithextern int MatGetColoringTypeFromOptions(char *,MatColoring*);
*d4fbbf0eSBarry Smithextern int MatColoringRegister(MatColoring *,char*,int (*)(Mat,MatColoring,int*,IS**));
*d4fbbf0eSBarry Smithextern int MatColoringRegisterAll();
*d4fbbf0eSBarry Smithextern int MatColoringRegisterDestroy();
2eac72dbSBarry Smith
a2ce50c7SBarry Smithextern int MatReorderForNonzeroDiagonal(Mat,double,IS,IS);
a2ce50c7SBarry Smith
a2ce50c7SBarry Smithextern int MatCholeskyFactor(Mat,IS,double);
a2ce50c7SBarry Smithextern int MatCholeskyFactorSymbolic(Mat,IS,double,Mat*);
a2ce50c7SBarry Smithextern int MatCholeskyFactorNumeric(Mat,Mat*);
a2ce50c7SBarry Smith
49d8b64dSBarry Smithextern int MatLUFactor(Mat,IS,IS,double);
d7b056bfSBarry Smithextern int MatILUFactor(Mat,IS,IS,double,int);
64051cb3SBarry Smithextern int MatLUFactorSymbolic(Mat,IS,IS,double,Mat*);
64051cb3SBarry Smithextern int MatILUFactorSymbolic(Mat,IS,IS,double,int,Mat*);
64051cb3SBarry Smithextern int MatIncompleteCholeskyFactorSymbolic(Mat,IS,double,int,Mat*);
20563c6bSBarry Smithextern int MatLUFactorNumeric(Mat,Mat*);
a2ce50c7SBarry Smithextern int MatILUDTFactor(Mat,double,int,IS,IS,Mat *);
a2ce50c7SBarry Smith
8ed539a5SBarry Smith
8ed539a5SBarry Smithextern int MatSolve(Mat,Vec,Vec);
22169318SLois Curfman McInnesextern int MatForwardSolve(Mat,Vec,Vec);
22169318SLois Curfman McInnesextern int MatBackwardSolve(Mat,Vec,Vec);
8ed539a5SBarry Smithextern int MatSolveAdd(Mat,Vec,Vec,Vec);
28988994SBarry Smithextern int MatSolveTrans(Mat,Vec,Vec);
28988994SBarry Smithextern int MatSolveTransAdd(Mat,Vec,Vec,Vec);
8ed539a5SBarry Smith
ee50ffe9SBarry Smithtypedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3,
ee50ffe9SBarry Smith              SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8,
ee50ffe9SBarry Smith              SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16,
ca9b4cbeSLois Curfman McInnes              SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128
ca9b4cbeSLois Curfman McInnes              } MatSORType;
ca9b4cbeSLois Curfman McInnesextern int MatRelax(Mat,Vec,double,MatSORType,double,int,Vec);
8ed539a5SBarry Smith
*d4fbbf0eSBarry Smith/*
*d4fbbf0eSBarry Smith    If you add entries here you must also add them to FINCLUDE/mat.h
*d4fbbf0eSBarry Smith*/
fae171e0SBarry Smithtypedef enum { MAT_SET_VALUES=0,
fae171e0SBarry Smith               MAT_GET_ROW=1,
fae171e0SBarry Smith               MAT_RESTORE_ROW=2,
fae171e0SBarry Smith               MAT_MULT=3,
fae171e0SBarry Smith               MAT_MULT_ADD=4,
fae171e0SBarry Smith               MAT_MULT_TRANS=5,
fae171e0SBarry Smith               MAT_MULT_TRANS_ADD=6,
fae171e0SBarry Smith               MAT_SOLVE=7,
fae171e0SBarry Smith               MAT_SOLVE_ADD=8,
fae171e0SBarry Smith               MAT_SOLVE_TRANS=9,
fae171e0SBarry Smith               MAT_SOLVE_TRANS_ADD=10,
fae171e0SBarry Smith               MAT_LUFACTOR=11,
fae171e0SBarry Smith               MAT_CHOLESKYFACTOR=12,
fae171e0SBarry Smith               MAT_RELAX=13,
fae171e0SBarry Smith               MAT_TRANSPOSE=14,
fae171e0SBarry Smith               MAT_GETINFO=15,
fae171e0SBarry Smith               MAT_EQUAL=16,
fae171e0SBarry Smith               MAT_GET_DIAGONAL=17,
fae171e0SBarry Smith               MAT_DIAGONAL_SCALE=18,
fae171e0SBarry Smith               MAT_NORM=19,
fae171e0SBarry Smith               MAT_ASSEMBLY_BEGIN=20,
fae171e0SBarry Smith               MAT_ASSEMBLY_END=21,
fae171e0SBarry Smith               MAT_COMPRESS=22,
fae171e0SBarry Smith               MAT_SET_OPTION=23,
fae171e0SBarry Smith               MAT_ZERO_ENTRIES=24,
fae171e0SBarry Smith               MAT_ZERO_ROWS=25,
*d4fbbf0eSBarry Smith               MAT_LUFACTOR_SYMBOLIC=26,
*d4fbbf0eSBarry Smith               MAT_LUFACTOR_NUMERIC=27,
*d4fbbf0eSBarry Smith               MAT_CHOLESKY_FACTOR_SYMBOLIC=28,
*d4fbbf0eSBarry Smith               MAT_CHOLESKY_FACTOR_NUMERIC=29,
*d4fbbf0eSBarry Smith               MAT_GET_SIZE=30,
*d4fbbf0eSBarry Smith               MAT_GET_LOCAL_SIZE=31,
*d4fbbf0eSBarry Smith               MAT_GET_OWNERSHIP_RANGE=32,
*d4fbbf0eSBarry Smith               MAT_ILUFACTOR_SYMBOLIC=33,
*d4fbbf0eSBarry Smith               MAT_INCOMPLETECHOLESKYFACTOR_SYMBOLIC=34,
*d4fbbf0eSBarry Smith               MAT_GET_ARRAY=35,
*d4fbbf0eSBarry Smith               MAT_RESTORE_ARRAY=36,
*d4fbbf0eSBarry Smith               MAT_CONVERT=37,
*d4fbbf0eSBarry Smith               MAT_GET_SUBMATRIX=38,
*d4fbbf0eSBarry Smith               MAT_GET_SUBMATRIX_INPLACE=39,
*d4fbbf0eSBarry Smith               MAT_CONVERT_SAME_TYPE=40,
*d4fbbf0eSBarry Smith               MAT_FORWARD_SOLVE=41,
*d4fbbf0eSBarry Smith               MAT_BACKWARD_SOLVE=42,
*d4fbbf0eSBarry Smith               MAT_ILUFACTOR=43,
*d4fbbf0eSBarry Smith               MAT_INCOMPLETECHOLESKYFACTOR=44,
*d4fbbf0eSBarry Smith               MAT_AXPY=45,
*d4fbbf0eSBarry Smith               MAT_GET_SUBMATRICES=46,
*d4fbbf0eSBarry Smith               MAT_INCREASE_OVERLAP=47,
*d4fbbf0eSBarry Smith               MAT_GET_VALUES=48,
*d4fbbf0eSBarry Smith               MAT_COPY=49,
*d4fbbf0eSBarry Smith               MAT_PRINT_HELP=50,
*d4fbbf0eSBarry Smith               MAT_SCALE=51,
*d4fbbf0eSBarry Smith               MAT_SHIFT=52,
*d4fbbf0eSBarry Smith               MAT_DIAGONAL_SHIFT=53,
*d4fbbf0eSBarry Smith               MAT_ILUDT_FACTOR=54,
*d4fbbf0eSBarry Smith               MAT_GET_BLOCK_SIZE=55,
fae171e0SBarry Smith               MAT_DESTROY=250,
fae171e0SBarry Smith               MAT_VIEW=251
fae171e0SBarry Smith             } MatOperation;
112a2221SBarry Smithextern int MatHasOperation(Mat,MatOperation,PetscTruth*);
fae171e0SBarry Smithextern int MatShellSetOperation(Mat,MatOperation,void *);
112a2221SBarry Smith
90ace30eSBarry Smith/*
90ace30eSBarry Smith   Codes for matrices stored on disk. By default they are
90ace30eSBarry Smith stored in a universal format. By changing the format with
90ace30eSBarry Smith ViewerSetFormat(viewer,BINARY_FORMAT_NATIVE); the matrices will
90ace30eSBarry Smith be stored in a way natural for the matrix, for example dense matrices
90ace30eSBarry Smith would be stored as dense. Matrices stored this way may only be
90ace30eSBarry Smith read into matrices of the same time.
90ace30eSBarry Smith*/
90ace30eSBarry Smith#define MATRIX_BINARY_FORMAT_DENSE -1
90ace30eSBarry Smith
2eac72dbSBarry Smith#endif
2eac72dbSBarry Smith
2eac72dbSBarry Smith
9d00d63dSBarry Smith