grid.h

Go to the documentation of this file.

/*
 * Copyright (c) 2009-2015:  G-CSC, Goethe University Frankfurt
 * Author: Sebastian Reiter
 * 
 * This file is part of UG4.
 * 
 * UG4 is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License version 3 (as published by the
 * Free Software Foundation) with the following additional attribution
 * requirements (according to LGPL/GPL v3 §7):
 * 
 * (1) The following notice must be displayed in the Appropriate Legal Notices
 * of covered and combined works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (2) The following notice must be displayed at a prominent place in the
 * terminal output of covered works: "Based on UG4 (www.ug4.org/license)".
 * 
 * (3) The following bibliography is recommended for citation and must be
 * preserved in all covered files:
 * "Reiter, S., Vogel, A., Heppner, I., Rupp, M., and Wittum, G. A massively
 *   parallel geometric multigrid solver on hierarchically distributed grids.
 *   Computing and visualization in science 16, 4 (2013), 151-164"
 * "Vogel, A., Reiter, S., Rupp, M., Nägel, A., and Wittum, G. UG4 -- a novel
 *   flexible software system for simulating pde based models on high performance
 *   computers. Computing and visualization in science 16, 4 (2013), 165-179"
 * 
 * This program 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.
 */
 
#ifndef __H__LIB_GRID__GRID__
#define __H__LIB_GRID__GRID__
 
#include <vector>
#include <list>
#include <memory>
#include <boost/function.hpp>
#include "common/util/message_hub.h"
#include "common/ug_config.h"
#include "grid_constants.h"
#include "grid_base_objects.h"
#include "grid_observer.h"
#include "grid_object_collection.h"
#include "element_storage.h"
#include "grid_base_object_traits.h"
 
//  Define PROFILE_GRID to profile some often used gird-methods
//#define PROFILE_GRID
#ifdef PROFILE_GRID
  #include "common/profiler/profiler.h"
  #define GRID_PROFILE_FUNC() PROFILE_FUNC()
  #define GRID_PROFILE(name)  PROFILE_BEGIN(name)
  #define GRID_PROFILE_END()  PROFILE_END()
#else
  #define GRID_PROFILE_FUNC()
  #define GRID_PROFILE(name)
  #define GRID_PROFILE_END()
#endif
 
namespace ug
{
 
//  predeclaration of the distributed grid manager, which handles parallelization
//  of grids. If you want to use it, you have to include
//  "lib_grid/parallelization/distributed_grid.h"
class DistributedGridManager;
 
//  predeclaration of the periodic boundary identifier, which handles the master/slave
//  identification of grid elements. If you want to use it, you have to include
//  "lib_grid/tools/periodic_boundary_identifier.h"
class PeriodicBoundaryManager;
 
//  Grid
 
class UG_API Grid
{
  public:
    template <class TElem>
    struct traits{
      typedef typename TElem::grid_base_object      base_object;
      typedef ug::ElementStorage<base_object>         ElementStorage;
      typedef typename ElementStorage::AttachmentPipe     AttachmentPipe;
      typedef typename ElementStorage::AttachedElementList  AttachedElementList;
      typedef typename ElementStorage::SectionContainer   SectionContainer;
 
      typedef typename geometry_traits<TElem>::iterator   iterator;
      typedef typename geometry_traits<TElem>::const_iterator const_iterator;
 
      typedef PointerConstArray<TElem*>           secure_container;
 
    //  CALLBACKS
      typedef boost::function<bool (base_object*)>      callback;
    };
 
 
    typedef traits<Vertex>  vertex_traits;
    typedef traits<Edge>  edge_traits;
    typedef traits<Face>    face_traits;
    typedef traits<Volume>    volume_traits;
    typedef traits<Vertex>::secure_container  SecureVertexContainer;
    typedef traits<Edge>::secure_container    SecureEdgeContainer;
    typedef traits<Face>::secure_container      SecureFaceContainer;
    typedef traits<Volume>::secure_container    SecureVolumeContainer;
 
