libMesh::CouplingMatrix Class Reference

This class defines a coupling matrix. More...

#include <coupling_matrix.h>

Public Member Functions
	CouplingMatrix (const std::size_t n=0)
	Constructor.
bool	operator() (const std::size_t i, const std::size_t j) const
CouplingAccessor	operator() (const std::size_t i, const std::size_t j)
std::size_t	size () const
void	resize (const std::size_t n)
	Resizes the matrix and initializes all entries to be 0.
void	clear ()
	Clears the matrix.
bool	empty () const
CouplingMatrix &	operator&= (const CouplingMatrix &other)

Private Types
typedef std::pair< std::size_t, std::size_t >	range_type
	Coupling matrices are typically either full or very sparse, and all values are only zero or one.
typedef std::vector< range_type >	rc_type

Private Attributes
rc_type	_ranges
std::size_t	_size
	The size of the matrix.

Friends
class	ConstCouplingAccessor
class	CouplingAccessor
class	ConstCouplingRow
class	ConstCouplingRowConstIterator

Detailed Description

This class defines a coupling matrix.

A coupling matrix is simply a matrix of ones and zeros describing how different components in a system couple with each other. A coupling matrix is necessarily square but not necessarily symmetric.

Author

Benjamin S. Kirk

Date

2002

Defines the coupling between variables of a System.

Definition at line 54 of file coupling_matrix.h.

Member Typedef Documentation

range_type

typedef std::pair<std::size_t, std::size_t> libMesh::CouplingMatrix::range_type

private

Coupling matrices are typically either full or very sparse, and all values are only zero or one.

We store non-zeros as ranges: the first entry of each range pair is the location of the first non-zero, and the second is the location of the last subsequent non-zero (not the next subsequent zero; we drop empty ranges).

We store locations (i,j) as long integers i*_size+j

Definition at line 119 of file coupling_matrix.h.

rc_type

typedef std::vector<range_type> libMesh::CouplingMatrix::rc_type

private

Definition at line 120 of file coupling_matrix.h.

Constructor & Destructor Documentation

CouplingMatrix()

libMesh::CouplingMatrix::CouplingMatrix ( const std::size_t  n = 0 )

inlineexplicit

Constructor.

Definition at line 571 of file coupling_matrix.h.

                                                 :
  _ranges(), _size(n)
{
  this->resize(n);
}

References resize().

Member Function Documentation

clear()

void libMesh::CouplingMatrix::clear ( )

inline

Clears the matrix.

Definition at line 624 of file coupling_matrix.h.

{
  this->resize(0);
}

References resize().

empty()

bool libMesh::CouplingMatrix::empty ( ) const

inline

Returns

true if the matrix is empty.

Definition at line 632 of file coupling_matrix.h.

{
  return (_size == 0);
}

References _size.

Referenced by libMesh::DofMap::reinit(), and libMesh::DefaultCoupling::set_dof_coupling().

operator&=()

CouplingMatrix & libMesh::CouplingMatrix::operator&=

(

const CouplingMatrix &

other

)

Definition at line 24 of file coupling_matrix.C.

{
  const std::size_t max_size = std::numeric_limits<std::size_t>::max();
 
  rc_type::iterator start_range = this->_ranges.begin();
 
  rc_type::const_iterator     other_range = other._ranges.begin();
  const rc_type::const_iterator other_end = other._ranges.end();
 
  for (; other_range != other_end; ++other_range)
    {
      std::size_t other_range_start = other_range->first;
      std::size_t other_range_end = other_range->second;
 
      // Find our range that might contain the start of the other
      // range.
      // lower_bound isn't *quite* what we want.
      // Because the other._ranges is sorted, we can contract this
      // search as we proceed, beginning with lb rather than at
      // begin() every time.
      rc_type::iterator lb =
        std::upper_bound (start_range, this->_ranges.end(),
                          std::make_pair(other_range_start, max_size));
      if (lb!=start_range)
        --lb;
      else
        lb=this->_ranges.end();
 
      start_range = lb;
 
      // If no range might contain the start of the new range then
      // we can just break out of here and start appending any
      // remaining ranges.
      if (lb == this->_ranges.end())
        break;
 
      // We did find a range which might contain the start of the new
      // range.
      const std::size_t lastloc  = lb->second;
      libmesh_assert_less_equal(lb->first, lastloc);
      libmesh_assert_less_equal(lb->first, other_range_start);
 
#ifdef DEBUG
      {
        CouplingMatrix::rc_type::const_iterator next = lb;
        next++;
        if (next != this->_ranges.end())
          {
            // Ranges should be sorted and should not touch
            libmesh_assert_greater(next->first, lastloc+1);
          }
      }
#endif
 
      CouplingMatrix::rc_type::iterator next = lb;
      next++;
 
      // We might need to extend this range or add a new range.
      // Merge contiguous ranges
      if (other_range_start <= lastloc)
        lb->second = other_range_end;
      // Or insert a new range.  This invalidates existing iterators,
      // but that's okay; the only iterator we need is for the newly
      // inserted range.
      else
        start_range = lb = this->_ranges.emplace
          (next, other_range_start, other_range_end);
 
      // At this point we have a range lb that may potentially overlap
      // subsequent existing ranges, in which case we need to merge
      // some.
 
      // First expand our range as necessary while finding ranges
      // which will be redundant later
      for (const std::size_t nextloc =
             (next == this->_ranges.end()) ?
             std::numeric_limits<std::size_t>::max() : next->first;
           nextloc <= lb->second; ++next)
        {
          // Ranges should be sorted and should not have been touching
          // initially
          libmesh_assert_greater(nextloc, lastloc+1);
 
          lb->second = std::max(lb->second, next->second);
        }
 
      CouplingMatrix::rc_type::iterator oldnext = lb;
      oldnext++;
 
      // Finally remove the redundant ranges
      this->_ranges.erase(oldnext, next);
    }
 
  // If we broke out early but we still have more other_ranges then
  // we can safely just append them to our ranges.
  for (; other_range != other_end; ++other_range)
    this->_ranges.push_back(*other_range);
 
  // Behave like a standard modification operator
  return *this;
}

