mesh_refinement.h

Go to the documentation of this file.

// The libMesh Finite Element Library.
// Copyright (C) 2002-2024 Benjamin S. Kirk, John W. Peterson, Roy H. Stogner

// This library is free software; you can 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.

// This library is distributed in the hope that it will be useful,
// but WITHOUT ANY WARRANTY; without even the implied warranty of
// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
// Lesser General Public License for more details.

// You should have received a copy of the GNU Lesser General Public
// License along with this library; if not, write to the Free Software
// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA



#ifndef LIBMESH_MESH_REFINEMENT_H
#define LIBMESH_MESH_REFINEMENT_H



#include "libmesh/libmesh_config.h"

#ifdef LIBMESH_ENABLE_AMR

// Local Includes
#include "libmesh/libmesh_common.h"
#include "libmesh/libmesh.h" // libMesh::invalid_uint
#include "libmesh/topology_map.h"
#include "libmesh/parallel_object.h"

// C++ Includes
#include <vector>

namespace libMesh
{

// Forward Declarations
class MeshBase;
class Point;
class Node;
class ErrorVector;
class PeriodicBoundaries;
class Elem;
class PointLocatorBase;

class MeshRefinement : public ParallelObject
{
public:

  explicit
  MeshRefinement (MeshBase & mesh);

private:
  // Both the copy ctor and the assignment operator are
  // declared private but not implemented.  This is the
  // standard practice to prevent them from being used.
  MeshRefinement (const MeshRefinement &);
  MeshRefinement & operator=(const MeshRefinement &);

public:

  class ElementFlagging
  {
  public:
    virtual ~ElementFlagging () = default;

    virtual void flag_elements () = 0;
  };

  void set_periodic_boundaries_ptr(PeriodicBoundaries * pb_ptr);

  ~MeshRefinement ();

  void clear ();

  void flag_elements_by_error_fraction (const ErrorVector & error_per_cell,
                                        const Real refine_fraction  = 0.3,
                                        const Real coarsen_fraction = 0.0,
                                        const unsigned int max_level = libMesh::invalid_uint);

  void flag_elements_by_error_tolerance (const ErrorVector & error_per_cell);

  bool flag_elements_by_nelem_target (const ErrorVector & error_per_cell);

  void flag_elements_by_elem_fraction (const ErrorVector & error_per_cell,
                                       const Real refine_fraction  = 0.3,
                                       const Real coarsen_fraction = 0.0,
                                       const unsigned int max_level = libMesh::invalid_uint);

  void flag_elements_by_mean_stddev (const ErrorVector & error_per_cell,
                                     const Real refine_fraction  = 1.0,
                                     const Real coarsen_fraction = 0.0,
                                     const unsigned int max_level = libMesh::invalid_uint);

  void flag_elements_by (ElementFlagging & element_flagging);

  void switch_h_to_p_refinement();

  void add_p_to_h_refinement();

  bool refine_and_coarsen_elements ();

  bool coarsen_elements ();

  bool refine_elements ();

  void uniformly_refine (unsigned int n=1);

  void uniformly_coarsen (unsigned int n=1);

  void uniformly_p_refine (unsigned int n=1);

  void uniformly_p_coarsen (unsigned int n=1);

  void clean_refinement_flags ();

  bool test_level_one (bool libmesh_assert_yes = false) const;

  bool test_unflagged (bool libmesh_assert_yes = false) const;

  Node * add_node (Elem & parent,
                   unsigned int child,
                   unsigned int node,
                   processor_id_type proc_id);

  Elem * add_elem (Elem * elem);

  Elem * add_elem (std::unique_ptr<Elem> elem);

  const MeshBase & get_mesh () const { return _mesh; }

  MeshBase & get_mesh () { return _mesh; }

  bool & coarsen_by_parents();

  Real & refine_fraction();

  Real & coarsen_fraction();

  unsigned int & max_h_level();

  Real & coarsen_threshold();

  dof_id_type & nelem_target();

  Real & absolute_global_tolerance();

  unsigned char & face_level_mismatch_limit();

  unsigned char & edge_level_mismatch_limit();

  unsigned char & node_level_mismatch_limit();

  signed char & overrefined_boundary_limit();

  signed char & underrefined_boundary_limit();

  bool & allow_unrefined_patches();

  bool make_flags_parallel_consistent ();

#ifdef LIBMESH_ENABLE_DEPRECATED
  bool get_enforce_mismatch_limit_prior_to_refinement();
#endif

#ifdef LIBMESH_ENABLE_DEPRECATED
  void set_enforce_mismatch_limit_prior_to_refinement(bool enforce);
#endif

  bool & enforce_mismatch_limit_prior_to_refinement();

private:

  bool _coarsen_elements ();

  bool _refine_elements ();

  void _smooth_flags (bool refining, bool coarsening);

  //------------------------------------------------------
  // "Smoothing" algorithms for refined meshes

  bool limit_level_mismatch_at_node (const unsigned int max_mismatch);

