mesh_data.h

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

// $Id: mesh_data.h 2789 2008-04-13 02:24:40Z 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_data_h__
#define __mesh_data_h__

// C++ includes
#include <map>
#include <vector>

// Local Includes
#include "libmesh.h"
#include "enum_xdr_mode.h"


// Forward Declarations
class Node;
class Elem;
class MeshBase;
class MeshDataUnvHeader;


/**
 * The \p MeshData class handles actual data and the corresponding
 * I/O on entities (nodes, elements) of meshes.
 * The \p MeshData can be used when dealing with files
 * that contain nodal or element-oriented data, numbered in the same 
 * format as a corresponding mesh file (when activated) or with
 * the \p libMesh element and node indices (when in compatibility mode).  
 * To use \p MeshData, it has to be either activated or the compatibility 
 * mode has to be enabled.
 *
 * @author Daniel Dreyer, 2003
 */

// ------------------------------------------------------------
// MeshData class definition
class MeshData 
{
public:


  //----------------------------------------------------------
  // convenient typedefs
  /**
   * A const iterator over the nodal data entries of
   * \p MeshData.  Use this when a loop over all \p Node*
   * in the \p MeshData is wanted.  Note that only const versions 
   * are provided.  Also these iterators should @e not be 
   * confused with the \p node_iterators provided
   * for the \p Mesh classes!
   */
  typedef std::map<const Node*, std::vector<Number> >::const_iterator const_node_data_iterator;

  /**
   * A const iterator over the element-associated data entries of
   * \p MeshData.  Use this when a loop over all \p Node*
   * in the \p MeshData is wanted.  Note that only const versions 
   * are provided.  Also these iterators should @e not be 
   * confused with the \p node_iterators provided
   * for the \p Mesh classes!
   */
  typedef std::map<const Elem*, std::vector<Number> >::const_iterator const_elem_data_iterator;


  //----------------------------------------------------------
  /**
   * Default Constructor.  Takes const reference
   * to the mesh it belongs to.
   */
  MeshData (const MeshBase& m);

  /**
   * Destructor.
   */
  ~MeshData ();

  /**
   * When \p MeshData should be used, it has to be activated
   * first, @e prior to reading in a mesh with the \p Mesh::read()
   * methods. This will ensure that element and node ids
   * given in the mesh file, i.e. the foreign node and element
   * ids, are stored in the corresponding id maps.
   * Optionally takes a string that should help the user
   * in identifying the data later on.
   */
  void activate (const std::string& descriptor="");

  /**
   * When the \p MeshData should be used, but was @e not activated
   * prior to reading in a mesh, then the compatibility mode enables
   * to still use this object as if the \p MeshData was active.
   * The foreign node and element ids are simply assigned the
   * indices used in \p libMesh.  Note that the compatibility mode
   * should be used with caution, since the node and element
   * indices in \p libMesh may be renumbered any time.  This
   * \p MeshData always employs the current node and element ids,
   * it does @e not create an image of ids when compatibility
   * mode was activated.
   */
  void enable_compatibility_mode (const std::string& descriptor="");

  /**
   * Clears the data fields, but leaves the id maps
   * untouched.  Useful for clearing data for a new
   * data file.  Use \p slim() to delete the maps.
   */
  void clear ();

  /**
   * Once the data is properly read from file, the id 
   * maps can safely be cleared.  However, if this object
   * should remain able to @e write nodal or element oriented 
   * data to file, this method should better @e not be used.
   * Use the appropriate \p bool to select the id map that
   * should be cleared.  By default, both id maps are deleted.
   */
  void slim (const bool node_id_map = true,
	     const bool elem_id_map = true);

  /**
   * Translates the @e nodal data contained in this object
   * to \p data_values and \p data_names.  These two
   * vectors are particularly suitable for use with
   * the \p MeshBase::write method that takes nodal
   * data.  E.g., the export method may be used for
   * inspecting boundary conditions.  A reference
   * to the mesh for which the data should be written
   * has to be provided.  Note that this mesh @e has 
   * to contain the nodes for which this \p MeshData 
   * holds data.  I.e., \p out_mesh may only refer to 
   * the \p MeshBase itself (that this \p MeshData belongs 
   * to), or its \p BoundaryMesh, cf. \p Mesh.  
   */
  void translate (const MeshBase& out_mesh,
		  std::vector<Number>& data_values,
		  std::vector<std::string>& data_names) const;

  /**
   * Read mesh data from file named \p name.  
   * Guess format from the file extension.  Note that
   * prior to this you have to at least either
   * \p close_node_map() or \p close_elem_map().
   */
  void read (const std::string& name);

  /**
   * Write mesh data to file named \p name.  
   * Guess format from the file extension.
   */
  void write (const std::string& name);

  /**
   * @returns a string containing relevant information
   * about the mesh.
   */
  std::string get_info () const;

  /**
   * Prints relevant information about the mesh.
   */
  void print_info (std::ostream& os=std::cout) const;

  /**
   * Same as above, but allows you to use the stream syntax.
   */
  friend std::ostream& operator << (std::ostream& os, const MeshData& m);
  
  
  //----------------------------------------------------------
  // Node-associated data
  /**
   * @returns the \f$ i^{th} \f$ value (defaults to 0) associated 
   * with node \p node.  Returns \p libMesh::zero when there
   * is no such \p node in the map.
   */
  Number operator() (const Node* node, 
		     const unsigned int i=0) const;

