vector_matrix.h

Go to the documentation of this file.

//LIC// ====================================================================
//LIC// This file forms part of oomph-lib, the object-oriented, 
//LIC// multi-physics finite-element library, available 
//LIC// at http://www.oomph-lib.org.
//LIC// 
//LIC//    Version 1.0; svn revision $LastChangedRevision$
//LIC//
//LIC// $LastChangedDate$
//LIC// 
//LIC// Copyright (C) 2006-2016 Matthias Heil and Andrew Hazel
//LIC// 
//LIC// This library is free software; you can redistribute it and/or
//LIC// modify it under the terms of the GNU Lesser General Public
//LIC// License as published by the Free Software Foundation; either
//LIC// version 2.1 of the License, or (at your option) any later version.
//LIC// 
//LIC// This library is distributed in the hope that it will be useful,
//LIC// but WITHOUT ANY WARRANTY; without even the implied warranty of
//LIC// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
//LIC// Lesser General Public License for more details.
//LIC// 
//LIC// You should have received a copy of the GNU Lesser General Public
//LIC// License along with this library; if not, write to the Free Software
//LIC// Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
//LIC// 02110-1301  USA.
//LIC// 
//LIC// The authors may be contacted at oomph-lib@maths.man.ac.uk.
//LIC// 
//LIC//====================================================================
#ifndef OOMPH_VECTOR_MATRIX_HEADER
#define OOMPH_VECTOR_MATRIX_HEADER


// Config header generated by autoconfig
#ifdef HAVE_CONFIG_H
  #include <oomph-lib-config.h>
#endif


#ifdef OOMPH_HAS_MPI
#include "mpi.h"
#endif

//oomph-lib headers
#include "Vector.h"
#include "oomph_utilities.h"

namespace oomph
{
//================================================================
/// VectorMatrix is a generalised, STL-map-based, matrix based on a Vector
/// of Vectors.
///
/// Example of usage:
/// \code
///
///  // Assume we have a Vector of pointers to objects:
///  VectorMatrix<int> vector_matrix(4,5,-1);
/// 
///  // This is a 4 by 5 matrix with all entries set to -1.
///
///  std::cout << vector_matrix[3][3] << " "
//             << vector_matrix.nrow() << " "
//             << vector_matrix.col() << std::endl;
///  
///  // Output:
///  // -1 4 5
///  
///  vector_matrix[3][3] = 42;
///  
///  std::cout << vector_matrix[3][3] << " "
///            << vector_matrix.nrow() << " "
///            << vector_matrix.col() << std::endl;
///
///  // Output:
///  // 42 4 5
///
/// \endcode
///
//================================================================
template<class VALUE_TYPE>
class VectorMatrix
{

public:

 /// \short Default constructor - constructs an empty matrix.
 VectorMatrix()
 {
   Vector_matrix.resize(0);
 }

 /// \short Constructor - constructs an n by m matrix with value val.
 VectorMatrix(const unsigned& n, const unsigned& m, const VALUE_TYPE& val)
 {
   this->build_vectors_and_value(n,m,val);
 }

 /// \short Constructor - constructs an n by m matrix, the value is defined by
 /// the default initialisation of VALUE_TYPE.
 VectorMatrix(const unsigned& n, const unsigned& m)
 {
   this->build_vectors(n,m);
 }

 /// \short Default virtual destructor
 virtual ~VectorMatrix()
 {
   this->clear();
 }

 /// \short returns the number of rows. This is the outer Vector size.
 const unsigned nrow() const
 {
#ifdef PARANOID
   // Inner vector size consistency check: All inner vectors must be the same
   // size. Although the size of the inner vectors are not directly used to 
   // calculate the nrow(), we perform this check here in case the user has 
   // done something dodgy.

   const unsigned para_nrow = Vector_matrix.size();

   if(para_nrow > 0)
   {
     // There is at least one inner vector
     unsigned inner_vector0_size = Vector_matrix[0].size();

     for (unsigned row_i = 0; row_i < para_nrow; row_i++)
     {
       unsigned current_inner_vector_size = Vector_matrix[row_i].size();
       if(current_inner_vector_size != inner_vector0_size)
       {
         std::ostringstream err_msg;
         err_msg << "The size of the inner vectors are not consistent.\n"
           << "Vector_matrix[0].size() is " << inner_vector0_size <<"\n"
           << "Vector_matrix[" <<row_i <<"] is " 
           << current_inner_vector_size << "\n";
         throw OomphLibError(
             err_msg.str(),
             OOMPH_CURRENT_FUNCTION,
             OOMPH_EXCEPTION_LOCATION);
       }
     }
   }
#endif

   return Vector_matrix.size();
 }