  /*
   * This algorithm restricts the maximum level mismatch
   * at any edge in the mesh.  See the ASCII art in the comment of
   * limit_level_mismatch_at_node, and pretend they're hexes.
   */
  bool limit_level_mismatch_at_edge (const unsigned int max_mismatch);

  /*
   * This algorithm flags interior elements for refinement as needed
   * to prevent corresponding boundary element refinement mismatch
   * from exceeding the given limit.
   */
  bool limit_overrefined_boundary (const signed char max_mismatch);

  /*
   * This algorithm flags boundary elements for refinement as needed
   * to prevent corresponding interior element refinement mismatch
   * from exceeding the given limit.
   */
  bool limit_underrefined_boundary (const signed char max_mismatch);

  bool eliminate_unrefined_patches ();


  //---------------------------------------------
  // Utility algorithms

  void create_parent_error_vector (const ErrorVector & error_per_cell,
                                   ErrorVector & error_per_parent,
                                   Real & parent_error_min,
                                   Real & parent_error_max);

  void update_nodes_map ();

  bool make_coarsening_compatible ();

  bool make_refinement_compatible ();

  Elem * topological_neighbor (Elem * elem,
                               const PointLocatorBase * point_locator,
                               const unsigned int side) const;

  bool has_topological_neighbor (const Elem * elem,
                                 const PointLocatorBase * point_locator,
                                 const Elem * neighbor) const;

  TopologyMap _new_nodes_map;

  MeshBase & _mesh;

  bool _use_member_parameters;

  bool _coarsen_by_parents;

  Real _refine_fraction;

  Real _coarsen_fraction;

  unsigned int _max_h_level;

  Real _coarsen_threshold;

  dof_id_type _nelem_target;

  Real _absolute_global_tolerance;

  unsigned char _face_level_mismatch_limit;
  unsigned char _edge_level_mismatch_limit;
  unsigned char _node_level_mismatch_limit;

  signed char _overrefined_boundary_limit;
  signed char _underrefined_boundary_limit;

  bool _allow_unrefined_patches;

  bool _enforce_mismatch_limit_prior_to_refinement;

  enum NeighborType {POINT, EDGE};
  bool enforce_mismatch_limit_prior_to_refinement(Elem * elem,
                                                  NeighborType nt,
                                                  unsigned max_mismatch);

#ifdef LIBMESH_ENABLE_PERIODIC
  PeriodicBoundaries * _periodic_boundaries;
#endif
};



// ------------------------------------------------------------
// MeshRefinement class inline members

inline bool & MeshRefinement::coarsen_by_parents()
{
  _use_member_parameters = true;
  return _coarsen_by_parents;
}

inline Real & MeshRefinement::refine_fraction()
{
  _use_member_parameters = true;
  return _refine_fraction;
}

inline Real & MeshRefinement::coarsen_fraction()
{
  _use_member_parameters = true;
  return _coarsen_fraction;
}

inline unsigned int & MeshRefinement::max_h_level()
{
  _use_member_parameters = true;
  return _max_h_level;
}

inline Real & MeshRefinement::coarsen_threshold()
{
  _use_member_parameters = true;
  return _coarsen_threshold;
}

inline dof_id_type & MeshRefinement::nelem_target()
{
  _use_member_parameters = true;
  return _nelem_target;
}

inline Real & MeshRefinement::absolute_global_tolerance()
{
  _use_member_parameters = true;
  return _absolute_global_tolerance;
}

inline unsigned char & MeshRefinement::face_level_mismatch_limit()
{
  return _face_level_mismatch_limit;
}

inline unsigned char & MeshRefinement::edge_level_mismatch_limit()
{
  return _edge_level_mismatch_limit;
}

inline unsigned char & MeshRefinement::node_level_mismatch_limit()
{
  return _node_level_mismatch_limit;
}

inline signed char & MeshRefinement::overrefined_boundary_limit()
{
  return _overrefined_boundary_limit;
}

inline signed char & MeshRefinement::underrefined_boundary_limit()
{
  return _underrefined_boundary_limit;
}

inline bool & MeshRefinement::allow_unrefined_patches()
{
  return _allow_unrefined_patches;
}

#ifdef LIBMESH_ENABLE_DEPRECATED
inline bool MeshRefinement::get_enforce_mismatch_limit_prior_to_refinement()
{
  libmesh_deprecated();
  return enforce_mismatch_limit_prior_to_refinement();
}

inline void MeshRefinement::set_enforce_mismatch_limit_prior_to_refinement(bool enforce)
{
  libmesh_deprecated();
  enforce_mismatch_limit_prior_to_refinement() = enforce;
}
#endif

inline bool & MeshRefinement::enforce_mismatch_limit_prior_to_refinement()
{
  return _enforce_mismatch_limit_prior_to_refinement;
}



} // namespace libMesh

#endif // end #ifdef LIBMESH_ENABLE_AMR
#endif // LIBMESH_MESH_REFINEMENT_H