mesh_refinement.h

一个用来实现偏微分方程中网格的计算库

// $Id: mesh_refinement.h 2822 2008-05-01 20:43:09Z roystgnr $

// The libMesh Finite Element Library.
// Copyright (C) 2002-2007  Benjamin S. Kirk, John W. Peterson
  
// 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 __mesh_refinement_h__
#define __mesh_refinement_h__



#include "libmesh_config.h"

#ifdef ENABLE_AMR

// C++ Includes   -----------------------------------
#include <vector>

// Local Includes -----------------------------------
#include "libmesh_common.h"
#include "libmesh.h" // libMesh::invalid_uint
#include "location_maps.h"

// Forward Declarations -----------------------------
class MeshBase;
class Point;
class Node;
class Elem;
class ErrorVector;



/**
 * This is the \p MeshRefinement class.  This class implements
 * adaptive mesh refinement algorithms for a \p MeshBase.
 *
 * @author Benjamin S. Kirk, 2002-2007.
 */


// ------------------------------------------------------------
// MeshRefinement class definition
class MeshRefinement
{
public:

  /**
   * Constructor.
   */
  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:

  /**
   * Destructor. Deletes all the elements that are currently stored.
   */
  ~MeshRefinement ();

  /**
   * Deletes all the data that are currently stored.
   */
  void clear ();  