  /**
   * @returns \p true when the node \p node has data,
   * \p false otherwise.
   */
  bool has_data (const Node* node) const;

  /**
   * @returns a const reference to the values associated with 
   * the node \p node.  @e Beware: this method will crash
   * when there is no data associated with the node \p node!
   * Check existence through \p has_data() first.
   */
  const std::vector<Number>& get_data (const Node* node) const;

  /**
   * @Sets all the data values associated with 
   * the node \p node, overwriting any existing vector
   */
  void set_data (const Node* node, const std::vector<Number>& val);

  /**
   * @returns the number of \p Number -type data 
   * (i.e., the size of the \p std::vector<Number>
   * returned through the \p operator() methods)
   * associated with a node.  Returns 0 when no
   * nodal data exists.
   */
  unsigned int n_val_per_node () const;

  /**
   * @returns the number of nodes for which this
   * \p MeshData has data stored.
   */
  unsigned int n_node_data () const;

  /**
   * Returns the \p MeshData::const_node_data_iterator which points
   * to the beginning of the \p Node* data containers
   * used here.
   */
  const_node_data_iterator node_data_begin () const;

  /**
   * Returns the \p MeshData::const_node_data_iterator which points
   * to the end of the \p Node* data containers used here.
   */
  const_node_data_iterator node_data_end () const;

  /**
   * For the desperate user, nodal boundary conditions 
   * may be inserted directly through the map \p nd.
   * It is mandatory that there does not yet exist any
   * other node data in this object, that the id maps
   * are closed, that the size of the std::vector's of 
   * each map have identical length and that the Node* 
   * point to nodes of the associated mesh.  
   * Note that this method takes a non-const reference 
   * and essentially clears the passed-in data.
   * If \p close_elem_data is \p true (default), then
   * this \p MeshData is ready for use: write to file,
   * use the operator() methods etc. If \p false, the 
   * user @e has to add element-associated data, too.
   */
  void insert_node_data (std::map<const Node*,
			          std::vector<Number> >& nd,
			 const bool close_elem_data = true);


  //----------------------------------------------------------
  // Element-associated data
  /**
   * @returns the \f$ i^{th} \f$ value (defaults to 0) associated 
   * with element \p elem.  Returns \p libMesh::zero when there
   * is no data for \p elem in the map.
   */
  Number operator() (const Elem* elem, 
		     const unsigned int i=0) const;

  /**
   * @returns \p true when the element \p elem has data,
   * \p false otherwise.
   */
  bool has_data (const Elem* elem) const;

  /**
   * @returns a const reference to the values associated with 
   * the element \p elem.  @e Beware: this method will crash
   * when there is no data associated with the element \p elem!
   * Check existence through \p has_data() first.
   */
  const std::vector<Number>& get_data (const Elem* elem) const;

  /**
   * @Sets all the data values associated with 
   * the element \p elem, overwriting any existing vector
   */
  void set_data (const Elem* elem, const std::vector<Number> &val);

  /**
   * @returns the number of \p Number -type data 
   * (i.e., the size of the \p std::vector<Number>
   * returned through the \p operator() methods)
   * associated with an element.  Returns 0 when
   * there is no element-associated data.
   */
  unsigned int n_val_per_elem () const;

  /**
   * @returns the number of elements for which this
   * \p MeshData has data stored.
   */
  unsigned int n_elem_data () const;

  /**
   * Returns a \p MeshData::const_elem_data_iterators which points
   * to the beginning of the \p Elem* data containers
   * used here.
   */
  const_elem_data_iterator elem_data_begin () const;

  /**
   * Returns a \p MeshData::const_elem_data_iterators which points
   * to the end of the \p Elem* data containers used here.
   */
  const_elem_data_iterator elem_data_end () const;

  /**
   * For the desperate user, element-associated boundary 
   * conditions may be inserted directly through the 
   * map \p ed.  Similar to the version for nodal data, 
   * it is imperative that the local \p _elem_data is empty, 
   * that the id maps are closed, that the size of the 
   * \p std::vector's of each map have identical length 
   * and that the \p Elem* point to elements of the 
   * associated mesh.  
   * Note that this method takes a non-const reference 
   * and essentially clears the passed-in data.
   * If \p close_node_data is \p true (default), then
   * this \p MeshData is ready for use: write to file,
   * use the operator() methods etc. If \p false, the 
   * user @e has to add nodal data, too.
   */
  void insert_elem_data (std::map<const Elem*,
			          std::vector<Number> >& ed,
			 const bool close_node_data = true);


  //----------------------------------------------------------
  /**
   * @returns \p true when this object is active and working.
   * Use \p activate() to bring this object alive.
   */
  bool active () const;
  /**
   * @returns \p true when this object is in compatibility
   * mode.  See \p enable_compatibility_mode() for details.
   */
  bool compatibility_mode () const;

  /**
   * @returns \p true when this object is properly initialized
   * and ready for use for @e element associated data, \p false 
   * otherwise.
   */
  bool elem_initialized () const;

  /**
   * @returns \p true when this object is properly initialized
   * and ready for use for @e nodal data, \p false otherwise.