matrix_tools.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2018 by the deal.II authors
//
// This file is part of the deal.II library.
//
// The deal.II library is free software; you can use it, redistribute
// it, and/or modify it under the terms of the GNU Lesser General
// Public License as published by the Free Software Foundation; either
// version 2.1 of the License, or (at your option) any later version.
// The full text of the license can be found in the file LICENSE at
// the top level of the deal.II distribution.
//
// ---------------------------------------------------------------------

#ifndef dealii_matrix_tools_h
#define dealii_matrix_tools_h


#include <deal.II/base/config.h>
#include <deal.II/base/function.h>
#include <deal.II/base/exceptions.h>
#include <deal.II/base/thread_management.h>
#include <deal.II/lac/constraint_matrix.h>
#include <deal.II/dofs/function_map.h>

#include <map>

#ifdef DEAL_II_WITH_PETSC
#  include <petscsys.h>
#endif

DEAL_II_NAMESPACE_OPEN


// forward declarations
template <int dim> class Quadrature;


template <typename number> class Vector;
template <typename number> class FullMatrix;
template <typename number> class SparseMatrix;

template <typename number> class BlockSparseMatrix;
template <typename Number> class BlockVector;

template <int dim, int spacedim> class Mapping;
template <int dim, int spacedim> class DoFHandler;

namespace hp
{
  template <int> class QCollection;
  template <int, int> class MappingCollection;
  template <int, int> class DoFHandler;
}


#ifdef DEAL_II_WITH_PETSC
namespace PETScWrappers
{
  class MatrixBase;
  class VectorBase;
  namespace MPI
  {
    class BlockSparseMatrix;
    class BlockVector;
  }
}
#endif

#ifdef DEAL_II_WITH_TRILINOS
namespace TrilinosWrappers
{
  class SparseMatrix;
  class BlockSparseMatrix;
  namespace MPI
  {
    class Vector;
    class BlockVector;
  }
}
#endif


namespace MatrixCreator
{
  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const Mapping<dim, spacedim>       &mapping,
                           const DoFHandler<dim,spacedim>    &dof,
                           const Quadrature<dim>    &q,
                           SparseMatrix<number>     &matrix,
                           const Function<spacedim,number> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const DoFHandler<dim,spacedim>    &dof,
                           const Quadrature<dim>    &q,
                           SparseMatrix<number>     &matrix,
                           const Function<spacedim,number> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const Mapping<dim, spacedim>   &mapping,
                           const DoFHandler<dim,spacedim> &dof,
                           const Quadrature<dim>    &q,
                           SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                           const Function<spacedim,number> &rhs,
                           Vector<number>           &rhs_vector,
                           const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const DoFHandler<dim,spacedim> &dof,
                           const Quadrature<dim>    &q,
                           SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                           const Function<spacedim,number> &rhs,
                           Vector<number>           &rhs_vector,
                           const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const hp::MappingCollection<dim,spacedim>       &mapping,
                           const hp::DoFHandler<dim,spacedim>    &dof,
                           const hp::QCollection<dim>    &q,
                           SparseMatrix<number>     &matrix,
                           const Function<spacedim,number> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const hp::DoFHandler<dim,spacedim>    &dof,
                           const hp::QCollection<dim>    &q,
                           SparseMatrix<number>     &matrix,
                           const Function<spacedim,number> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const hp::MappingCollection<dim,spacedim> &mapping,
                           const hp::DoFHandler<dim,spacedim> &dof,
                           const hp::QCollection<dim> &q,
                           SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                           const Function<spacedim,number> &rhs,
                           Vector<number>           &rhs_vector,
                           const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim, typename number>
  void create_mass_matrix (const hp::DoFHandler<dim,spacedim> &dof,
                           const hp::QCollection<dim> &q,
                           SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                           const Function<spacedim,number> &rhs,
                           Vector<number>           &rhs_vector,
                           const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const a = nullptr,
                           const ConstraintMatrix   &constraints = ConstraintMatrix());


  template <int dim, int spacedim, typename number>
  void create_boundary_mass_matrix (const Mapping<dim, spacedim>       &mapping,
                                    const DoFHandler<dim,spacedim>    &dof,
                                    const Quadrature<dim-1>  &q,
                                    SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                                    const std::map<types::boundary_id, const Function<spacedim,number>*> &boundary_functions,
                                    Vector<number>           &rhs_vector,
                                    std::vector<types::global_dof_index> &dof_to_boundary_mapping,
                                    const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const weight = 0,
                                    std::vector<unsigned int> component_mapping = std::vector<unsigned int>());


  template <int dim, int spacedim, typename number>
  void create_boundary_mass_matrix (const DoFHandler<dim,spacedim>    &dof,
                                    const Quadrature<dim-1>  &q,
                                    SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                                    const std::map<types::boundary_id, const Function<spacedim,number>*> &boundary_functions,
                                    Vector<number>           &rhs_vector,
                                    std::vector<types::global_dof_index> &dof_to_boundary_mapping,
                                    const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const a = nullptr,
                                    std::vector<unsigned int> component_mapping = std::vector<unsigned int>());

  template <int dim, int spacedim, typename number>
  void create_boundary_mass_matrix (const hp::MappingCollection<dim,spacedim>       &mapping,
                                    const hp::DoFHandler<dim,spacedim>    &dof,
                                    const hp::QCollection<dim-1>  &q,
                                    SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                                    const std::map<types::boundary_id, const Function<spacedim,number>*> &boundary_functions,
                                    Vector<number>           &rhs_vector,
                                    std::vector<types::global_dof_index> &dof_to_boundary_mapping,
                                    const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const a = nullptr,
                                    std::vector<unsigned int> component_mapping = std::vector<unsigned int>());

