Actual source code: matio.c

  1: /*$Id: matio.c,v 1.79 2001/08/06 21:16:10 bsmith Exp $*/

  3: /* 
  4:    This file contains simple binary read/write routines for matrices.
  5:  */

 7:  #include src/mat/matimpl.h
 8:  #include petscsys.h

 12: static int MatLoadPrintHelp_Private(Mat A)
 13: {
 14:   static PetscTruth called = PETSC_FALSE;
 15:   MPI_Comm          comm = A->comm;
 16:   int               ierr;
 17: 
 19:   if (called) {return(0);} else called = PETSC_TRUE;
 20:   (*PetscHelpPrintf)(comm," Options for MatLoad:\n");
 21:   (*PetscHelpPrintf)(comm,"  -mat_type <type>\n");
 22:   (*PetscHelpPrintf)(comm,"  -matload_type <type>\n");
 23:   (*PetscHelpPrintf)(comm,"  -matload_block_size <block_size> :Used for MATBAIJ, MATBDIAG\n");
 24:   (*PetscHelpPrintf)(comm,"  -matload_bdiag_diags <s1,s2,s3,...> : Used for MATBDIAG\n");
 25:   return(0);
 26: }

 30: /*@C
 31:    MatLoad - Loads a matrix that has been stored in binary format
 32:    with MatView().  The matrix format is determined from the options database.
 33:    Generates a parallel MPI matrix if the communicator has more than one
 34:    processor.  The default matrix type is AIJ.

 36:    Collective on PetscViewer

 38:    Input Parameters:
 39: +  viewer - binary file viewer, created with PetscViewerBinaryOpen()
 40: -  outtype - type of matrix desired, for example MATSEQAIJ,
 41:              MATMPIROWBS, etc.  See types in petsc/include/petscmat.h.

 43:    Output Parameters:
 44: .  newmat - new matrix

 46:    Basic Options Database Keys:
 47: +    -matload_type seqaij   - AIJ type
 48: .    -matload_type mpiaij   - parallel AIJ type
 49: .    -matload_type seqbaij  - block AIJ type
 50: .    -matload_type mpibaij  - parallel block AIJ type
 51: .    -matload_type seqsbaij - block symmetric AIJ type
 52: .    -matload_type mpisbaij - parallel block symmetric AIJ type
 53: .    -matload_type seqbdiag - block diagonal type
 54: .    -matload_type mpibdiag - parallel block diagonal type
 55: .    -matload_type mpirowbs - parallel rowbs type
 56: .    -matload_type seqdense - dense type
 57: .    -matload_type mpidense - parallel dense type
 58: -    -matload_symmetric - matrix in file is symmetric

 60:    More Options Database Keys:
 61:    Used with block matrix formats (MATSEQBAIJ, MATMPIBDIAG, ...) to specify
 62:    block size
 63: .    -matload_block_size <bs>

 65:    Used to specify block diagonal numbers for MATSEQBDIAG and MATMPIBDIAG formats
 66: .    -matload_bdiag_diags <s1,s2,s3,...>

 68:    Level: beginner

 70:    Notes:
 71:    MatLoad() automatically loads into the options database any options
 72:    given in the file filename.info where filename is the name of the file
 73:    that was passed to the PetscViewerBinaryOpen(). The options in the info
 74:    file will be ignored if you use the -matload_ignore_info option.

 76:    In parallel, each processor can load a subset of rows (or the
 77:    entire matrix).  This routine is especially useful when a large
 78:    matrix is stored on disk and only part of it existsis desired on each
 79:    processor.  For example, a parallel solver may access only some of
 80:    the rows from each processor.  The algorithm used here reads
 81:    relatively small blocks of data rather than reading the entire
 82:    matrix and then subsetting it.

 84:    Notes for advanced users:
 85:    Most users should not need to know the details of the binary storage
 86:    format, since MatLoad() and MatView() completely hide these details.
 87:    But for anyone who's interested, the standard binary matrix storage
 88:    format is

 90: $    int    MAT_FILE_COOKIE
 91: $    int    number of rows
 92: $    int    number of columns
 93: $    int    total number of nonzeros
 94: $    int    *number nonzeros in each row
 95: $    int    *column indices of all nonzeros (starting index is zero)
 96: $    PetscScalar *values of all nonzeros

 98:    Note for Cray users, the int's stored in the binary file are 32 bit
 99: integers; not 64 as they are represented in the memory, so if you
100: write your own routines to read/write these binary files from the Cray
101: you need to adjust the integer sizes that you read in, see
102: PetscReadBinary() and PetscWriteBinary() to see how this may be
103: done.

105:    In addition, PETSc automatically does the byte swapping for
106: machines that store the bytes reversed, e.g.  DEC alpha, freebsd,
107: linux, nt and the paragon; thus if you write your own binary
108: read/write routines you have to swap the bytes; see PetscReadBinary()
109: and PetscWriteBinary() to see how this may be done.

111: .keywords: matrix, load, binary, input

113: .seealso: PetscViewerBinaryOpen(), MatView(), VecLoad()

115:  @*/
116: int MatLoad(PetscViewer viewer,const MatType outtype,Mat *newmat)
117: {
118:   Mat         factory;
119:   int         ierr;
120:   PetscTruth  isbinary,flg;
121:   MPI_Comm    comm;
122:   int         (*r)(PetscViewer,const MatType,Mat*);
123:   char        mtype[256],*prefix;

128:   *newmat = 0;

130:   PetscObjectGetOptionsPrefix((PetscObject)viewer,&prefix);
131:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_BINARY,&isbinary);
132:   if (!isbinary) {
133:     SETERRQ(PETSC_ERR_ARG_WRONG,"Invalid viewer; open viewer with PetscViewerBinaryOpen()");
134:   }

136:   PetscOptionsGetString(prefix,"-mat_type",mtype,256,&flg);
137:   if (flg) {
138:     outtype = mtype;
139:   }
140:   PetscOptionsGetString(prefix,"-matload_type",mtype,256,&flg);
141:   if (flg) {
142:     outtype = mtype;
143:   }
144:   if (!outtype) outtype = MATAIJ;

146:   PetscObjectGetComm((PetscObject)viewer,&comm);
147:   MatCreate(comm,0,0,0,0,&factory);
148:   MatSetType(factory,outtype);
149:   r = factory->ops->load;
150:   MatDestroy(factory);
151:   if (!r) SETERRQ1(PETSC_ERR_SUP,"MatLoad is not supported for type: %s",outtype);

153:   PetscLogEventBegin(MAT_Load,viewer,0,0,0);
154:   (*r)(viewer,outtype,newmat);
155:   PetscLogEventEnd(MAT_Load,viewer,0,0,0);

157:   PetscOptionsHasName(prefix,"-matload_symmetric",&flg);
158:   if (flg) {
159:     MatSetOption(*newmat,MAT_SYMMETRIC);
160:     MatSetOption(*newmat,MAT_SYMMETRY_ETERNAL);
161:   }
162:   PetscOptionsHasName(PETSC_NULL,"-help",&flg);
163:   if (flg) {MatLoadPrintHelp_Private(*newmat); }
164:   return(0);
165: }