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// Copyright (C) 2006-2025 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
#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:
    /// Default constructor - constructs an empty matrix.
    VectorMatrix()
    {
      Vector_matrix.resize(0);
    }
 
    /// 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);
    }
 
    /// 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);
    }
 
    /// Default virtual destructor
    virtual ~VectorMatrix()
    {
      this->clear();
    }
 
    /// 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();
    }
 
    /// 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();
      }
    }
 
    /// [] access function to the i-th inner vector.
    Vector<VALUE_TYPE>& operator[](const size_t i)
    {
      return Vector_matrix[i];
    }
 
    /// [] access function to the i-th inner vector const version
    const Vector<VALUE_TYPE>& operator[](const size_t i) const
    {
      return Vector_matrix[i];
    }
 
 
    /// Clears the outer vector. Calling Vector::clear() will invoke the
    /// destructor of all the inner Vectors.
    void clear()
    {
      Vector_matrix.clear();
    }
 
    /// 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);
      }
    }
 
    /// 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:
    /// 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));
    }
 
    /// 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;
  };
 
} // namespace oomph
 
#endif