    typedef ug::AttachmentPipe<Vertex*, VertexElementStorage> VertexAttachmentPipe;
    typedef ug::AttachmentPipe<Edge*, EdgeElementStorage>   EdgeAttachmentPipe;
    typedef ug::AttachmentPipe<Face*, FaceElementStorage>     FaceAttachmentPipe;
    typedef ug::AttachmentPipe<Volume*, VolumeElementStorage>   VolumeAttachmentPipe;
 
 
    template <class TElem, class TAttachment>
    class AttachmentAccessor : public ug::AttachmentAccessor<typename TElem::grid_base_object*,
                                 TAttachment,
                                 typename traits<TElem>::ElementStorage>
    {
      public:
        AttachmentAccessor();
        AttachmentAccessor(const AttachmentAccessor& aa);
        AttachmentAccessor(Grid& grid, TAttachment& a);
        AttachmentAccessor(Grid& grid, TAttachment& a, bool autoAttach);
 
        inline bool access(Grid& grid, TAttachment& a)
          {
            return ug::AttachmentAccessor<typename TElem::grid_base_object*,
                            TAttachment,
                            typename traits<TElem>::ElementStorage>::
              access(grid.get_attachment_pipe<TElem>(), a);
          }
    };
 
  //  half-specialized AttachmentAccessors:
    template <class TAttachment>
    class VertexAttachmentAccessor : public AttachmentAccessor<Vertex, TAttachment>
    {
      public:
        VertexAttachmentAccessor();
        VertexAttachmentAccessor(const VertexAttachmentAccessor& aa);
        VertexAttachmentAccessor(Grid& grid, TAttachment& a);
        VertexAttachmentAccessor(Grid& grid, TAttachment& a, bool autoAttach);
    };
 
    template <class TAttachment>
    class EdgeAttachmentAccessor : public AttachmentAccessor<Edge, TAttachment>
    {
      public:
        EdgeAttachmentAccessor();
        EdgeAttachmentAccessor(const EdgeAttachmentAccessor& aa);
        EdgeAttachmentAccessor(Grid& grid, TAttachment& a);
        EdgeAttachmentAccessor(Grid& grid, TAttachment& a, bool autoAttach);
    };
 
    template <class TAttachment>
    class FaceAttachmentAccessor : public AttachmentAccessor<Face, TAttachment>
    {
      public:
        FaceAttachmentAccessor();
        FaceAttachmentAccessor(const FaceAttachmentAccessor& aa);
        FaceAttachmentAccessor(Grid& grid, TAttachment& a);
        FaceAttachmentAccessor(Grid& grid, TAttachment& a, bool autoAttach);
    };
 
    template <class TAttachment>
    class VolumeAttachmentAccessor : public AttachmentAccessor<Volume, TAttachment>
    {
      public:
        VolumeAttachmentAccessor();
        VolumeAttachmentAccessor(const VolumeAttachmentAccessor& aa);
        VolumeAttachmentAccessor(Grid& grid, TAttachment& a);
        VolumeAttachmentAccessor(Grid& grid, TAttachment& a, bool autoAttach);
    };
 
    typedef std::vector<Vertex*>  VertexContainer;
    typedef std::vector<Edge*>    EdgeContainer;
    typedef std::vector<Face*>      FaceContainer;
    typedef std::vector<Volume*>    VolumeContainer;
 
    typedef EdgeContainer::iterator   AssociatedEdgeIterator;
    typedef FaceContainer::iterator   AssociatedFaceIterator;
    typedef VolumeContainer::iterator   AssociatedVolumeIterator;
 
  public:
  //  constructors and destructor
 
    Grid();
 
 
    Grid(uint options);
 
 
    Grid(const Grid& grid);
 
    virtual ~Grid();
 
 
    Grid& operator = (const Grid& grid);
    
  //  grid options
    void set_options(uint options);
    uint get_options() const;
    void enable_options(uint options);  
    void disable_options(uint options); 
    bool option_is_enabled(uint option) const;
 
  //  parallelism
 
    void set_parallel(bool parallel);
 
 
    inline bool is_parallel() const;
 
 
    inline DistributedGridManager* distributed_grid_manager();
    inline const DistributedGridManager* distributed_grid_manager() const;
  //  periodic boundaries
 
    void set_periodic_boundaries(bool);
    bool has_periodic_boundaries() const;
 
 
    PeriodicBoundaryManager* periodic_boundary_manager();
    const PeriodicBoundaryManager* periodic_boundary_manager() const;
  //  clear
    void clear();
    void clear_geometry();
    void clear_attachments();
 
  //  element creation
 
