Teuchos_MatrixMarket_Raw_Reader.hpp

// @HEADER
// ***********************************************************************
//
//          Tpetra: Templated Linear Algebra Services Package
//                 Copyright (2008) Sandia Corporation
//
// Under the terms of Contract DE-AC04-94AL85000 with Sandia Corporation,
// the U.S. Government retains certain rights in this software.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
// 1. Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//
// 2. Redistributions in binary form must reproduce the above copyright
// notice, this list of conditions and the following disclaimer in the
// documentation and/or other materials provided with the distribution.
//
// 3. Neither the name of the Corporation nor the names of the
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY SANDIA CORPORATION "AS IS" AND ANY
// EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
// IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
// PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL SANDIA CORPORATION OR THE
// CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
// EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
// PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
// PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
// LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
// NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
// SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
//
// Questions? Contact Michael A. Heroux (maherou@sandia.gov)
//
// ************************************************************************
// @HEADER
 
#ifndef __Teuchos_MatrixMarket_Raw_Reader_hpp
#define __Teuchos_MatrixMarket_Raw_Reader_hpp
 
#include "Teuchos_MatrixMarket_Raw_Adder.hpp"
#include "Teuchos_MatrixMarket_SymmetrizingAdder.hpp"
#include "Teuchos_MatrixMarket_CoordDataReader.hpp"
 
 
namespace Teuchos {
  namespace MatrixMarket {
    namespace Raw {
      template<class Scalar, class Ordinal>
      class Reader {
      public:
        Reader (const bool tolerant, const bool debug) :
          tolerant_ (tolerant), debug_ (debug)
        {
          init ();
        }
 
        Reader () :
          tolerant_ (false), debug_ (false)
        {
          init ();
        }
 
        Reader (const RCP<ParameterList>& params) :
          tolerant_ (false), debug_ (false)
        {
          setParameters (params);
          init ();
        }
 
        void
        setParameters (const RCP<ParameterList>& params)
        {
          // Default parameter values.
          bool tolerant = false;
          bool debug = false;
 
          // Read parameters.
          tolerant = params->get ("Parse tolerantly", tolerant);
          debug = params->get ("Debug mode", debug);
 
          // No side effects on the class until ParameterList
          // processing is complete.
          tolerant_ = tolerant;
          debug_ = debug;
        }
 
        RCP<const ParameterList>
        getValidParameters () const
        {
          // Default parameter values.
          const bool tolerant = false;
          const bool debug = false;
 
          // Set default parameters with documentation.
          RCP<ParameterList> params = parameterList ("Matrix Market Reader");
          params->set ("Parse tolerantly", tolerant, "Whether to tolerate "
                       "syntax errors when parsing the Matrix Market file");
          params->set ("Debug mode", debug, "Whether to print debugging output "
                       "to stderr, on all participating MPI processes");
 
          return rcp_const_cast<const ParameterList> (params);
        }
 
        bool
        readFile (ArrayRCP<Ordinal>& rowptr,
                  ArrayRCP<Ordinal>& colind,
                  ArrayRCP<Scalar>& values,
                  Ordinal& numRows,
                  Ordinal& numCols,
                  const std::string& filename)
        {
          std::ifstream in (filename.c_str ());
          TEUCHOS_TEST_FOR_EXCEPTION(! in, std::runtime_error,
            "Failed to open file \"" << filename << "\" for reading.");
          return read (rowptr, colind, values, numRows, numCols, in);
        }
 
