Package edu.rit.io

Class DoubleMatrixFile

java.lang.Object
edu.rit.io.DoubleMatrixFile
public class DoubleMatrixFile extends Object
Class DoubleMatrixFile provides an object for reading or writing a double matrix from or to a file. The matrix containing the data to read or write is a separate object, specified as an argument to the constructor or the setMatrix() method.

To write the matrix to a file, call the prepareToWrite() method, specifying the output stream to write. The prepareToWrite() method returns an instance of class DoubleMatrixFile.Writer. Call the methods of the writer object to write the matrix, or sections of the matrix, to the output stream. When finished, close the writer.

To read the matrix from a file, call the prepareToRead() method, specifying the input stream to read. The prepareToRead() method returns an instance of class DoubleMatrixFile.Reader. Call the methods of the reader object to read the matrix, or sections of the matrix, from the input stream. When finished, close the reader.

Class DoubleMatrixFile includes a main program to combine a group of double matrix files into one double matrix file. You might use this main program when the processes of a parallel program have computed slices of a matrix and stored the slices in separate files, and you want to combine the slices together into one file.

Double Matrix File Format

A double matrix file is a binary file containing the following items. Each primitive item is written as though by java.io.DataOutput (int, four bytes; double, eight bytes; most significant byte first).

  • Number of matrix rows, R (int). R >= 0.
  • Number of matrix columns, C (int). C >= 0.
  • Zero or more segments of matrix elements.

Each segment contains the following items.

  • The segment's lower row index, RL (int). RL >= 0.
  • The segment's lower column index, CL (int). CL >= 0.
  • Number of rows in the segment, M (int). M >= 0. RL+M <= R.
  • Number of columns in the segment, N (int). N >= 0. CL+N <= C.
  • The matrix elements in rows RL..RL+M-1 and columns CL..CL+N-1 (double). Stored in row major order.
Version:
06-Jan-2008
Author:
Alan Kaminsky

  • Constructor Details

    • DoubleMatrixFile

      public DoubleMatrixFile()
      Construct a new double matrix file object. The matrix's number of rows and number of columns are uninitialized. Before using the matrix file, specify the number of rows and the number of columns by calling the setMatrix() method or by reading the matrix file from an input stream.

    • DoubleMatrixFile

      public DoubleMatrixFile(int R, int C, double[][] theMatrix)
      Construct a new double matrix file object with the given number of rows, number of columns, and underlying matrix.
      Parameters:
      R - Number of rows.
      C - Number of columns.
      theMatrix - Underlying matrix.
      Throws:
      NullPointerException - (unchecked exception) Thrown if theMatrix is null.
      IllegalArgumentException - (unchecked exception) Thrown if R < 0. Thrown if C < 0. Thrown if theMatrix.length does not equal R.

  • Method Details

    • getRowCount

      public int getRowCount()
      Returns the number of rows in this matrix file.
      Returns:
      Number of rows R, or -1 if not initialized.

    • getColCount

      public int getColCount()
      Returns the number of columns in this matrix file.
      Returns:
      Number of columns, C, or -1 if not initialized.

    • getMatrix

      public double[][] getMatrix()
      Obtain this matrix file's underlying matrix.
      Returns:
      Underlying matrix, or null if not initialized.

    • setMatrix

      public void setMatrix(int R, int C, double[][] theMatrix)
      Set this matrix file's number of rows, number of columns, and underlying matrix.
      Parameters:
      R - Number of rows.
      C - Number of columns.
      theMatrix - Underlying matrix.
      Throws:
      NullPointerException - (unchecked exception) Thrown if theMatrix is null.
      IllegalArgumentException - (unchecked exception) Thrown if R < 0. Thrown if C < 0. Thrown if theMatrix.length does not equal R.

    • prepareToWrite

      public DoubleMatrixFile.Writer prepareToWrite(OutputStream theStream) throws IOException
      Prepare to write this matrix file to the given output stream. The number of rows and the number of columns in this matrix file are written to the output stream at this time. To write this matrix file's elements, call methods on the returned writer, then close the writer.

      For improved performance, specify an output stream with buffering, such as an instance of class java.io.BufferedOutputStream.

      Parameters:
      theStream - Output stream.
      Returns:
      Writer object with which to write this matrix file.
      Throws:
      IllegalStateException - (unchecked exception) Thrown if this matrix file object is uninitialized.
      NullPointerException - (unchecked exception) Thrown if theStream is null.
      IOException - Thrown if an I/O error occurred.
      IOException - if any.

    • prepareToRead

      public DoubleMatrixFile.Reader prepareToRead(InputStream theStream) throws IOException
      Prepare to read this matrix file from the given input stream. The number of rows and the number of columns are read from the input stream at this time. If this matrix file object is uninitialized, it becomes initialized with the given number of rows and columns, and storage is allocated for the underlying matrix's row references; call the getMatrix() method to obtain the underlying matrix. If this matrix file object is already initialized, the number of rows and columns read from the input stream must match those of this matrix file object, otherwise an exception is thrown. To read this matrix file's elements, call methods on the returned reader, then close the reader.

      For improved performance, specify an input stream with buffering, such as an instance of class java.io.BufferedInputStream.

      Parameters:
      theStream - Input stream.
      Returns:
      Reader object with which to read this matrix file.
      Throws:
      NullPointerException - (unchecked exception) Thrown if theStream is null.
      IOException - Thrown if an I/O error occurred.
      InvalidMatrixFileException - (subclass of IOException) Thrown if the input stream's contents were invalid.
      IOException - if any.

    • main

      public static void main(String[] args) throws Exception
      Main program to combine a group of double matrix files into one double matrix file. The program reads all the given input files into a matrix, then writes the entire matrix to the given output file as a single segment. Each input file must be for a matrix with the same number of rows and columns. There must be sufficient main memory to hold the entire matrix.

      You might use this main program when the processes of a parallel program have computed slices of a matrix and stored the slices in separate files, and you want to combine the slices together into one file.

      Usage: java edu.rit.io.DoubleMatrixFile outfile infile1 [ infile2 . . . ]

      Parameters:
      args - an array of String objects.
      Throws:
      Exception - if any.