/* $Id: mat.h,v 1.102 1996/04/09 02:23:45 curfman Exp bsmith $ */
/*
     Include file for the matrix component of PETSc
*/
#ifndef __MAT_PACKAGE
#define __MAT_PACKAGE
#include "vec.h"

#define MAT_COOKIE         PETSC_COOKIE+5

typedef struct _Mat*           Mat;

typedef enum { MATSAME=-1, MATSEQDENSE, MATSEQAIJ, MATMPIAIJ, MATSHELL, 
               MATMPIROWBS, MATSEQBDIAG, MATMPIBDIAG,
               MATMPIDENSE, MATSEQBAIJ } MatType;

extern int MatCreate(MPI_Comm,int,int,Mat*);
extern int MatCreateSeqDense(MPI_Comm,int,int,Scalar*,Mat*);
extern int MatCreateMPIDense(MPI_Comm,int,int,int,int,Scalar*,Mat*); 
extern int MatCreateSeqAIJ(MPI_Comm,int,int,int,int*,Mat*);
extern int MatCreateMPIAIJ(MPI_Comm,int,int,int,int,int,int*,int,int*,Mat*); 
extern int MatCreateMPIRowbs(MPI_Comm,int,int,int,int*,void*,Mat*); 
extern int MatCreateSeqBDiag(MPI_Comm,int,int,int,int,int*,Scalar**,Mat*); 
extern int MatCreateMPIBDiag(MPI_Comm,int,int,int,int,int,int*,Scalar**,Mat*); 
extern int MatCreateSeqBAIJ(MPI_Comm,int,int,int,int,int*,Mat*); 

extern int MatDestroy(Mat);

extern int MatCreateShell(MPI_Comm,int,int,int,int,void *,Mat*);
extern int MatShellGetContext(Mat,void **);

  
extern int MatPrintHelp(Mat);

/* ------------------------------------------------------------*/
extern int MatSetValues(Mat,int,int*,int,int*,Scalar*,InsertMode);
typedef enum {FLUSH_ASSEMBLY=1,FINAL_ASSEMBLY=0} MatAssemblyType;
extern int MatAssemblyBegin(Mat,MatAssemblyType);
extern int MatAssemblyEnd(Mat,MatAssemblyType);

typedef enum {ROW_ORIENTED=1,COLUMN_ORIENTED=2,ROWS_SORTED=4,
              COLUMNS_SORTED=8,NO_NEW_NONZERO_LOCATIONS=16,
              YES_NEW_NONZERO_LOCATIONS=32,SYMMETRIC_MATRIX=64,
              STRUCTURALLY_SYMMETRIC_MATRIX,NO_NEW_DIAGONALS,
              YES_NEW_DIAGONALS,INODE_LIMIT_1,INODE_LIMIT_2,
              INODE_LIMIT_3,INODE_LIMIT_4,INODE_LIMIT_5} MatOption;
extern int MatSetOption(Mat,MatOption);
extern int MatGetType(Mat,MatType*,char**);
extern int MatGetTypeFromOptions(MPI_Comm,char*,MatType*,int*);
extern int MatGetValues(Mat,int,int*,int,int*,Scalar*);
extern int MatGetRow(Mat,int,int *,int **,Scalar**);
extern int MatRestoreRow(Mat,int,int *,int **,Scalar**);
extern int MatGetColumn(Mat,int,int *,int **,Scalar**);
extern int MatRestoreColumn(Mat,int,int *,int **,Scalar**);
extern int MatGetArray(Mat,Scalar **);
extern int MatRestoreArray(Mat,Scalar **);

extern int MatMult(Mat,Vec,Vec);
extern int MatMultAdd(Mat,Vec,Vec,Vec);
extern int MatMultTrans(Mat,Vec,Vec);
extern int MatMultTransAdd(Mat,Vec,Vec,Vec);

extern int MatConvert(Mat,MatType,Mat*);
extern int MatCopy(Mat,Mat);
extern int MatView(Mat,Viewer);
extern int MatLoad(Viewer,MatType,Mat*);