    template<class TGeomObj>
    typename geometry_traits<TGeomObj>::iterator
    create(GridObject* pParent = NULL);
 
 
    template <class TGeomObj>
    typename geometry_traits<TGeomObj>::iterator
    create(const typename geometry_traits<TGeomObj>::Descriptor& descriptor,
        GridObject* pParent = NULL);
 
 
    template <class TGeomObj>
    typename geometry_traits<TGeomObj>::iterator
    create_and_replace(typename geometry_traits<TGeomObj>::grid_base_object* pReplaceMe);
 
    VertexIterator create_by_cloning(Vertex* pCloneMe, GridObject* pParent = NULL);
 
    EdgeIterator create_by_cloning(Edge* pCloneMe, const IVertexGroup& ev, GridObject* pParent = NULL);
 
    FaceIterator create_by_cloning(Face* pCloneMe, const IVertexGroup& fv, GridObject* pParent = NULL);
 
    VolumeIterator create_by_cloning(Volume* pCloneMe, const IVertexGroup& vv, GridObject* pParent = NULL);
 
 
    template <class TGeomObj>
    void reserve(size_t num);
 
  //  element deletion
    void erase(GridObject* geomObj);
    void erase(Vertex* vrt);
    void erase(Edge* edge);
    void erase(Face* face);
    void erase(Volume* vol);
 
    template <class GeomObjIter>
    void erase(const GeomObjIter& iterBegin, const GeomObjIter& iterEnd);
 
    template <class TGeomObj>
    void clear();
 
  //  replace
 
    bool replace_vertex(Vertex* vrtOld, Vertex* vrtNew);
 
 
    bool replace_vertex_is_valid(Vertex* vrtOld, Vertex* vrtNew);
 
 
    void objects_will_be_merged(Vertex* target, Vertex* elem1,
                  Vertex* elem2);
    void objects_will_be_merged(Edge* target, Edge* elem1,
                  Edge* elem2);
    void objects_will_be_merged(Face* target, Face* elem1,
                  Face* elem2);
    void objects_will_be_merged(Volume* target, Volume* elem1,
                  Volume* elem2);
  /*
    template <class VrtPairIter>
    void replace_vertices(VrtPairIter& iterBegin, VrtPairIter& iterEnd);
  */
 
  //  geometric-object-collection
    virtual GridObjectCollection get_grid_objects();
 
    void flip_orientation(Edge* e);
    
    void flip_orientation(Face* f);
 
    void flip_orientation(Volume* vol);
    
  //  Iterators
    template <class TGeomObj>
    typename geometry_traits<TGeomObj>::iterator
    begin();
 
    template <class TGeomObj>
    typename geometry_traits<TGeomObj>::iterator
    end();
 
    inline VertexIterator vertices_begin()  {return begin<Vertex>();}
    inline VertexIterator vertices_end()    {return end<Vertex>();}
    inline EdgeIterator   edges_begin()   {return begin<Edge>();}
    inline EdgeIterator   edges_end()     {return end<Edge>();}
    inline FaceIterator     faces_begin()   {return begin<Face>();}
    inline FaceIterator     faces_end()     {return end<Face>();}
    inline VolumeIterator   volumes_begin()   {return begin<Volume>();}
    inline VolumeIterator   volumes_end()   {return end<Volume>();}
  
    template <class TGeomObj>
    typename geometry_traits<TGeomObj>::const_iterator
    begin() const;
 
    template <class TGeomObj>
    typename geometry_traits<TGeomObj>::const_iterator
    end() const;
 
 
    template <class TGeomObj> TGeomObj* front();
    
 
    template <class TGeomObj> TGeomObj* back();
    
  //  element manipulation
  /*
    void set_vertices(Edge* e, EdgeDesctiptor& ed);
    void set_vertices(Face* f, FaceDescriptor& fd);
    void set_vertices(Volume* v, VolumeDescriptor& vd);
  */
 
  //  element numbers
    template <class TGeomObj>
    size_t num() const;
    inline size_t num_vertices() const  {return num<Vertex>();}
    inline size_t num_edges() const   {return num<Edge>();}
    inline size_t num_faces() const   {return num<Face>();}
    inline size_t num_volumes()const    {return num<Volume>();}
 
    size_t vertex_fragmentation();  
    size_t edge_fragmentation();    
    size_t face_fragmentation();    
    size_t volume_fragmentation();  
 
 
    template <class TGeomObj>
    size_t attachment_container_size() const;
 