  template <int dim, int spacedim, typename number>
  void create_boundary_mass_matrix (const hp::DoFHandler<dim,spacedim>    &dof,
                                    const hp::QCollection<dim-1>  &q,
                                    SparseMatrix<typename numbers::NumberTraits<number>::real_type>     &matrix,
                                    const std::map<types::boundary_id, const Function<spacedim,number>*> &boundary_functions,
                                    Vector<number>           &rhs_vector,
                                    std::vector<types::global_dof_index> &dof_to_boundary_mapping,
                                    const Function<spacedim,typename numbers::NumberTraits<number>::real_type> *const a = nullptr,
                                    std::vector<unsigned int> component_mapping = std::vector<unsigned int>());

  template <int dim, int spacedim>
  void create_laplace_matrix (const Mapping<dim, spacedim>   &mapping,
                              const DoFHandler<dim,spacedim> &dof,
                              const Quadrature<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim>
  void create_laplace_matrix (const DoFHandler<dim,spacedim> &dof,
                              const Quadrature<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim>
  void create_laplace_matrix (const Mapping<dim, spacedim>   &mapping,
                              const DoFHandler<dim,spacedim> &dof,
                              const Quadrature<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim> &rhs,
                              Vector<double>           &rhs_vector,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim>
  void create_laplace_matrix (const DoFHandler<dim,spacedim> &dof,
                              const Quadrature<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim> &rhs,
                              Vector<double>           &rhs_vector,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim>
  void create_laplace_matrix (const hp::MappingCollection<dim,spacedim> &mapping,
                              const hp::DoFHandler<dim,spacedim> &dof,
                              const hp::QCollection<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim>
  void create_laplace_matrix (const hp::DoFHandler<dim,spacedim> &dof,
                              const hp::QCollection<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim>
  void create_laplace_matrix (const hp::MappingCollection<dim,spacedim> &mapping,
                              const hp::DoFHandler<dim,spacedim> &dof,
                              const hp::QCollection<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim>      &rhs,
                              Vector<double>           &rhs_vector,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  template <int dim, int spacedim>
  void create_laplace_matrix (const hp::DoFHandler<dim,spacedim> &dof,
                              const hp::QCollection<dim>    &q,
                              SparseMatrix<double>     &matrix,
                              const Function<spacedim>      &rhs,
                              Vector<double>           &rhs_vector,
                              const Function<spacedim> *const a = nullptr,
                              const ConstraintMatrix   &constraints = ConstraintMatrix());

  DeclExceptionMsg (ExcComponentMismatch,
                    "You are providing either a right hand side function or a "
                    "coefficient with a number of vector components that is "
                    "inconsistent with the rest of the arguments. If you do "
                    "provide a coefficient or right hand side function, then "
                    "it either needs to have as many components as the finite "
                    "element in use, or only a single vector component. In "
                    "the latter case, the same value will be taken for "
                    "each vector component of the finite element.");
}



namespace MatrixTools
{
  using namespace MatrixCreator;

  template <typename number>
  void
  apply_boundary_values (const std::map<types::global_dof_index,number> &boundary_values,
                         SparseMatrix<number>  &matrix,
                         Vector<number>        &solution,
                         Vector<number>        &right_hand_side,
                         const bool             eliminate_columns = true);

  template <typename number>
  void
  apply_boundary_values (const std::map<types::global_dof_index,number> &boundary_values,
                         BlockSparseMatrix<number>           &matrix,
                         BlockVector<number>                 &solution,
                         BlockVector<number>                 &right_hand_side,
                         const bool           eliminate_columns = true);

#ifdef DEAL_II_WITH_PETSC

  void
  apply_boundary_values
  (const std::map<types::global_dof_index,PetscScalar> &boundary_values,
   PETScWrappers::MatrixBase                           &matrix,
   PETScWrappers::VectorBase                           &solution,
   PETScWrappers::VectorBase                           &right_hand_side,
   const bool                                           eliminate_columns = true);

  void
  apply_boundary_values (const std::map<types::global_dof_index,PetscScalar>  &boundary_values,
                         PETScWrappers::MPI::BlockSparseMatrix &matrix,
                         PETScWrappers::MPI::BlockVector        &solution,
                         PETScWrappers::MPI::BlockVector        &right_hand_side,
                         const bool       eliminate_columns = true);

#endif

#ifdef DEAL_II_WITH_TRILINOS

  void
  apply_boundary_values (const std::map<types::global_dof_index,TrilinosScalar> &boundary_values,
                         TrilinosWrappers::SparseMatrix  &matrix,
                         TrilinosWrappers::MPI::Vector   &solution,
                         TrilinosWrappers::MPI::Vector   &right_hand_side,
                         const bool             eliminate_columns = true);

  void
  apply_boundary_values (const std::map<types::global_dof_index,TrilinosScalar> &boundary_values,
                         TrilinosWrappers::BlockSparseMatrix  &matrix,
                         TrilinosWrappers::MPI::BlockVector   &solution,
                         TrilinosWrappers::MPI::BlockVector   &right_hand_side,
                         const bool                eliminate_columns = true);
#endif

  template <typename number>
  void
  local_apply_boundary_values (const std::map<types::global_dof_index,number> &boundary_values,
                               const std::vector<types::global_dof_index> &local_dof_indices,
                               FullMatrix<number> &local_matrix,
                               Vector<number>     &local_rhs,
                               const bool          eliminate_columns);

  DeclExceptionMsg (ExcBlocksDontMatch,
                    "You are providing a matrix whose subdivision into "
                    "blocks in either row or column direction does not use "
                    "the same blocks sizes as the solution vector or "
                    "right hand side vectors, respectively.");
}



DEAL_II_NAMESPACE_CLOSE

#endif