typedef enum {MAT_LOCAL=1,MAT_GLOBAL_MAX=2,MAT_GLOBAL_SUM=3} MatInfoType;
extern int MatGetInfo(Mat,MatInfoType,int*,int*,int*);
extern int MatValid(Mat,PetscTruth*);
extern int MatGetDiagonal(Mat,Vec);
extern int MatTranspose(Mat,Mat*);
extern int MatDiagonalScale(Mat,Vec,Vec);
extern int MatDiagonalShift(Mat,Vec);
extern int MatEqual(Mat,Mat, PetscTruth*);

extern int MatNorm(Mat,NormType,double *);
extern int MatZeroEntries(Mat);
extern int MatZeroRows(Mat,IS,Scalar*);
extern int MatZeroColumns(Mat,IS,Scalar*);

extern int MatGetSize(Mat,int*,int*);
extern int MatGetLocalSize(Mat,int*,int*);
extern int MatGetOwnershipRange(Mat,int*,int*);

typedef enum {MAT_INITIAL_MATRIX, MAT_REUSE_MATRIX} MatGetSubMatrixCall;
extern int MatGetSubMatrix(Mat,IS,IS,MatGetSubMatrixCall,Mat*);
extern int MatGetSubMatrixInPlace(Mat,IS,IS);
extern int MatGetSubMatrices(Mat,int,IS *,IS *,MatGetSubMatrixCall,Mat **);
extern int MatIncreaseOverlap(Mat,int,IS *,int);

extern int MatAXPY(Scalar *,Mat,Mat);
extern int MatCompress(Mat);

extern int MatScale(Scalar *,Mat);
extern int MatShift(Scalar *,Mat);

/* Routines unique to particular data structures */
extern int MatBDiagGetData(Mat,int*,int*,int**,int**,Scalar***);

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

typedef enum {ORDER_NATURAL=0,ORDER_ND=1,ORDER_1WD=2,
              ORDER_RCM=3,ORDER_QMD=4,ORDER_ROWLENGTH=5,ORDER_APPLICATION_1,
              ORDER_APPLICATION_2} MatOrdering;
extern int MatGetReordering(Mat,MatOrdering,IS*,IS*);
extern int MatGetReorderingTypeFromOptions(char *,MatOrdering*);
extern int MatReorderForNonzeroDiagonal(Mat,double,IS,IS);
extern int MatReorderingRegister(MatOrdering *,char*,PetscTruth,int,
                                 int (*)(int*,int*,int*,int*,int*));
extern int MatReorderingRegisterAll();
extern int MatReorderingRegisterDestroy();
extern int MatReorderingGetName(MatOrdering,char **);
extern PetscTruth MatReorderingRequiresSymmetric[];
extern int MatReorderingIndexShift[];

extern int MatLUFactor(Mat,IS,IS,double);
extern int MatILUFactor(Mat,IS,IS,double,int);
extern int MatCholeskyFactor(Mat,IS,double);
extern int MatLUFactorSymbolic(Mat,IS,IS,double,Mat*);
extern int MatILUFactorSymbolic(Mat,IS,IS,double,int,Mat*);
extern int MatCholeskyFactorSymbolic(Mat,IS,double,Mat*);
extern int MatIncompleteCholeskyFactorSymbolic(Mat,IS,double,int,Mat*);
extern int MatLUFactorNumeric(Mat,Mat*);
extern int MatCholeskyFactorNumeric(Mat,Mat*);

extern int MatSolve(Mat,Vec,Vec);
extern int MatForwardSolve(Mat,Vec,Vec);
extern int MatBackwardSolve(Mat,Vec,Vec);
extern int MatSolveAdd(Mat,Vec,Vec,Vec);
extern int MatSolveTrans(Mat,Vec,Vec);
extern int MatSolveTransAdd(Mat,Vec,Vec,Vec);

typedef enum {SOR_FORWARD_SWEEP=1,SOR_BACKWARD_SWEEP=2,SOR_SYMMETRIC_SWEEP=3,
              SOR_LOCAL_FORWARD_SWEEP=4,SOR_LOCAL_BACKWARD_SWEEP=8,
              SOR_LOCAL_SYMMETRIC_SWEEP=12,SOR_ZERO_INITIAL_GUESS=16,
              SOR_EISENSTAT=32,SOR_APPLY_UPPER=64,SOR_APPLY_LOWER=128
              } MatSORType;