  //  connectivity-information
    Edge* get_edge(Vertex* v1, Vertex* v2);
 
    Edge* get_edge(const EdgeVertices& ev);
 
    Edge* get_edge(Face* f, int ind);
 
    Edge* get_edge(Volume* v, int ind);
 
    Face* get_face(const FaceVertices& fv);
 
    Face* get_face(Volume* v, int ind);
 
    Volume* get_volume(const VolumeVertices& vv);
    
 
    Edge* get_element(const EdgeVertices& ev)   {return get_edge(ev);}
    Face* get_element(const FaceVertices& fv)   {return get_face(fv);}
    Volume* get_element(const VolumeVertices& vv) {return get_volume(vv);}
    Vertex* get_element(const VertexDescriptor& vd) {return vd.vertex();}
    
 
  //  access to the sides of an geometric object
 
    Vertex::side* get_side(Vertex* obj, size_t side);
    Edge::side* get_side(Edge* obj, size_t side);
    Face::side* get_side(Face* obj, size_t side);
    Volume::side* get_side(Volume* obj, size_t side);
 
 
    GridObject* get_opposing_object(Vertex* vrt, Face* elem);
    GridObject* get_opposing_object(Vertex* vrt, Volume* elem);
 
    template <class TElem>
    void associated_elements(traits<Vertex>::secure_container& elemsOut, TElem* e);
    template <class TElem>
    void associated_elements(traits<Edge>::secure_container& elemsOut, TElem* e);
    template <class TElem>
    void associated_elements(traits<Face>::secure_container& elemsOut, TElem* e);
    template <class TElem>
    void associated_elements(traits<Volume>::secure_container& elemsOut, TElem* e);
 
    template <class TElem>
    void associated_elements_sorted(traits<Vertex>::secure_container& elemsOut, TElem* e);
    template <class TElem>
    void associated_elements_sorted(traits<Edge>::secure_container& elemsOut, TElem* e);
    template <class TElem>
    void associated_elements_sorted(traits<Face>::secure_container& elemsOut, TElem* e);
    template <class TElem>
    void associated_elements_sorted(traits<Volume>::secure_container& elemsOut, TElem* e);
 
 
  //  attachments
    template <class TGeomObjClass>
    void attach_to(IAttachment& attachment, bool passOnValues);
 
    inline void attach_to_vertices(IAttachment& attachment, bool passOnValues)  {attach_to<Vertex>(attachment, passOnValues);}
    inline void attach_to_edges(IAttachment& attachment, bool passOnValues)   {attach_to<Edge>(attachment, passOnValues);}
    inline void attach_to_faces(IAttachment& attachment, bool passOnValues)   {attach_to<Face>(attachment, passOnValues);}
    inline void attach_to_volumes(IAttachment& attachment, bool passOnValues)   {attach_to<Volume>(attachment, passOnValues);}
 
    inline void attach_to_all(IAttachment& attachment, bool passOnValues);
 
    template <class TGeomObjClass>
    inline void attach_to(IAttachment& attachment)  {attach_to<TGeomObjClass>(attachment, attachment.default_pass_on_behaviour());}
 
    inline void attach_to_vertices(IAttachment& attachment) {attach_to<Vertex>(attachment);}
    inline void attach_to_edges(IAttachment& attachment)  {attach_to<Edge>(attachment);}
    inline void attach_to_faces(IAttachment& attachment)  {attach_to<Face>(attachment);}
    inline void attach_to_volumes(IAttachment& attachment)  {attach_to<Volume>(attachment);}
 
    inline void attach_to_all(IAttachment& attachment);
 
  //  attach with specified default value and default pass-on behaviour
    template <class TGeomObjClass, class TAttachment>
    void attach_to_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue);
 