        bool
        read (ArrayRCP<Ordinal>& rowptr,
              ArrayRCP<Ordinal>& colind,
              ArrayRCP<Scalar>& values,
              Ordinal& numRows,
              Ordinal& numCols,
              std::istream& in)
        {
          using std::cerr;
          using std::cout;
          using std::endl;
          typedef ScalarTraits<Scalar> STS;
 
          // This "Adder" knows how to add sparse matrix entries,
          // given a line of data from the file.  It also stores the
          // entries and can sort them.
          typedef Adder<Scalar, Ordinal> raw_adder_type;
          // SymmetrizingAdder "advices" (yes, I'm using that as a verb)
          // the original Adder, so that additional entries are filled
          // in symmetrically, if the Matrix Market banner line
          // specified a symmetry type other than "general".
          typedef SymmetrizingAdder<raw_adder_type> adder_type;
 
          // Current line number of the input stream.
          size_t lineNumber = 1;
 
          // Construct the "Banner" (matrix metadata, including type
          // and symmetry information, but not dimensions).
          RCP<const Banner> banner;
          std::ostringstream err;
          try {
            banner = readBanner (in, lineNumber);
          }
          catch (std::exception& e) {
            err << "Failed to read Matrix Market input's Banner: " << e.what();
            if (tolerant_) {
              if (debug_) {
                cerr << err.str() << endl;
              }
              return false;
            }
            else {
              TEUCHOS_TEST_FOR_EXCEPTION(true, std::runtime_error, err.str());
            }
          }
 
          //
          // Validate the metadata in the Banner.
          //
          bool ok = true;
          if (banner->matrixType () != "coordinate") {
            err << "Matrix Market input file must contain a \"coordinate\"-"
              "format sparse matrix in order to create a sparse matrix object "
              "from it.";
            ok = false;
          }
          else if (! STS::isComplex && banner->dataType () == "complex") {
            err << "The Matrix Market sparse matrix file contains complex-"
              "valued data, but you are try to read the data into a sparse "
              "matrix containing real values (your matrix's Scalar type is "
              "real).";
            ok = false;
          }
          else if (banner->dataType () != "real" &&
                   banner->dataType () != "complex") {
            err << "Only real or complex data types (no pattern or integer "
              "matrices) are currently supported.";
            ok = false;
          }
          if (! ok) {
            if (tolerant_) {
              if (debug_) {
                cerr << "Matrix Market banner is invalid: " << err.str () << endl;
                return false;
              }
            }
            else {
              TEUCHOS_TEST_FOR_EXCEPTION(true, std::runtime_error,
                "Matrix Market banner is invalid: " << err.str ());
            }
          }
          if (debug_) {
            cerr << "Matrix Market Banner line:" << endl << *banner << endl;
          }
 
          // The reader will invoke the adder (see below) once for
          // each matrix entry it reads from the input stream.
          typedef CoordDataReader<adder_type, Ordinal, Scalar, STS::isComplex> reader_type;
          // We will set the adder below, after calling readDimensions().
          reader_type reader;
 
          // Read in the dimensions of the sparse matrix: (# rows, #
          // columns, # matrix entries (counting duplicates as
          // separate entries)).  The second element of the pair tells
          // us whether the values were gotten successfully.
          std::pair<Tuple<Ordinal, 3>, bool> dims =
            reader.readDimensions (in, lineNumber, tolerant_);
          if (! dims.second) {
            err << "Error reading Matrix Market sparse matrix file: failed to "
              "read coordinate dimensions.";
            if (tolerant_) {
              if (debug_) {
                cerr << err.str () << endl;
              }
              return false;
            }
            else {
              TEUCHOS_TEST_FOR_EXCEPTION(true, std::runtime_error, err.str ());
            }
          }
 
          // These are "expected" values read from the input stream's
          // metadata.  The actual matrix entries read from the input
          // stream might not conform to their constraints.  We allow
          // such nonconformity only in "tolerant" mode; otherwise, we
          // throw an exception.
          numRows = dims.first[0];
          numCols = dims.first[1];
          const Ordinal numEntries = dims.first[2];
          if (debug_) {
            cerr << "Reported dimensions: " << numRows << " x " << numCols
                 << ", with " << numEntries << " entries (counting possible "
                 << "duplicates)." << endl;
          }
 
          // The "raw" adder knows about the expected matrix
          // dimensions, but doesn't know about symmetry.
          RCP<raw_adder_type> rawAdder =
            rcp (new raw_adder_type (numRows, numCols, numEntries,
                                     tolerant_, debug_));
          // The symmetrizing adder knows about symmetry.  It mediates
          // adding entries to the "raw" adder.  We'll use the raw
          // adder to compute the CSR arrays.
          RCP<adder_type> adder =
            rcp (new adder_type (rawAdder, banner->symmType ()));
 
          // Give the adder to the reader.
          reader.setAdder (adder);
 
          // Read the sparse matrix entries.  "results" just tells us if
          // and where there were any bad lines of input.  The actual
          // sparse matrix entries are stored in the (raw) Adder object.
          std::pair<bool, std::vector<size_t> > results =
            reader.read (in, lineNumber, tolerant_, debug_);
 
          // Report any bad line number(s).
          if (! results.first) {
            err << "The Matrix Market input stream had syntax error(s)."
              "  Here is the error report." << endl;
            reportBadness (err, results);
            if (tolerant_) {
              if (debug_) {
                cerr << err.str() << endl;
              }
              return false;
            }
            else {
              TEUCHOS_TEST_FOR_EXCEPTION(true, std::runtime_error, err.str ());
            }
          }
          // Done reading the sparse matrix; now extract CSR arrays.
          size_t numUnique, numRemoved;
          ArrayRCP<Ordinal> ptr;
          ArrayRCP<Ordinal> ind;
          ArrayRCP<Scalar> val;
          try {
            rawAdder->mergeAndConvertToCSR (numUnique, numRemoved, ptr, ind, val);
          }
          catch (std::exception& e) {
            err << "Failed to convert sparse matrix data to CSR (compressed "
              "sparse row) format.  Reported error: " << e.what ();
            if (tolerant_) {
              if (debug_) {
                cerr << err.str () << endl;
              }
              return false;
            }
            else {
              TEUCHOS_TEST_FOR_EXCEPTION(true, std::runtime_error, err.str ());
            }
          }
          rowptr = ptr;
          colind = ind;
          values = val;
          return true;
        }
 
