Actual source code: matio.c

      1: #define PETSCMAT_DLL

      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 PetscErrorCode MatLoadPrintHelp_Private(Mat A)
     13: {
     14:   static PetscTruth called = PETSC_FALSE;
     15:   MPI_Comm          comm = A->comm;
     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 -viewer_binary_skip_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:    PETSc automatically does the byte swapping for
     99: machines that store the bytes reversed, e.g.  DEC alpha, freebsd,
    100: linux, Windows and the paragon; thus if you write your own binary
    101: read/write routines you have to swap the bytes; see PetscBinaryRead()
    102: and PetscBinaryWrite() to see how this may be done.

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

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

    108:  @*/
    109: PetscErrorCode PETSCMAT_DLLEXPORT MatLoad(PetscViewer viewer, MatType outtype,Mat *newmat)
    110: {
    111:   Mat            factory;
    113:   PetscTruth     isbinary,flg;
    114:   MPI_Comm       comm;
    115:   PetscErrorCode (*r)(PetscViewer, MatType,Mat*);
    116:   char           mtype[256];
    117:   const char     *prefix;

    122:   *newmat = 0;

    124:   PetscObjectGetOptionsPrefix((PetscObject)viewer,(const char **)&prefix);
    125:   PetscTypeCompare((PetscObject)viewer,PETSC_VIEWER_BINARY,&isbinary);
    126:   if (!isbinary) {
    127:     SETERRQ(PETSC_ERR_ARG_WRONG,"Invalid viewer; open viewer with PetscViewerBinaryOpen()");
    128:   }

    130:   PetscOptionsGetString(prefix,"-mat_type",mtype,256,&flg);
    131:   if (flg) {
    132:     outtype = mtype;
    133:   }
    134:   PetscOptionsGetString(prefix,"-matload_type",mtype,256,&flg);
    135:   if (flg) {
    136:     outtype = mtype;
    137:   }
    138:   if (!outtype) outtype = MATAIJ;

    140:   PetscObjectGetComm((PetscObject)viewer,&comm);
    141:   MatCreate(comm,&factory);
    142:   MatSetSizes(factory,0,0,0,0);
    143:   MatSetType(factory,outtype);
    144:   r = factory->ops->load;
    145:   MatDestroy(factory);
    146:   if (!r) SETERRQ1(PETSC_ERR_SUP,"MatLoad is not supported for type: %s",outtype);

    148:   PetscLogEventBegin(MAT_Load,viewer,0,0,0);
    149:   (*r)(viewer,outtype,newmat);
    150:   PetscLogEventEnd(MAT_Load,viewer,0,0,0);

    152:   PetscOptionsHasName(prefix,"-matload_symmetric",&flg);
    153:   if (flg) {
    154:     MatSetOption(*newmat,MAT_SYMMETRIC);
    155:     MatSetOption(*newmat,MAT_SYMMETRY_ETERNAL);
    156:   }
    157:   PetscOptionsHasName(PETSC_NULL,"-help",&flg);
    158:   if (flg) {MatLoadPrintHelp_Private(*newmat); }
    159:   return(0);
    160: }