    template <class TAttachment>
    inline void attach_to_vertices_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue) {attach_to_dv<Vertex>(attachment, defaultValue);}
    template <class TAttachment>
    inline void attach_to_edges_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue)  {attach_to_dv<Edge>(attachment, defaultValue);}
    template <class TAttachment>
    inline void attach_to_faces_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue)  {attach_to_dv<Face>(attachment, defaultValue);}
    template <class TAttachment>
    inline void attach_to_volumes_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue)  {attach_to_dv<Volume>(attachment, defaultValue);}
 
    template <class TAttachment>
    inline void attach_to_all_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue);
 
  //  attach with specified default value and custom pass-on behaviour
    template <class TGeomObjClass, class TAttachment>
    void attach_to_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue, bool passOnValues);
 
    template <class TAttachment>
    inline void attach_to_vertices_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue, bool passOnValues)  {attach_to_dv<Vertex>(attachment, defaultValue, passOnValues);}
    template <class TAttachment>
    inline void attach_to_edges_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue, bool passOnValues)   {attach_to_dv<Edge>(attachment, defaultValue, passOnValues);}
    template <class TAttachment>
    inline void attach_to_faces_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue, bool passOnValues)   {attach_to_dv<Face>(attachment, defaultValue, passOnValues);}
    template <class TAttachment>
    inline void attach_to_volumes_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue, bool passOnValues) {attach_to_dv<Volume>(attachment, defaultValue, passOnValues);}
 
    template <class TAttachment>
    inline void attach_to_all_dv(TAttachment& attachment, const typename TAttachment::ValueType& defaultValue, bool passOnValues);
  //  detach
    template <class TGeomObjClass>
    void detach_from(IAttachment& attachment);
 
    inline void detach_from_vertices(IAttachment& attachment) {detach_from<Vertex>(attachment);}
    inline void detach_from_edges(IAttachment& attachment)    {detach_from<Edge>(attachment);}
    inline void detach_from_faces(IAttachment& attachment)    {detach_from<Face>(attachment);}
    inline void detach_from_volumes(IAttachment& attachment)  {detach_from<Volume>(attachment);}
 
    inline void detach_from_all(IAttachment& attachment);
 
 
    template <class TGeomObjClass>
    inline bool has_attachment(IAttachment& attachment)     {return get_attachment_pipe<TGeomObjClass>().has_attachment(attachment);}
 
    inline bool has_vertex_attachment(IAttachment& attachment)  {return has_attachment<Vertex>(attachment);}
    inline bool has_edge_attachment(IAttachment& attachment)  {return has_attachment<Edge>(attachment);}
    inline bool has_face_attachment(IAttachment& attachment)  {return has_attachment<Face>(attachment);}
    inline bool has_volume_attachment(IAttachment& attachment)  {return has_attachment<Volume>(attachment);}
 
  //  direct attachment access
    template <class TGeomObj>
    uint get_attachment_data_index(TGeomObj* pObj) const;
 
    template <class TGeomObj, class TAttachment>
    typename TAttachment::ContainerType*
    get_attachment_data_container(TAttachment& attachment);
    
 
    template <class TGeomObj>
    typename traits<TGeomObj>::AttachmentPipe&
    get_attachment_pipe();
 
  //  observers
    void register_observer(GridObserver* observer, uint observerType = OT_FULL_OBSERVER);
    void unregister_observer(GridObserver* observer);
 