      private:
        bool tolerant_;
        bool debug_;
 
        void init () {
          using std::cerr;
          using std::endl;
 
          if (debug_) {
            cerr << "MatrixMarket::Raw::Reader:" << endl
                 << "- Tolerant mode: " << tolerant_ << endl
                 << "- Debug mode: " << debug_ << endl;
          }
        }
 
        RCP<const Banner>
        readBanner (std::istream& in, size_t& lineNumber)
        {
          using std::cerr;
          using std::endl;
          std::string line; // The presumed banner line
 
          // The first line of the Matrix Market file should always be
          // the banner line.  In tolerant mode, we allow comment
          // lines before the banner line.  This complicates detection
          // of comment lines a bit.
          if (tolerant_) {
            // Keep reading lines until we get a noncomment line.
            const bool maybeBannerLine = true;
            size_t numLinesRead = 0;
            bool commentLine = false;
            do {
              // Try to read a line from the input stream.
              const bool readFailed = ! getline (in, line);
              TEUCHOS_TEST_FOR_EXCEPTION(readFailed, std::invalid_argument,
                "Failed to get Matrix Market banner line from input, after reading "
                << numLinesRead << "line" << (numLinesRead != 1 ? "s." : "."));
              // We read a line from the input stream.
              ++lineNumber;
              ++numLinesRead;
              size_t start, size; // Output args of checkCommentLine
              commentLine = checkCommentLine (line, start, size, lineNumber,
                                              tolerant_, maybeBannerLine);
            } while (commentLine); // Loop until we find a noncomment line.
          }
          else {
            const bool readFailed = ! getline (in, line);
            TEUCHOS_TEST_FOR_EXCEPTION(readFailed, std::invalid_argument,
              "Failed to get Matrix Market banner line from input.  This "
              "probably means that the file is empty (contains zero lines).");
          }
 
          if (debug_) {
            cerr << "Raw::Reader::readBanner: Here is the presumed banner line:"
                 << endl << line << endl;
          }
 
          // Assume that the noncomment line we found is the banner line.
          RCP<Banner> banner;
          try {
            banner = rcp (new Banner (line, tolerant_));
          } catch (std::exception& e) {
            TEUCHOS_TEST_FOR_EXCEPTION(true, std::invalid_argument,
              "Matrix Market file's banner line contains syntax error(s): "
              << e.what ());
          }
          return rcp_const_cast<const Banner> (banner);
        }
 
        void
        reportBadness (std::ostream& out,
                       const std::pair<bool, std::vector<size_t> >& results)
        {
          using std::endl;
          const size_t numErrors = results.second.size();
          const size_t maxNumErrorsToReport = 20;
          out << numErrors << " errors when reading Matrix Market sparse "
            "matrix file." << endl;
          if (numErrors > maxNumErrorsToReport) {
            out << "-- We do not report individual errors when there "
              "are more than " << maxNumErrorsToReport << ".";
          }
          else if (numErrors == 1) {
            out << "Error on line " << results.second[0] << endl;
          }
          else if (numErrors > 1) {
            out << "Errors on lines {";
            for (size_t k = 0; k < numErrors-1; ++k) {
              out << results.second[k] << ", ";
            }
            out << results.second[numErrors-1] << "}" << endl;
          }
        }
      }; // end of class Reader
    } // namespace Raw
  } // namespace MatrixMarket
} // namespace Teuchos
 
#endif // __Teuchos_MatrixMarket_Raw_Reader_hpp