matrix_tools.h

// ---------------------------------------------------------------------
//
// Copyright (C) 1998 - 2019 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.md at
// the top level directory of deal.II.
//
// ---------------------------------------------------------------------

#ifndef dealii_matrix_tools_h
#define dealii_matrix_tools_h


#include <deal.II/base/config.h>

#include <deal.II/base/exceptions.h>
#include <deal.II/base/function.h>
#include <deal.II/base/thread_management.h>

#include <deal.II/dofs/deprecated_function_map.h>

#include <deal.II/lac/affine_constraints.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;
} // namespace hp


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

#ifdef DEAL_II_WITH_TRILINOS
namespace TrilinosWrappers
{
  class SparseMatrix;
  class BlockSparseMatrix;
  namespace MPI
  {
    class Vector;
    class BlockVector;
  } // namespace MPI
} // namespace TrilinosWrappers
#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 AffineConstraints<number> &constraints = AffineConstraints<number>());

  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 AffineConstraints<number> &constraints = AffineConstraints<number>());

  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> &      rhs,
    Vector<number> &                        rhs_vector,
    const Function<spacedim, number> *const a    = nullptr,
    const AffineConstraints<number> &constraints = AffineConstraints<number>());

  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> &      rhs,
    Vector<number> &                        rhs_vector,
    const Function<spacedim, number> *const a    = nullptr,
    const AffineConstraints<number> &constraints = AffineConstraints<number>());

  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 AffineConstraints<number> &constraints = AffineConstraints<number>());

  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 AffineConstraints<number> &constraints = AffineConstraints<number>());

  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> &          rhs,
    Vector<number> &                            rhs_vector,
    const Function<spacedim, number> *const     a = nullptr,
    const AffineConstraints<number> &constraints = AffineConstraints<number>());

  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> &      rhs,
    Vector<number> &                        rhs_vector,
    const Function<spacedim, number> *const a    = nullptr,
    const AffineConstraints<number> &constraints = AffineConstraints<number>());


  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<number> &           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, number> *const weight            = 0,
    std::vector<unsigned int>               component_mapping = {});


  template <int dim, int spacedim, typename number>
  void
  create_boundary_mass_matrix(
    const DoFHandler<dim, spacedim> &dof,
    const Quadrature<dim - 1> &      q,
    SparseMatrix<number> &           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, number> *const a                 = nullptr,
    std::vector<unsigned int>               component_mapping = {});

  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<number> &                      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, number> *const a                 = nullptr,
    std::vector<unsigned int>               component_mapping = {});

  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<number> &               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, number> *const a                 = nullptr,
    std::vector<unsigned int>               component_mapping = {});

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 AffineConstraints<double> &constraints = AffineConstraints<double>());

  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 MatrixCreator



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.");
} // namespace MatrixTools



DEAL_II_NAMESPACE_CLOSE

#endif