/*
    template <class GeomObjClass>
    util::IAttachmentDataContainer* get_data_container(util::IAttachment& attachment);
 
    util::IAttachmentDataContainer* get_vertex_data_container(util::IAttachment& attachment)  {return get_data_container<Vertex>(attachment);}
    util::IAttachmentDataContainer* get_edge_data_container(util::IAttachment& attachment)    {return get_data_container<Edge>(attachment);}
    util::IAttachmentDataContainer* get_face_data_container(util::IAttachment& attachment)    {return get_data_container<Face>(attachment);}
    util::IAttachmentDataContainer* get_volume_data_container(util::IAttachment& attachment)  {return get_data_container<Volume>(attachment);}
*/
 
  //  pass_on_values
    void pass_on_values(Vertex* objSrc, Vertex* objDest);
    void pass_on_values(Edge* objSrc, Edge* objDest);
    void pass_on_values(Face* objSrc, Face* objDest);
    void pass_on_values(Volume* objSrc, Volume* objDest);
 
  //  subject to change!
    AssociatedEdgeIterator associated_edges_begin(Vertex* vrt);
    AssociatedEdgeIterator associated_edges_end(Vertex* vrt);
    AssociatedEdgeIterator associated_edges_begin(Face* face);
    AssociatedEdgeIterator associated_edges_end(Face* face);
    AssociatedEdgeIterator associated_edges_begin(Volume* vol);
    AssociatedEdgeIterator associated_edges_end(Volume* vol);
 
    AssociatedFaceIterator associated_faces_begin(Vertex* vrt);
    AssociatedFaceIterator associated_faces_end(Vertex* vrt);
    AssociatedFaceIterator associated_faces_begin(Edge* edge);
    AssociatedFaceIterator associated_faces_end(Edge* edge);
    AssociatedFaceIterator associated_faces_begin(Volume* vol);
    AssociatedFaceIterator associated_faces_end(Volume* vol);
 
    AssociatedVolumeIterator associated_volumes_begin(Vertex* vrt);
    AssociatedVolumeIterator associated_volumes_end(Vertex* vrt);
    AssociatedVolumeIterator associated_volumes_begin(Edge* edge);
    AssociatedVolumeIterator associated_volumes_end(Edge* edge);
    AssociatedVolumeIterator associated_volumes_begin(Face* face);
    AssociatedVolumeIterator associated_volumes_end(Face* face);
 
  //  advanced element manipulation
    inline void register_element(Vertex* v, GridObject* pParent = NULL) {register_vertex(v, pParent);}
    inline void unregister_element(Vertex* v)                 {unregister_vertex(v);}
    inline void register_element(Edge* e, GridObject* pParent = NULL)   {register_edge(e, pParent);}
    inline void unregister_element(Edge* e)                   {unregister_edge(e);}
    inline void register_element(Face* f, GridObject* pParent = NULL)     {register_face(f, pParent);}
    inline void unregister_element(Face* f)                     {unregister_face(f);}
    inline void register_element(Volume* v, GridObject* pParent = NULL)   {register_volume(v, pParent);}
    inline void unregister_element(Volume* v)                   {unregister_volume(v);}
 
    void register_and_replace_element(Vertex* v, Vertex* pReplaceMe);
    void register_and_replace_element(Edge* e, Edge* pReplaceMe);
    void register_and_replace_element(Face* f, Face* pReplaceMe);
    void register_and_replace_element(Volume* v, Volume* pReplaceMe);
 
  //  marks
 
    void begin_marking();
 
    void clear_marks();
 
 
    inline void mark(GridObject* obj);
    inline void mark(Vertex* obj);
    inline void mark(Edge* obj);
    inline void mark(Face* obj);
    inline void mark(Volume* obj);
 
    template <class TIterator>
    void mark(TIterator begin, TIterator end);
    
 
    inline void unmark(GridObject* obj);
    inline void unmark(Vertex* obj);
    inline void unmark(Edge* obj);
    inline void unmark(Face* obj);
    inline void unmark(Volume* obj);
 
    template <class TIterator>
    void unmark(TIterator begin, TIterator end);
    
 
    inline bool is_marked(GridObject* obj) const;
    inline bool is_marked(Vertex* obj) const;
    inline bool is_marked(Edge* obj) const;
    inline bool is_marked(Face* obj) const;
    inline bool is_marked(Volume* obj) const;
    void end_marking();
    
    SPMessageHub message_hub()    {return m_messageHub;}
 
    void test_attached_linked_lists();
 
  protected:
    typedef std::vector<GridObserver*>  ObserverContainer;
 
    typedef Attachment<VertexContainer> AVertexContainer;
    typedef Attachment<EdgeContainer> AEdgeContainer;
    typedef Attachment<FaceContainer> AFaceContainer;
    typedef Attachment<VolumeContainer> AVolumeContainer;
 
    typedef Attachment<int> AMark;
 
  protected:
 
    void notify_and_clear_observers_on_grid_destruction(GridObserver* initiator = NULL);
 
    template <class TElem> inline
    typename traits<TElem>::ElementStorage&
    element_storage()
    {return ElementStorageSelector<typename geometry_traits<TElem>::grid_base_object>::
        element_storage(m_vertexElementStorage, m_edgeElementStorage,
                m_faceElementStorage, m_volumeElementStorage);
    }
 
    template <class TElem> inline
    const typename traits<TElem>::ElementStorage&
    element_storage() const
    {return ElementStorageSelector<typename geometry_traits<TElem>::grid_base_object>::
        element_storage(m_vertexElementStorage, m_edgeElementStorage,
                m_faceElementStorage, m_volumeElementStorage);
    }
 
 
    void assign_grid(const Grid& grid);
    
 
    inline void assign_hash_value(Vertex* vrt)  {vrt->m_hashValue = m_hashCounter++;}
 
    void register_vertex(Vertex* v, GridObject* pParent = NULL);
    void unregister_vertex(Vertex* v);
    void register_edge(Edge* e, GridObject* pParent = NULL,
            Face* createdByFace = NULL, Volume* createdByVol = NULL);
    void unregister_edge(Edge* e);
    void register_face(Face* f, GridObject* pParent = NULL,
               Volume* createdByVol = NULL);
    void unregister_face(Face* f);
    void register_volume(Volume* v, GridObject* pParent = NULL);
    void unregister_volume(Volume* v);
 
    void change_options(uint optsNew);
 
    void change_vertex_options(uint optsNew);
    void change_edge_options(uint optsNew);
    void change_face_options(uint optsNew);
    void change_volume_options(uint optsNew);
 
    void vertex_store_associated_edges(bool bStoreIt);
    void vertex_store_associated_faces(bool bStoreIt);
    void vertex_store_associated_volumes(bool bStoreIt);
    void edge_store_associated_faces(bool bStoreIt);
    void edge_store_associated_volumes(bool bStoreIt);
    void face_store_associated_edges(bool bStoreIt);
    void face_store_associated_volumes(bool bStoreIt);
    void face_autogenerate_edges(bool bAutogen);
    void volume_store_associated_edges(bool bStoreIt);
    void volume_store_associated_faces(bool bStoreIt);
    void volume_autogenerate_edges(bool bAutogen);
    void volume_autogenerate_faces(bool bAutogen);
 
    void volume_sort_associated_edge_container();
 
    template <class TAttachmentPipe, class TElem>
    void pass_on_values(TAttachmentPipe& attachmentPipe,
              TElem* pSrc, TElem* pDest);
 
  //  some methods that simplify auto-enabling of grid options
    inline void autoenable_option(uint option, const char* caller, const char* optionName);
 
  //  neighbourhood access
    template <class TGeomObj>
    Edge* find_edge_in_associated_edges(TGeomObj* obj,
                      const EdgeVertices& ev);
                        
    template <class TGeomObj>
    Face* find_face_in_associated_faces(TGeomObj* obj,
                      const FaceVertices& fv);
                        
    template <class TGeomObj>
    Volume* find_volume_in_associated_volumes(TGeomObj* obj,
                          const VolumeVertices& vv);
 
  //  get associated elements
    void get_associated(SecureVertexContainer& vrts, Edge* e);
    void get_associated(SecureVertexContainer& vrts, Face* f);
    void get_associated(SecureVertexContainer& vrts, Volume* v);
 
    void get_associated(SecureEdgeContainer& edges, Vertex* v);
    void get_associated(SecureEdgeContainer& edges, Face* f);
    void get_associated(SecureEdgeContainer& edges, Volume* v);
 
    void get_associated(SecureFaceContainer& faces, Vertex* v);
    void get_associated(SecureFaceContainer& faces, Edge* e);
    void get_associated(SecureFaceContainer& faces, Volume* v);
 
    void get_associated(SecureVolumeContainer& vols, Vertex* v);
    void get_associated(SecureVolumeContainer& vols, Edge* e);
    void get_associated(SecureVolumeContainer& vols, Face* f);
 
    template <class TContainer>
    void get_associated(TContainer& container, GridObject* o);
 
    template <class TElem>
    void get_associated(typename traits<typename TElem::grid_base_object>
              ::secure_container& elems, TElem* e);
    
    void get_associated_vols_raw(SecureVolumeContainer& vols, Face* f);
 
    void get_associated_sorted(SecureVertexContainer& vrts, Edge* e) const;
    void get_associated_sorted(SecureVertexContainer& vrts, Face* f) const;
    void get_associated_sorted(SecureVertexContainer& vrts, Volume* v) const;
 
    void get_associated_sorted(SecureEdgeContainer& edges, Vertex* v);
    void get_associated_sorted(SecureEdgeContainer& edges, Face* f);
    void get_associated_sorted(SecureEdgeContainer& edges, Volume* v);
 
    void get_associated_sorted(SecureFaceContainer& faces, Vertex* v);
    void get_associated_sorted(SecureFaceContainer& faces, Edge* e);
    void get_associated_sorted(SecureFaceContainer& faces, Volume* v);
    
    void get_associated_sorted(SecureVolumeContainer& vols, Vertex* v);
    void get_associated_sorted(SecureVolumeContainer& vols, Edge* e);
    void get_associated_sorted(SecureVolumeContainer& vols, Face* f);
 
    template <class TElem>
    void get_associated_sorted(typename traits<typename TElem::grid_base_object>
                   ::secure_container& elems, TElem* e);
 
 
 
    template <class TAttachmentPipe>
    void copy_user_attachments(const TAttachmentPipe& apSrc, TAttachmentPipe& apDest,
                  std::vector<int>& srcDataIndices);
 
  //  marks
    void init_marks();
    void reset_marks();
    void remove_marks();
 
  protected:
 
    inline traits<Vertex>::SectionContainer::iterator
    get_iterator(Vertex* o)
    {
      return m_vertexElementStorage.m_sectionContainer.
          get_container().get_iterator(o);
    }
 
    inline traits<Edge>::SectionContainer::iterator
    get_iterator(Edge* o)
    {
      return m_edgeElementStorage.m_sectionContainer.
          get_container().get_iterator(o);
    }
 
    inline traits<Face>::SectionContainer::iterator
    get_iterator(Face* o)
    {
      return m_faceElementStorage.m_sectionContainer.
          get_container().get_iterator(o);
    }
 
    inline traits<Volume>::SectionContainer::iterator
    get_iterator(Volume* o)
    {
      return m_volumeElementStorage.m_sectionContainer.
          get_container().get_iterator(o);
    }
    template <class TElem>
    void clear_attachments();
 
  protected:
    VertexElementStorage  m_vertexElementStorage;
    EdgeElementStorage    m_edgeElementStorage;
    FaceElementStorage    m_faceElementStorage;
    VolumeElementStorage  m_volumeElementStorage;
 
    uint      m_options;
    uint32      m_hashCounter;
 
  //  observer handling
    ObserverContainer m_gridObservers;
    ObserverContainer m_vertexObservers;
    ObserverContainer m_edgeObservers;
    ObserverContainer m_faceObservers;
    ObserverContainer m_volumeObservers;
 
  //  interconnection management
    AVertexContainer  m_aVertexContainer;
    AEdgeContainer    m_aEdgeContainer;
    AFaceContainer    m_aFaceContainer;
    AVolumeContainer  m_aVolumeContainer;
 
    AttachmentAccessor<Vertex, AEdgeContainer>    m_aaEdgeContainerVERTEX;
    AttachmentAccessor<Vertex, AFaceContainer>    m_aaFaceContainerVERTEX;
    AttachmentAccessor<Vertex, AVolumeContainer>  m_aaVolumeContainerVERTEX;
 
    AttachmentAccessor<Edge, AEdgeContainer>    m_aaEdgeContainerEDGE;
    AttachmentAccessor<Edge, AFaceContainer>    m_aaFaceContainerEDGE;
    AttachmentAccessor<Edge, AVolumeContainer>    m_aaVolumeContainerEDGE;
 
    AttachmentAccessor<Face, AEdgeContainer>    m_aaEdgeContainerFACE;
    AttachmentAccessor<Face, AFaceContainer>    m_aaFaceContainerFACE;
    AttachmentAccessor<Face, AVolumeContainer>    m_aaVolumeContainerFACE;
 
    AttachmentAccessor<Volume, AEdgeContainer>    m_aaEdgeContainerVOLUME;
    AttachmentAccessor<Volume, AFaceContainer>    m_aaFaceContainerVOLUME;
    AttachmentAccessor<Volume, AVolumeContainer>  m_aaVolumeContainerVOLUME;
    
  //  marks
    int m_currentMark;  // 0: marks inactive. -1: reset-marks (sets currentMark to 1)
    bool m_bMarking;
    AMark m_aMark;
    VertexAttachmentAccessor<AMark> m_aaMarkVRT;
    EdgeAttachmentAccessor<AMark> m_aaMarkEDGE;
    FaceAttachmentAccessor<AMark> m_aaMarkFACE;
    VolumeAttachmentAccessor<AMark> m_aaMarkVOL;
 
    SPMessageHub              m_messageHub;
    DistributedGridManager*   m_distGridMgr;
    PeriodicBoundaryManager*  m_periodicBndMgr;
};
 
}//end of namespace
 
#include "grid_impl.hpp"
 
#endif