References _ranges.

operator()() [1/2]

CouplingAccessor libMesh::CouplingMatrix::operator() ( const std::size_t  i, const std::size_t  j  )

inline

Returns

The (i,j) entry of the matrix as a smart-reference.

Definition at line 595 of file coupling_matrix.h.

{
  const std::size_t location = std::size_t(i)*_size + j;
 
  return CouplingAccessor(location, *this);
}

References _size, and CouplingAccessor.

operator()() [2/2]

bool libMesh::CouplingMatrix::operator() ( const std::size_t  i, const std::size_t  j  ) const

inline

Returns

The (i,j) entry of the matrix.

Definition at line 580 of file coupling_matrix.h.

{
  libmesh_assert_less (i, _size);
  libmesh_assert_less (j, _size);
 
  const std::size_t location = std::size_t(i)*_size + j;
 
  return bool(ConstCouplingAccessor(location, *this));
}

References _size, and ConstCouplingAccessor.

resize()

void libMesh::CouplingMatrix::resize ( const std::size_t  n )

inline

Resizes the matrix and initializes all entries to be 0.

Definition at line 614 of file coupling_matrix.h.

{
  _size = n;
 
  _ranges.clear();
}

References _ranges, and _size.

Referenced by clear(), CouplingMatrix(), main(), and CouplingMatrixTest::testSimpleAPI().

size()

std::size_t libMesh::CouplingMatrix::size ( ) const

inline

Returns

The size of the matrix, i.e. N for an NxN matrix.

Definition at line 606 of file coupling_matrix.h.

{
  return _size;
}

References _size.

Referenced by libMesh::ConstCouplingAccessor::ConstCouplingAccessor(), libMesh::ConstCouplingRow::ConstCouplingRow(), and libMesh::ConstCouplingRowConstIterator::operator*().

Friends And Related Symbol Documentation

ConstCouplingAccessor

friend class ConstCouplingAccessor

friend

Definition at line 103 of file coupling_matrix.h.

Referenced by operator()().

ConstCouplingRow

friend class ConstCouplingRow

friend

Definition at line 105 of file coupling_matrix.h.

ConstCouplingRowConstIterator

friend class ConstCouplingRowConstIterator

friend

Definition at line 106 of file coupling_matrix.h.

CouplingAccessor

friend class CouplingAccessor

friend

Definition at line 104 of file coupling_matrix.h.

Referenced by operator()().

Member Data Documentation

_ranges

rc_type libMesh::CouplingMatrix::_ranges

private

Definition at line 121 of file coupling_matrix.h.

Referenced by libMesh::ConstCouplingRow::ConstCouplingRow(), libMesh::ConstCouplingRowConstIterator::ConstCouplingRowConstIterator(), libMesh::ConstCouplingRow::end(), libMesh::ConstCouplingAccessor::operator bool(), operator&=(), libMesh::ConstCouplingRowConstIterator::operator++(), libMesh::CouplingAccessor::operator=(), and resize().

_size

std::size_t libMesh::CouplingMatrix::_size

private

The size of the matrix.

Definition at line 126 of file coupling_matrix.h.

Referenced by empty(), operator()(), operator()(), resize(), and size().

---

The documentation for this class was generated from the following files:

• include/numerics/coupling_matrix.h
• src/numerics/coupling_matrix.C