  /**
   * Flags elements for coarsening and refinement based on
   * the computed error passed in \p error_per_cell.  The two
   * fractions \p refine_fraction and \p coarsen_fraction must be in
   * \f$ [0,1] \f$.
   *
   * All the function arguments except error_per_cell
   * have been deprecated, and will be removed in
   * future libMesh releases - to control these parameters,
   * set the corresponding member variables.
   */
  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);

  /**
   * Flags elements for coarsening and refinement based on
   * the computed error passed in \p error_per_cell.  This method refines
   * the worst elements with errors greater than
   * \p absolute_global_tolerance / n_active_elem, flagging at most
   * \p refine_fraction * n_active_elem
   * It coarsens elements with errors less than
   * \p coarsen_threshold * \p global_tolerance / n_active_elem,
   * flagging at most
   * \p coarsen_fraction * n_active_elem
   *
   * The three fractions \p refine_fraction \p coarsen_fraction and
   * \p coarsen_threshold should be in \f$ [0,1] \f$.
   */
  void flag_elements_by_error_tolerance (const ErrorVector& error_per_cell);

  /**
   * Flags elements for coarsening and refinement based on
   * the computed error passed in \p error_per_cell.  This method attempts to
   * produce a mesh with slightly more than \p nelem_target active elements,
   * trading element refinement for element coarsening when their error
   * ratios exceed \p coarsen_threshold.  It flags no more than
   * \p refine_fraction * n_elem elements for refinement and flags no
   * more than \p coarsen_fraction * n_elem elements for coarsening.
   * This method returns true if it has done all the AMR/C it can do
   * in a single step, or false if further adaptive steps may be required
   * to produce a mesh with a narrow error distribution and the right
   * number of elements.
   */
  bool flag_elements_by_nelem_target (const ErrorVector& error_per_cell);

  /**
   * Flags elements for coarsening and refinement based on
   * the computed error passed in \p error_per_cell.  This method picks
   * the top \p refine_fraction * \p n_elem elements for refinement and
   * the bottom \p coarsen_fraction * \p n_elem elements for coarsening.
   * The two fractions \p refine_fraction and \p coarsen_fraction must be
   * in \f$ [0,1] \f$.
   *
   * All the function arguments except error_per_cell
   * have been deprecated, and will be removed in
   * future libMesh releases - to control these parameters,
   * set the corresponding member variables.
   */
  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);

  /**
   * Flags elements for coarsening and refinement based on
   * the computed error passed in \p error_per_cell.  This method picks
   * the top \p refine_fraction * \p stddev + \p mean elements for refinement
   * and the bottom \p mean - \p coarsen_fraction * \p stddev elements for
   * coarsening. The two fractions \p refine_fraction and \p coarsen_fraction
   * must be in \f$ [0,1] \f$.
   *
   * All the function arguments except error_per_cell
   * have been deprecated, and will be removed in
   * future libMesh releases - to control these parameters,
   * set the corresponding member variables.
   */
  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);

  /**
   * Takes a mesh whose elements are flagged for h refinement and coarsening,
   * and switches those flags to request p refinement and coarsening instead.
   */
  void switch_h_to_p_refinement();

  /**
   * Takes a mesh whose elements are flagged for h refinement and coarsening,
   * and adds flags to request p refinement and coarsening of the same elements.
   */
  void add_p_to_h_refinement();

  /**
   * Refines and coarsens user-requested elements. Will also
   * refine/coarsen additional elements to satisy level-one rule.
   * It is possible that for a given set of refinement flags there
   * is actually no change upon calling this member function.  Consequently,
   * this function returns \p true if the mesh actually changed (hence
   * data needs to be projected) and \p false otherwise.
   *
   * The argument \p maintain_level_one is now deprecated; use the option
   * face_level_mismatch_limit() instead.
   */
  bool refine_and_coarsen_elements (const bool maintain_level_one=true);

  /**
   * Only coarsens the user-requested elements. Some elements
   * will not be coarsened to satisfy the level one rule.
   * It is possible that for a given set of refinement flags there
   * is actually no change upon calling this member function.  Consequently,
   * this function returns \p true if the mesh actually changed (hence
   * data needs to be projected) and \p false otherwise.
   *
   * The argument \p maintain_level_one is now deprecated; use the option
   * face_level_mismatch_limit() instead.
   */
  bool coarsen_elements (const bool maintain_level_one=true);

  /**
   * Only refines the user-requested elements. 
   * It is possible that for a given set of refinement flags there
   * is actually no change upon calling this member function.  Consequently,
   * this function returns \p true if the mesh actually changed (hence
   * data needs to be projected) and \p false otherwise.
   *
   * The argument \p maintain_level_one is now deprecated; use the option
   * face_level_mismatch_limit() instead.
   */
  bool refine_elements (const bool maintain_level_one=true);
  
  /**
   * Uniformly refines the mesh \p n times.
   */
  void uniformly_refine (unsigned int n=1);
  
  /**
   * Attempts to uniformly coarsen the mesh \p n times.
   */
  void uniformly_coarsen (unsigned int n=1);
  
  /**
   * Uniformly p refines the mesh \p n times.
   */
  void uniformly_p_refine (unsigned int n=1);
  
  /**
   * Attempts to uniformly p coarsen the mesh \p n times.
   */
  void uniformly_p_coarsen (unsigned int n=1);

  /**
   * Returns true if and only if the mesh is level one smooth
   * Returns false otherwise
   * Aborts the program if libmesh_assert_yes is true and 
   * the mesh is not level one smooth
   */
  bool test_level_one (bool libmesh_assert_yes = false);
  
  /**
   * Returns true if and only if the mesh has no elements
   * flagged to be coarsened or refined
   * Returns false otherwise
   * Aborts the program if libmesh_assert_yes is true and 
   * the mesh has flagged elements
   */
  bool test_unflagged (bool libmesh_assert_yes = false);
  
  /**
   * Add point \p p to the mesh. The function returns a pointer to
   * the new node.
   * The processor_id is assigned to the new node (only if no existing
   * node is found.  The tolerance \p tol tells the method how far away
   * from p to search for existing nodes.
   */
  Node* add_point (const Point& p,
                   const unsigned int processor_id,
                   const Real tol);

  /**
   * Adds the element \p elem to the mesh.
   */
  Elem* add_elem (Elem* elem);

  /**
   * @returns a constant reference to the \p MeshBase object associated
   * with this object.
   */
  const MeshBase& get_mesh () const { return _mesh; }

  /**
   * @returns a writeable reference to the \p MeshBase object associated
   * with this object.
   */
  MeshBase&       get_mesh ()       { return _mesh; }

  /**
   * If \p coarsen_by_parents is true, complete groups of sibling elements
   * (elements with the same parent) will be flagged for coarsening.
   * This should make the coarsening more likely to occur as requested.
   *
   * \p coarsen_by_parents is true by default.
   */
  bool& coarsen_by_parents();

  /**
   * The \p refine_fraction sets either a desired target or a desired
   * maximum number of elements to flag for refinement, depending on which
   * flag_elements_by method is called.
   *
   * \p refine_fraction must be in \f$ [0,1] \f$, and is 0.3 by default.
   */
  Real& refine_fraction();

  /**
   * The \p coarsen_fraction sets either a desired target or a desired
   * maximum number of elements to flag for coarsening, depending on which
   * flag_elements_by method is called.
   *
   * \p coarsen_fraction must be in \f$ [0,1] \f$, and is 0 by default.
   */
  Real& coarsen_fraction();

  /**
   * The \p max_h_level is the greatest refinement level an element should
   * reach.
   *
   * \p max_h_level is unlimited (libMesh::invalid_uint) by default
   */
  unsigned int& max_h_level();

  /**
   * The \p coarsen_threshold provides hysteresis in AMR/C strategies.
   * Refinement of elements with error estimate E will be done even
   * at the expense of coarsening elements whose children's accumulated
   * error does not exceed \p coarsen_threshold * E.
   *
   * \p coarsen_threshold must be in \f$ [0,1] \f$, and is 0.1 by default.
   */
  Real& coarsen_threshold();

  /**
   * If \p nelem_target is set to a nonzero value, methods like
   * flag_elements_by_nelem_target() will attempt to keep the number
   * of active elements in the mesh close to nelem_target.
   *
   * \p nelem_target is 0 by default.
   */
  unsigned int& nelem_target();

  /**
   * If \p absolute_global_tolerance is set to a nonzero value, methods
   * like flag_elements_by_global_tolerance() will attempt to reduce
   * the global error of the mesh (defined as the square root of the
   * sum of the squares of the errors on active elements) to below
   * this tolerance.
   *
   * \p absolute_global_tolerance is 0 by default.