extern int MatRelax(Mat,Vec,double,MatSORType,double,int,Vec);

typedef enum { MAT_SET_VALUES=0,
               MAT_GET_ROW=1,
               MAT_RESTORE_ROW=2,
               MAT_MULT=3,
               MAT_MULT_ADD=4,
               MAT_MULT_TRANS=5,
               MAT_MULT_TRANS_ADD=6,
               MAT_SOLVE=7,
               MAT_SOLVE_ADD=8,
               MAT_SOLVE_TRANS=9,
               MAT_SOLVE_TRANS_ADD=10,
               MAT_LUFACTOR=11,
               MAT_CHOLESKYFACTOR=12,
               MAT_RELAX=13,
               MAT_TRANSPOSE=14,
               MAT_GETINFO=15,
               MAT_EQUAL=16,
               MAT_GET_DIAGONAL=17, 
               MAT_DIAGONAL_SCALE=18,
               MAT_NORM=19,
               MAT_ASSEMBLY_BEGIN=20,
               MAT_ASSEMBLY_END=21,
               MAT_COMPRESS=22,
               MAT_SET_OPTION=23,
               MAT_ZERO_ENTRIES=24,
               MAT_ZERO_ROWS=25,
               MAT_GET_REORDERING=26,
               MAT_LUFACTOR_SYMBOLIC=27,
               MAT_LUFACTOR_NUMERIC=28,
               MAT_CHOLESKY_FACTOR_SYMBOLIC=29,
               MAT_CHOLESKY_FACTOR_NUMERIC=30,
               MAT_GET_SIZE=31,
               MAT_GET_LOCAL_SIZE=32,
               MAT_GET_OWNERSHIP_RANGE=33,
               MAT_ILUFACTOR_SYMBOLIC=34,
               MAT_INCOMPLETECHOLESKYFACTOR_SYMBOLIC=35,
               MAT_GET_ARRAY=36,
               MAT_RESTORE_ARRAY=37,
               MAT_CONVERT=38,
               MAT_GET_SUBMATRIX=39,
               MAT_GET_SUBMATRIX_INPLACE=40,
               MAT_CONVERT_SAME_TYPE=41,
               MAT_FORWARD_SOLVE=42,
               MAT_BACKWARD_SOLVE=43,
               MAT_ILUFACTOR=44,
               MAT_INCOMPLETECHOLEKSYFACTOR=45,
               MAT_AXPY=46,
               MAT_GET_SUBMATRICES=47,
               MAT_INCREASE_OVERLAP=48,
               MAT_GET_VALUES=49,
               MAT_COPY=50,
               MAT_PRINT_HELP=51,
               MAT_SCALE=52,
               MAT_SHIFT=53,
               MAT_DIAGONAL_SHIFT=54,
               MAT_DESTROY=250,
               MAT_VIEW=251
             } MatOperation;
extern int MatHasOperation(Mat,MatOperation,PetscTruth*);
extern int MatShellSetOperation(Mat,MatOperation,void *);

/*  Not currently supported! 
#define MAT_SCATTER_COOKIE PETSC_COOKIE+15
typedef struct _MatScatter* MatScatter;

extern int MatScatterBegin(Mat,Mat,InsertMode,MatScatter);
extern int MatScatterEnd(Mat,Mat,InsertMode,MatScatter);
extern int MatScatterCreate(Mat,IS,IS,Mat,IS,IS,MatScatter*);
extern int MatScatterDestroy(MatScatter);
*/

/*
   Codes for matrices stored on disk. By default they are
 stored in a universal format. By changing the format with 
 ViewerSetFormat(viewer,BINARY_FORMAT_NATIVE); the matrices will
 be stored in a way natural for the matrix, for example dense matrices
 would be stored as dense. Matrices stored this way may only be
 read into matrices of the same time.
*/
#define MATRIX_BINARY_FORMAT_DENSE -1

#endif