 /// \short return the number of columns. This is the size of the first inner
 /// vectors, or returns 0 if the outer vector is of size 0 
 /// (this->nrow() is 0).
 const unsigned ncol() const
 {
#ifdef PARANOID
   // Inner vector size consistency check: All inner vectors must be the same
   // size.

   const unsigned para_nrow = this->nrow();
   if(para_nrow > 0)
   {
     // There is at least one inner vector
     unsigned inner_vector0_size = Vector_matrix[0].size();

     for (unsigned row_i = 0; row_i < para_nrow; row_i++)
     {
       unsigned current_inner_vector_size = Vector_matrix[row_i].size();
       if(current_inner_vector_size != inner_vector0_size)
       {
         std::ostringstream err_msg;
         err_msg << "The size of the inner vectors are not consistent.\n"
           << "Vector_matrix[0].size() is " << inner_vector0_size <<"\n"
           << "Vector_matrix[" <<row_i <<"] is " 
           << current_inner_vector_size << "\n";
         throw OomphLibError(
             err_msg.str(),
             OOMPH_CURRENT_FUNCTION,
             OOMPH_EXCEPTION_LOCATION);
       }
     }
   }
#endif

   if(this->nrow() == 0)
   {
     return 0;
   }
   else
   {
     return Vector_matrix[0].size();
   }
 }

 /// \short [] access function to the i-th inner vector.
 Vector<VALUE_TYPE>& operator[] (const size_t i)
 {
   return Vector_matrix[i];
 }
 
 /// \short [] access function to the i-th inner vector const version
 const Vector<VALUE_TYPE>& operator[] (const size_t i) const
 {
   return Vector_matrix[i];
 }


 /// \short Clears the outer vector. Calling Vector::clear() will invoke the 
 /// destructor of all the inner Vectors.
 void clear()
 {
   Vector_matrix.clear();
 }

 /// \short Resize the existing VectorMatrix.
 /// WARNING: This invokes the resize function in std::vector, as such, only
 /// new values are assigned, old values as kept.
 /// e.g. if vec = [2,2,2], then vec.resize(5,3) gives
 /// vec = [2, 2, 2, 3, 3].
 void resize(const size_t& n, const size_t& m, 
             VALUE_TYPE val = VALUE_TYPE())
 {
   Vector_matrix.resize(n);
   for (unsigned i = 0; i < n ; i++)
   {
     Vector_matrix[i].resize(m,val);
   }
 }

 /// \short Any elements held in the container before the call are destroyed 
 /// and replaced by newly constructed elements (no assignments of elements 
 /// take place).
 /// This causes an automatic reallocation of the allocated storage space if 
 /// -and only if- the new vector size surpasses the current vector capacity.
 /// This invokes std::assign on both the outer vector and the inner vectors.
 void assign(const size_t & n, const size_t& m,
             const VALUE_TYPE& val)
 {
   Vector_matrix.assign(n,Vector<VALUE_TYPE>(m,val));
 }


protected:

 /// \short Builds an n by m VectorMatrix with default VALUE_TYPE.
 void build_vectors(const unsigned& n, const unsigned& m)
 {
   Vector_matrix.resize(n,Vector<VALUE_TYPE>(m));
 }

 /// \short Build an m by n VectorMatrix with VALUE_TYPE val.
 void build_vectors_and_value(const unsigned& n, 
                              const unsigned& m, 
                              const VALUE_TYPE& val)
 {
   Vector_matrix.resize(n, Vector<VALUE_TYPE>(m,val));
 }

 /// Here's the generalised matrix structure: A Vector of Vector to
 /// templated by VALUE_TYPE.
 Vector<Vector<VALUE_TYPE> > Vector_matrix;

};

} // End of oomph namespace

#endif