[next] [prev] [prev-tail] [tail] [up]

### 9 Utilities

We have some utilities available for input and output of sparse matrices; the interfaces to these routines are available in the module psb_util_mod.

#### 9.1 hb_read — Read a sparse matrix from a file in the Harwell–Boeing format

    call hb_read(a, iret, iunit, filename, b, mtitle)

Type:

  Asynchronous.

On Entry

filename

  The name of the file to be read.
  Type:optional.
  Specified as: a character variable containing a valid file name, or -, in which case the default input unit 5 (i.e. standard input in Unix jargon) is used. Default: -.

iunit

  The Fortran file unit number.
  Type:optional.
  Specified as: an integer value. Only meaningful if filename is not -.

On Return

a

  the sparse matrix read from file.
  Type:required.
  Specified as: a structured data of type psb_Tspmat_type.

b

  Rigth hand side(s).
  Type: Optional
  An array of type real or complex, rank 2 and having the ALLOCATABLE attribute; will be allocated and filled in if the input file contains a right hand side, otherwise will be left in the UNALLOCATED state.

mtitle

  Matrix title.
  Type: Optional
  A charachter variable of length 72 holding a copy of the matrix title as specified by the Harwell-Boeing format and contained in the input file.

iret

  Error code.
  Type: required
  An integer value; 0 means no error has been detected.

#### 9.2 hb_write — Write a sparse matrix to a file in the Harwell–Boeing format

    call hb_write(a, iret, iunit, filename, key, rhs, mtitle)

Type:

  Asynchronous.

On Entry

a

  the sparse matrix to be written.
  Type:required.
  Specified as: a structured data of type psb_Tspmat_type.

b

  Rigth hand side.
  Type: Optional
  An array of type real or complex, rank 1 and having the ALLOCATABLE attribute; will be allocated and filled in if the input file contains a right hand side.

filename

  The name of the file to be written to.
  Type:optional.
  Specified as: a character variable containing a valid file name, or -, in which case the default output unit 6 (i.e. standard output in Unix jargon) is used. Default: -.

iunit

  The Fortran file unit number.
  Type:optional.
  Specified as: an integer value. Only meaningful if filename is not -.

key

  Matrix key.
  Type: Optional
  A charachter variable of length 8 holding the matrix key as specified by the Harwell-Boeing format and to be written to file.

mtitle

  Matrix title.
  Type: Optional
  A charachter variable of length 72 holding the matrix title as specified by the Harwell-Boeing format and to be written to file.

On Return

iret

  Error code.
  Type: required
  An integer value; 0 means no error has been detected.

#### 9.3 mm_mat_read — Read a sparse matrix from a file in the MatrixMarket format

    call mm_mat_read(a, iret, iunit, filename)

Type:

  Asynchronous.

On Entry

filename

  The name of the file to be read.
  Type:optional.
  Specified as: a character variable containing a valid file name, or -, in which case the default input unit 5 (i.e. standard input in Unix jargon) is used. Default: -.

iunit

  The Fortran file unit number.
  Type:optional.
  Specified as: an integer value. Only meaningful if filename is not -.

On Return

a

  the sparse matrix read from file.
  Type:required.
  Specified as: a structured data of type psb_Tspmat_type.

iret

  Error code.
  Type: required
  An integer value; 0 means no error has been detected.

#### 9.4 mm_array_read — Read a dense array from a file in the MatrixMarket format

    call mm_array_read(b, iret, iunit, filename)

Type:

  Asynchronous.

On Entry

filename

  The name of the file to be read.
  Type:optional.
  Specified as: a character variable containing a valid file name, or -, in which case the default input unit 5 (i.e. standard input in Unix jargon) is used. Default: -.

iunit

  The Fortran file unit number.
  Type:optional.
  Specified as: an integer value. Only meaningful if filename is not -.

On Return

b

  Rigth hand side(s).
  Type: required
  An array of type real or complex, rank 1 or 2 and having the ALLOCATABLE attribute, or an object of type psb_T_vect_type, of type real or complex.
  Will be allocated and filled in if the input file contains a right hand side, otherwise will be left in the UNALLOCATED state.

iret

  Error code.
  Type: required
  An integer value; 0 means no error has been detected.

#### 9.5 mm_mat_write — Write a sparse matrix to a file in the MatrixMarket format

    call mm_mat_write(a, mtitle, iret, iunit, filename)

Type:

  Asynchronous.

On Entry

a

  the sparse matrix to be written.
  Type:required.
  Specified as: a structured data of type psb_Tspmat_type.

mtitle

  Matrix title.
  Type: required
  A charachter variable holding a descriptive title for the matrix to be written to file.

filename

  The name of the file to be written to.
  Type:optional.
  Specified as: a character variable containing a valid file name, or -, in which case the default output unit 6 (i.e. standard output in Unix jargon) is used. Default: -.

iunit

  The Fortran file unit number.
  Type:optional.
  Specified as: an integer value. Only meaningful if filename is not -.

On Return

iret

  Error code.
  Type: required
  An integer value; 0 means no error has been detected.

Notes

If this function is called on a matrix `a` on a distributed communicator only the local part is written in output. To get a single MatrixMarket file with the whole matrix when appropriate, e.g. for debugging purposes, one could gather the whole matrix on a single rank and then write it. Consider the following example for a double precision matrix

    type(psb_ldspmat_type) :: aglobal

    call psb_gather(aglobal,a,desc_a,info)
    if (iam == psb_root_) then
    call mm_mat_write(aglobal,mtitle,info,filename)
    end if
    call psb_spfree(aglobal, desc_a, info)

To simplify this procedure in C, there is a utility function

    psb_i_t psb_c_<s,d,c,z>global_mat_write(ah,cdh);

that produces exactly this result.

#### 9.6 mm_array_write — Write a dense array from a file in the MatrixMarket format

    call mm_array_write(b, vtitle, iret, iunit, filename)

Type:

  Asynchronous.

On Entry

b

  Rigth hand side(s).
  Type: required
  An array of type real or complex, rank 1 or 2, or an object of type psb_T_vect_type, of type real or complex; its contents will be written to disk.

filename

  The name of the file to be written.

vtitle

  Matrix title.
  Type: required
  A charachter variable holding a descriptive title for the vector to be written to file. Type:optional.
  Specified as: a character variable containing a valid file name, or -, in which case the default input unit 5 (i.e. standard input in Unix jargon) is used. Default: -.

iunit

  The Fortran file unit number.
  Type:optional.
  Specified as: an integer value. Only meaningful if filename is not -.

On Return

iret

  Error code.
  Type: required
  An integer value; 0 means no error has been detected.

Notes

If this function is called on a vector `v` on a distributed communicator only the local part is written in output. To get a single MatrixMarket file with the whole vector when appropriate, e.g. for debugging purposes, one could gather the whole vector on a single rank and then write it. Consider the following example for a double precision vector

    real(psb_dpk_), allocatable :: vglobal(:)

    call psb_gather(vglobal,v,desc,info)
    if (iam == psb_root_) then
    call mm_array_write(vglobal,vtitle,info,filename)
    end if
    call deallocate(vglobal, stat=info)

To simplify this procedure in C, there is a utility function

    psb_i_t psb_c_<s,d,c,z>global_vec_write(vh,cdh);

that produces exactly this result.

[next] [prev] [prev-tail] [front] [up]