MeshDistributor.cc

//
// Software License for AMDiS
//
// Copyright (c) 2010 Dresden University of Technology 
// All rights reserved.
// Authors: Simon Vey, Thomas Witkowski et al.
//
// This file is part of AMDiS
//
// See also license.opensource.txt in the distribution.


#include <algorithm>
#include <iostream>
#include <fstream>
#include <limits>
#include <stdint.h>
#include <boost/lexical_cast.hpp>
#include <boost/filesystem.hpp>

#include "parallel/MeshDistributor.h"
#include "parallel/MeshManipulation.h"
#include "parallel/ParallelDebug.h"
#include "parallel/StdMpi.h"
#include "parallel/MeshPartitioner.h"
#include "parallel/ParMetisPartitioner.h"
#include "parallel/ZoltanPartitioner.h"
#include "parallel/SimplePartitioner.h"
#include "parallel/MpiHelper.h"
#include "io/ElementFileWriter.h"
#include "io/MacroInfo.h"
#include "io/VtkWriter.h"
#include "Mesh.h"
#include "Traverse.h"
#include "ElInfo.h"
#include "Element.h"
#include "MacroElement.h"
#include "DOFMatrix.h"
#include "DOFVector.h"
#include "SystemVector.h"
#include "ElementDofIterator.h"
#include "ProblemStatBase.h"
#include "StandardProblemIteration.h"
#include "VertexVector.h"
#include "MeshStructure.h"
#include "ProblemVec.h"
#include "ProblemInstat.h"
#include "RefinementManager3d.h"
#include "Debug.h"

namespace AMDiS {

  using boost::lexical_cast;
  using namespace boost::filesystem;
  using namespace std;

  inline bool cmpDofsByValue(const DegreeOfFreedom* dof1, const DegreeOfFreedom* dof2)
  {
    return (*dof1 < *dof2);
  }


  MeshDistributor::MeshDistributor()
    : probStat(0),
      name("parallel"),
      feSpace(NULL),
      mesh(NULL),
      refineManager(NULL),
      info(10),
      partitioner(NULL),
      nRankDofs(0),
      nOverallDofs(0),
      rstart(0),
      deserialized(false),
      writeSerializationFile(false),
      repartitioningAllowed(false),
      repartitionIthChange(20),
      nMeshChangesAfterLastRepartitioning(0),
      repartitioningCounter(0),
      debugOutputDir(""),
      lastMeshChangeIndex(0)
  {
    FUNCNAME("MeshDistributor::ParalleDomainBase()");

    mpiRank = MPI::COMM_WORLD.Get_rank();
    mpiSize = MPI::COMM_WORLD.Get_size();
    mpiComm = MPI::COMM_WORLD;

    int tmp = 0;
    GET_PARAMETER(0, name + "->repartitioning", "%d", &tmp);
    repartitioningAllowed = (tmp > 0);

    GET_PARAMETER(0, name + "->debug output dir", &debugOutputDir);
    GET_PARAMETER(0, name + "->repartition ith change", "%d", &repartitionIthChange);

    tmp = 0;
    GET_PARAMETER(0, name + "->log main rank", "%d", &tmp);
    Msg::outputMainRank = (tmp > 0);

    string partStr = "parmetis";
    GET_PARAMETER(0, name + "->partitioner", &partStr);

    if (partStr == "parmetis") 
      partitioner = new ParMetisPartitioner(&mpiComm);

    if (partStr == "zoltan") {
#ifdef HAVE_ZOLTAN
      partitioner = new ZoltanPartitioner(&mpiComm);
#else
      ERROR_EXIT("AMDiS was compiled without Zoltan support. There you cannot make use of it!\n");
#endif
    }

    if (partStr == "simple")
      partitioner = new SimplePartitioner(&mpiComm);

    tmp = 0;
    GET_PARAMETER(0, name + "->box partitioning", "%d", &tmp);
    partitioner->setBoxPartitioning(static_cast<bool>(tmp));

    TEST_EXIT(partitioner)("Could not create partitioner \"%s\"!\n", partStr.c_str());
  }


  void MeshDistributor::initParallelization()
  {
    FUNCNAME("MeshDistributor::initParallelization()");

    TEST_EXIT(mpiSize > 1)
      ("Parallelization does not work with only one process!\n");

    TEST_EXIT(feSpace)("No FE space has been defined for the mesh distributor!\n");
    TEST_EXIT(mesh)("No mesh has been defined for the mesh distributor!\n");

#ifdef HAVE_ZOLTAN
    int a = 0;
    char *b = NULL;
    float zoltanVersion = 0.0;
    Zoltan_Initialize(a, &b, &zoltanVersion);
#endif

    elObjects.setFeSpace(feSpace);

    // If the problem has been already read from a file, we need only to set
    // isRankDofs to all matrices and rhs vector and to remove periodic 
    // boundary conditions (if there are some).
    if (deserialized) {
      updateMacroElementInfo();

      setRankDofs();

      removePeriodicBoundaryConditions();

      macroElIndexMap.clear();
      macroElIndexTypeMap.clear();

      for (vector<MacroElement*>::iterator it = allMacroElements.begin();
	   it != allMacroElements.end(); ++it) {
	macroElIndexMap[(*it)->getIndex()] = (*it)->getElement();
	macroElIndexTypeMap[(*it)->getIndex()] = (*it)->getElType();
      }

      return;
    }


    // Test, if the mesh is the macro mesh only! Paritioning of the mesh is supported
    // only for macro meshes, so it will not work yet if the mesh is already refined
    // in some way.
    testForMacroMesh();

    // For later mesh repartitioning, we need to store some information about the
    // macro mesh.
    createMacroElementInfo();

    // create an initial partitioning of the mesh
    partitioner->createInitialPartitioning();

    // set the element weights, which are 1 at the very first begin
    setInitialElementWeights();

    // and now partition the mesh    
    bool partitioningSucceed = partitioner->partition(elemWeights, INITIAL);
    TEST_EXIT(partitioningSucceed)("Initial partitioning does not work!\n");
    partitioner->createPartitionMap(partitionMap);


#if (DEBUG != 0)    
    debug::ElementIdxToDofs elMap;
    debug::createSortedDofs(mesh, elMap);
    if (mpiRank == 0) {
      int writePartMesh = 1;
      GET_PARAMETER(0, "dbg->write part mesh", "%d", &writePartMesh);

      if (writePartMesh > 0) {
	debug::writeElementIndexMesh(mesh, debugOutputDir + "elementIndex.vtu");
	ParallelDebug::writePartitioning(*this, debugOutputDir + "part.vtu");
      }
    }
#endif


    // === Create interior boundary information. ===

    createInteriorBoundaryInfo();

#if (DEBUG != 0)
    ParallelDebug::printBoundaryInfo(*this);
#endif

    for (deque<MacroElement*>::iterator it = mesh->firstMacroElement();
	 it != mesh->endOfMacroElements(); ++it) {
      for (int i = 0; i < mesh->getGeo(NEIGH); i++) {
	if ((*it)->getNeighbour(i) && 
	    mesh->isPeriodicAssociation((*it)->getBoundary(i))) {

	  int neighIndex = (*it)->getNeighbour(i)->getIndex();

	  (*it)->getNeighbour(i)->setNeighbour((*it)->getOppVertex(i), NULL);
	  (*it)->setNeighbour(i, NULL);
	  (*it)->setBoundary(i, 0);

	  macroElementNeighbours[(*it)->getIndex()][i] = -1;
	  macroElementNeighbours[neighIndex][(*it)->getOppVertex(i)] = -1;
	}
      }
    }

    for (vector<MacroElement*>::iterator it = allMacroElements.begin();
	 it != allMacroElements.end(); ++it) {
      for (int i = 0; i < mesh->getGeo(NEIGH); i++) {
	if ((*it)->getNeighbour(i) && 
	    mesh->isPeriodicAssociation((*it)->getBoundary(i))) {

	  int neighIndex = (*it)->getNeighbour(i)->getIndex();

	  (*it)->getNeighbour(i)->setNeighbour((*it)->getOppVertex(i), NULL);
	  (*it)->setNeighbour(i, NULL);
	  (*it)->setBoundary(i, 0);

	  macroElementNeighbours[(*it)->getIndex()][i] = -1;
	  macroElementNeighbours[neighIndex][(*it)->getOppVertex(i)] = -1;
	}
      }
    }

    // === Remove all macro elements that are not part of the rank partition. ===

    removeMacroElements();

    // === Create new global and local DOF numbering. ===


    // We have to remove the VertexVectors, which contain periodic assoiciations, 
    // because they are not valid anymore after some macro elements have been removed
    // and the corresponding DOFs were deleted.
    for (map<BoundaryType, VertexVector*>::iterator it = mesh->getPeriodicAssociations().begin();
	 it != mesh->getPeriodicAssociations().end(); ++it)
      const_cast<DOFAdmin&>(mesh->getDofAdmin(0)).removeDOFContainer(dynamic_cast<DOFContainer*>(it->second));

    updateLocalGlobalNumbering();

    // === In 3D we have to make some test, if the resulting mesh is valid. If   ===
    // === it is not valid, there is no possiblity yet to fix this problem, just ===
    // === exit with an error message.                                           ===
    
    check3dValidMesh();

    // === If in debug mode, make some tests. ===

#if (DEBUG != 0)
    MSG("AMDiS runs in debug mode, so make some test ...\n");

    ParallelDebug::testAllElements(*this);
    debug::testSortedDofs(mesh, elMap);
    ParallelDebug::testInteriorBoundary(*this);

    debug::writeMesh(feSpace, -1, debugOutputDir + "macro_mesh");   

    MSG("Debug mode tests finished!\n");
#endif

    // === Create periodic DOF mapping, if there are periodic boundaries. ===

    createPeriodicMap();

#if (DEBUG != 0)
    ParallelDebug::testPeriodicBoundary(*this);
#endif

    // === Global refinements. ===
    
    int globalRefinement = 0;
    GET_PARAMETER(0, mesh->getName() + "->global refinements", "%d", &globalRefinement);
    
    if (globalRefinement > 0) {
      refineManager->globalRefine(mesh, globalRefinement);

      updateLocalGlobalNumbering();

     
      // === Update periodic mapping, if there are periodic boundaries. ===     

      createPeriodicMap();

#if (DEBUG != 0)
    ParallelDebug::testPeriodicBoundary(*this);
#endif
    }


    /// === Set DOF rank information to all matrices and vectors. ===

    setRankDofs();


    // === Remove periodic boundary conditions in sequential problem definition. ===

    removePeriodicBoundaryConditions();
  }


  void MeshDistributor::addProblemStat(ProblemVec *probVec)
  {
    FUNCNAME("MeshDistributor::addProblemVec()");

    if (feSpace != NULL) {
      vector<FiniteElemSpace*> feSpaces = probVec->getFeSpaces();
      for (unsigned int i = 0; i < feSpaces.size(); i++) {
	TEST_EXIT(feSpace == feSpaces[i])
	  ("Parallelizaton is not supported for multiple FE spaces!\n");
      }
    } else {
      feSpace = probVec->getFeSpace(0);
      mesh = feSpace->getMesh();
      info = probVec->getInfo();
      
      TEST_EXIT(mesh->getNumberOfDOFAdmin() == 1)
	("Only meshes with one DOFAdmin are supported!\n");
      TEST_EXIT(mesh->getDofAdmin(0).getNumberOfPreDofs(VERTEX) == 0)
	("Wrong pre dof number for DOFAdmin!\n");
      
      switch (mesh->getDim()) {
      case 2:
	refineManager = new RefinementManager2d();
	break;
      case 3:
	refineManager = new RefinementManager3d();
	break;
      default:
	ERROR_EXIT("This should not happen for dim = %d!\n", mesh->getDim());
      }

      partitioner->setMesh(mesh);
    }

    // Create parallel serialization file writer, if needed.
    int writeSerialization = 0;
    GET_PARAMETER(0, probVec->getName() + "->output->write serialization", "%d", 
		  &writeSerialization);
    if (writeSerialization && !writeSerializationFile) {
      string filename = "";
      GET_PARAMETER(0, name + "->output->serialization filename", &filename);
      
      TEST_EXIT(filename != "")
	("No filename defined for parallel serialization file!\n");

      int tsModulo = -1;
      GET_PARAMETER(0, probVec->getName() + "->output->write every i-th timestep", 
		    "%d", &tsModulo);
      
      probVec->getFileWriterList().push_back(new Serializer<MeshDistributor>(this, filename, tsModulo));
      writeSerializationFile = true;
    }    

    int readSerialization = 0;
    GET_PARAMETER(0, probVec->getName() + "->input->read serialization", "%d", 
		  &readSerialization);
    if (readSerialization) {
      string filename = "";
      GET_PARAMETER(0, probVec->getName() + "->input->serialization filename", &filename);
      filename += ".p" + lexical_cast<string>(mpiRank);
      MSG("Start deserialization with %s\n", filename.c_str());
      ifstream in(filename.c_str());

      TEST_EXIT(!in.fail())("Could not open deserialization file: %s\n",
			    filename.c_str());

      probVec->deserialize(in);
      in.close();
      MSG("Deserialization from file: %s\n", filename.c_str());

      filename = "";
      GET_PARAMETER(0, name + "->input->serialization filename", &filename);
      
      TEST_EXIT(filename != "")
	("No filename defined for parallel deserialization file!\n");
      
      string rankFilename = filename + ".p" + lexical_cast<string>(mpiRank);
      in.open(rankFilename.c_str());
      
      TEST_EXIT(!in.fail())("Could not open parallel deserialization file: %s\n",
			    filename.c_str());
      
      deserialize(in);
      in.close();
      MSG("Deserializtion of mesh distributor from file: %s\n", rankFilename.c_str());
      deserialized = true;
    }

    probStat.push_back(probVec);
  }


  void MeshDistributor::exitParallelization()
  {}

  
  void MeshDistributor::testForMacroMesh()
  {
    FUNCNAME("MeshDistributor::testForMacroMesh()");

    int nMacroElements = 0;

    TraverseStack stack;
    ElInfo *elInfo = stack.traverseFirst(mesh, -1, Mesh::CALL_LEAF_EL);
    while (elInfo) {
      TEST_EXIT(elInfo->getLevel() == 0)
	("Mesh is already refined! This does not work with parallelization!\n");

      TEST_EXIT(elInfo->getType() == 0)
	("Only macro elements with level 0 are supported!\n");
      
      nMacroElements++;

      elInfo = stack.traverseNext(elInfo);
    }

    TEST_EXIT(nMacroElements >= mpiSize)
      ("The mesh has less macro elements than number of mpi processes!\n");
  }


  void MeshDistributor::synchVector(DOFVector<double> &vec)
  {
    StdMpi<vector<double> > stdMpi(mpiComm);

    for (RankToDofContainer::iterator sendIt = sendDofs.begin();
	 sendIt != sendDofs.end(); ++sendIt) {
      vector<double> dofs;
      int nSendDofs = sendIt->second.size();
      dofs.reserve(nSendDofs);
      
      for (int i = 0; i < nSendDofs; i++)
	dofs.push_back(vec[*((sendIt->second)[i])]);

      stdMpi.send(sendIt->first, dofs);
    }

    for (RankToDofContainer::iterator recvIt = recvDofs.begin();
	 recvIt != recvDofs.end(); ++recvIt)
      stdMpi.recv(recvIt->first, recvIt->second.size());

    stdMpi.startCommunication();

    for (RankToDofContainer::iterator recvIt = recvDofs.begin();
	 recvIt != recvDofs.end(); ++recvIt)
      for (unsigned int i = 0; i < recvIt->second.size(); i++)
	vec[*(recvIt->second)[i]] = stdMpi.getRecvData(recvIt->first)[i];
  }


  void MeshDistributor::synchVector(SystemVector &vec)
  {
    int nComponents = vec.getSize();
    StdMpi<vector<double> > stdMpi(mpiComm);

    for (RankToDofContainer::iterator sendIt = sendDofs.begin();
	 sendIt != sendDofs.end(); ++sendIt) {
      vector<double> dofs;
      int nSendDofs = sendIt->second.size();
      dofs.reserve(nComponents * nSendDofs);
      
      for (int i = 0; i < nComponents; i++) {
	DOFVector<double> *dofvec = vec.getDOFVector(i);
	for (int j = 0; j < nSendDofs; j++)
	  dofs.push_back((*dofvec)[*((sendIt->second)[j])]);
      }

      stdMpi.send(sendIt->first, dofs);
    }

    for (RankToDofContainer::iterator recvIt = recvDofs.begin();
	 recvIt != recvDofs.end(); ++recvIt)
      stdMpi.recv(recvIt->first, recvIt->second.size() * nComponents);

    stdMpi.startCommunication();

    for (RankToDofContainer::iterator recvIt = recvDofs.begin();
	 recvIt != recvDofs.end(); ++recvIt) {
      int nRecvDofs = recvIt->second.size();

      int counter = 0;
      for (int i = 0; i < nComponents; i++) {
	DOFVector<double> *dofvec = vec.getDOFVector(i);
 	for (int j = 0; j < nRecvDofs; j++)
	  (*dofvec)[*(recvIt->second)[j]] = 
	    stdMpi.getRecvData(recvIt->first)[counter++];
      }
    }
  }


  void MeshDistributor::check3dValidMesh()
  {
    FUNCNAME("MeshDistributor::check3dValidMesh()");

    if (mesh->getDim() != 3)
      return;

    std::set<DofEdge> allEdges;
    std::set<int> rankMacroEls;

    TraverseStack stack;
    ElInfo *elInfo = stack.traverseFirst(mesh, 0, Mesh::CALL_EL_LEVEL);
    while (elInfo) {
      for (int i = 0; i < 4; i++) {
	ElementObjectData elData(elInfo->getElement()->getIndex(), i);
	allEdges.insert(elObjects.getEdgeLocalMap(elData));
      }

      rankMacroEls.insert(elInfo->getElement()->getIndex());

      elInfo = stack.traverseNext(elInfo);
    }


    FixRefinementPatch::connectedEdges.clear();

    for (std::set<DofEdge>::iterator it = allEdges.begin(); it != allEdges.end(); ++it) {
      vector<ElementObjectData>& edgeEls = elObjects.getElements(*it);

      TEST_EXIT_DBG(edgeEls.size() > 0)
	("No edge %d/%d in elObjDB!\n", it->first, it->second);

      std::set<int> el0, el1;
      std::map<int, int> edgeNoInEl;

      for (unsigned int i = 0; i < edgeEls.size(); i++) {
	if (rankMacroEls.count(edgeEls[i].elIndex)) {
	  if (el0.empty())
	    el0.insert(edgeEls[i].elIndex);
	  else
	    el1.insert(edgeEls[i].elIndex);

	  edgeNoInEl[edgeEls[i].elIndex] = edgeEls[i].ithObject;
	}
      }
            
      TEST_EXIT_DBG(!el0.empty())("Should not happen!\n");

      if (el1.empty())
	continue;
      
      bool found = false;      
      do {
	found = false;
	for (std::set<int>::iterator elIt = el0.begin(); elIt != el0.end(); ++elIt) {
	  for (int i = 0; i < 4; i++) {
	    int neighEl = macroElementNeighbours[*elIt][i];
	    if (neighEl != -1 && el1.count(neighEl)) {
	      el0.insert(neighEl);
	      el1.erase(neighEl);
	      found = true;
	    }
	  }
	  
	  if (found)
	    break;
	}
      } while (found);
      
      if (!el1.empty()) {
	MSG("Unvalid 3D mesh with %d (%d - %d) elements on this edge!\n", 
	    edgeEls.size(), el0.size(), el1.size());

	for (std::set<int>::iterator elIt0 = el0.begin(); elIt0 != el0.end(); ++elIt0) {
	  for (std::set<int>::iterator elIt1 = el1.begin(); elIt1 != el1.end(); ++elIt1) {

	    TEST_EXIT_DBG(macroElIndexMap.count(*elIt0))("Should not happen!\n");
	    TEST_EXIT_DBG(macroElIndexMap.count(*elIt1))("Should not happen!\n");
	    TEST_EXIT_DBG(edgeNoInEl.count(*elIt0))("Should not happen!\n");
	    TEST_EXIT_DBG(edgeNoInEl.count(*elIt1))("Should not happen!\n");

	    pair<Element*, int> edge0 = 
	      make_pair(macroElIndexMap[*elIt0], edgeNoInEl[*elIt0]);
	    pair<Element*, int> edge1 = 
	      make_pair(macroElIndexMap[*elIt1], edgeNoInEl[*elIt1]);

	    DofEdge dofEdge0 = edge0.first->getEdge(edge0.second);
	    DofEdge dofEdge1 = edge1.first->getEdge(edge1.second);

	    WorldVector<double> c0, c1;
	    mesh->getDofIndexCoords(dofEdge0.first, feSpace, c0);
	    mesh->getDofIndexCoords(dofEdge0.second, feSpace, c1);

	    MSG("FOUND EDGE: %d %d with coords %f %f %f   %f %f %f\n",
		dofEdge0.first, dofEdge0.second, 
		c0[0], c0[1], c0[2],
		c1[0], c1[1], c1[2]);

	    TEST_EXIT_DBG(dofEdge0 == dofEdge1)("Should noth happen!\n");

	    FixRefinementPatch::connectedEdges.push_back(make_pair(edge0, edge1));
	    FixRefinementPatch::connectedEdges.push_back(make_pair(edge1, edge0));
	  }
	}
      }
    }
  }


  void MeshDistributor::setRankDofs()
  {
    for (unsigned int i = 0; i < probStat.size(); i++) {
      int nComponents = probStat[i]->getNumComponents();
      for (int j = 0; j < nComponents; j++) {
	for (int k = 0; k < nComponents; k++)
	  if (probStat[i]->getSystemMatrix(j, k))
	    probStat[i]->getSystemMatrix(j, k)->setRankDofs(isRankDof);

	TEST_EXIT_DBG(probStat[i]->getRhs()->getDOFVector(j))("No RHS vector!\n");
	TEST_EXIT_DBG(probStat[i]->getSolution()->getDOFVector(j))("No solution vector!\n");
	
	probStat[i]->getRhs()->getDOFVector(j)->setRankDofs(isRankDof);
	probStat[i]->getSolution()->getDOFVector(j)->setRankDofs(isRankDof);
      }
    }
  }


  void MeshDistributor::removePeriodicBoundaryConditions()
  {
    FUNCNAME("MeshDistributor::removePeriodicBoundaryConditions()");

    // Remove periodic boundaries in boundary manager on matrices and vectors.
    for (unsigned int i = 0; i < probStat.size(); i++) {
      int nComponents = probStat[i]->getNumComponents();

      for (int j = 0; j < nComponents; j++) {
	for (int k = 0; k < nComponents; k++) {
	  DOFMatrix* mat = probStat[i]->getSystemMatrix(j, k);
	  if (mat && mat->getBoundaryManager())
	    removePeriodicBoundaryConditions(const_cast<BoundaryIndexMap&>(mat->getBoundaryManager()->getBoundaryConditionMap()));
	}
	
	if (probStat[i]->getSolution()->getDOFVector(j)->getBoundaryManager())
	  removePeriodicBoundaryConditions(const_cast<BoundaryIndexMap&>(probStat[i]->getSolution()->getDOFVector(j)->getBoundaryManager()->getBoundaryConditionMap()));
	
	if (probStat[i]->getRhs()->getDOFVector(j)->getBoundaryManager())
	  removePeriodicBoundaryConditions(const_cast<BoundaryIndexMap&>(probStat[i]->getRhs()->getDOFVector(j)->getBoundaryManager()->getBoundaryConditionMap()));
      }
    }

    // Remove periodic boundaries on elements in mesh.
    TraverseStack stack;
    ElInfo *elInfo = stack.traverseFirst(mesh,  -1, Mesh::CALL_EVERY_EL_PREORDER);
    while (elInfo) {
      elInfo->getElement()->deleteElementData(PERIODIC);
      elInfo = stack.traverseNext(elInfo);
    }    

    // Remove periodic vertex associations
    mesh->getPeriodicAssociations().clear();
  }


  void MeshDistributor::removePeriodicBoundaryConditions(BoundaryIndexMap& boundaryMap)
  {
    BoundaryIndexMap::iterator it = boundaryMap.begin();
    while (it != boundaryMap.end()) {
      if (it->second->isPeriodic())
	boundaryMap.erase(it++);
      else
	++it;      
    }    
  }


  void MeshDistributor::checkMeshChange(bool tryRepartition)
  {
    FUNCNAME("MeshDistributor::checkMeshChange()");

    double first = MPI::Wtime();

    // === If mesh has not been changed on all ranks, return. ===

    int recvAllValues = 0;
    int sendValue = static_cast<int>(mesh->getChangeIndex() != lastMeshChangeIndex);
    mpiComm.Allreduce(&sendValue, &recvAllValues, 1, MPI_INT, MPI_SUM);

    if (recvAllValues == 0)
      return;

    // === At least one rank mesh has been changed, so the boundaries must be ===
    // === adapted to the new mesh structure.                                 ===
   
    do {
      bool meshChanged = false;

      // To check the interior boundaries, the ownership of the boundaries is not 
      // important. Therefore, we add all boundaries to one boundary container.
      RankToBoundMap allBound;

      for (InteriorBoundary::iterator it(myIntBoundary); !it.end(); ++it)
	if ((mesh->getDim() == 2 && it->rankObj.subObj == EDGE) || 
	    (mesh->getDim() == 3 && it->rankObj.subObj == FACE))
 	  allBound[it.getRank()].push_back(*it);

      for (InteriorBoundary::iterator it(otherIntBoundary); !it.end(); ++it)
	if ((mesh->getDim() == 2 && it->rankObj.subObj == EDGE) || 
	    (mesh->getDim() == 3 && it->rankObj.subObj == FACE))
	  allBound[it.getRank()].push_back(*it);

      for (InteriorBoundary::iterator it(periodicBoundary); !it.end(); ++it) {
	if (it.getRank() == mpiRank) {
	  if ((mesh->getDim() == 2 && it->rankObj.subObj == EDGE) || 
	      (mesh->getDim() == 3 && it->rankObj.subObj == FACE)) {
	    MeshStructure elCode;
	    elCode.init(it->rankObj);
	    
	    MeshManipulation mm(feSpace);
	    meshChanged |= mm.fitElementToMeshCode(elCode, it->neighObj);
	  }
	} else {
	  if ((mesh->getDim() == 2 && it->rankObj.subObj == EDGE) || 
	      (mesh->getDim() == 3 && it->rankObj.subObj == FACE))
	    allBound[it.getRank()].push_back(*it);	
	}
      }


      // === Check the boundaries and adapt mesh if necessary. ===
#if (DEBUG != 0)
      MSG("Run checkAndAdaptBoundary ...\n");
#endif

      meshChanged |= checkAndAdaptBoundary(allBound);

      // === Check on all ranks if at least one rank's mesh has changed. ===

      int sendValue = static_cast<int>(meshChanged);
      recvAllValues = 0;
      mpiComm.Allreduce(&sendValue, &recvAllValues, 1, MPI_INT, MPI_SUM);

      MSG("Mesh changed on %d ranks!\n", recvAllValues);
    } while (recvAllValues != 0);

#if (DEBUG != 0)
    debug::writeMesh(feSpace, -1, debugOutputDir + "mesh");
#endif


    // === Because the mesh has been changed, update the DOF numbering and mappings. ===

    updateLocalGlobalNumbering();


    // === Update periodic mapping, if there are periodic boundaries. ===

    createPeriodicMap();

#if (DEBUG != 0)
    ParallelDebug::testPeriodicBoundary(*this);
#endif


    // === The mesh has changed, so check if it is required to repartition the mesh. ===

    nMeshChangesAfterLastRepartitioning++;


    INFO(info, 8)("Parallel mesh adaption needed %.5f seconds\n", 
		  MPI::Wtime() - first);

    if (tryRepartition &&
	repartitioningAllowed && 
	nMeshChangesAfterLastRepartitioning >= repartitionIthChange) {
      repartitionMesh();
      nMeshChangesAfterLastRepartitioning = 0;
    }

    // === Print imbalance factor. ===

    vector<int> nDofsInRank(mpiSize);
    int nDofs = mesh->getDofAdmin(0).getUsedDofs();
    mpiComm.Gather(&nDofs, 1, MPI_INT, &(nDofsInRank[0]), 1, MPI_INT, 0);

    if (mpiRank == 0) {
      int nOverallDofs = 0;
      int maxDofs = numeric_limits<int>::min();
      for (int i = 0; i < mpiSize; i++) {
	nOverallDofs += nDofsInRank[i];
	maxDofs = std::max(maxDofs, nDofsInRank[i]);
      }      
      int avrgDofs = nOverallDofs / mpiSize;
      double imbalance = (static_cast<double>(maxDofs - avrgDofs) /  avrgDofs) * 100.0;

      MSG("Imbalancing factor: %.1f\%\n", imbalance);
    }
  }

  
  bool MeshDistributor::checkAndAdaptBoundary(RankToBoundMap &allBound)
  {
    FUNCNAME("MeshDistributor::checkAndAdaptBoundary()");

    // === Create mesh structure codes for all ranks boundary elements. ===
       
    map<int, MeshCodeVec> sendCodes;
   
    for (RankToBoundMap::iterator it = allBound.begin(); it != allBound.end(); ++it) {

      for (vector<AtomicBoundary>::iterator boundIt = it->second.begin();
	   boundIt != it->second.end(); ++boundIt) {
	MeshStructure elCode;
	elCode.init(boundIt->rankObj);
	sendCodes[it->first].push_back(elCode);
      }
    }

    StdMpi<MeshCodeVec> stdMpi(mpiComm, true);
    stdMpi.send(sendCodes);
    for (RankToBoundMap::iterator it = allBound.begin(); it != allBound.end(); ++it)
      stdMpi.recv(it->first);
    stdMpi.startCommunication();
 
    // === Compare received mesh structure codes. ===
    
    bool meshChanged = false;

    for (RankToBoundMap::iterator it = allBound.begin(); it != allBound.end(); ++it) {
     
      MeshCodeVec &recvCodes = stdMpi.getRecvData()[it->first];
      int i = 0;
      
      for (vector<AtomicBoundary>::iterator boundIt = it->second.begin();
	   boundIt != it->second.end(); ++boundIt, i++) {

	MeshStructure elCode;	
	elCode.init(boundIt->rankObj);

	if (elCode.getCode() != recvCodes[i].getCode()) {
	  TEST_EXIT_DBG(refineManager)("Refinement manager is not set correctly!\n");

	  MeshManipulation mm(feSpace);
	  meshChanged |= mm.fitElementToMeshCode(recvCodes[i], boundIt->rankObj);
 	}
      }
    }

    return meshChanged;
  }


  void MeshDistributor::serialize(ostream &out, DofContainer &data)
  {    
    int vecSize = data.size();
    SerUtil::serialize(out, vecSize);
    for (int i = 0; i < vecSize; i++) {
      int dofIndex = *(data[i]);
      SerUtil::serialize(out, dofIndex);
    }
  }


  void MeshDistributor::deserialize(istream &in, DofContainer &data,
				    map<int, const DegreeOfFreedom*> &dofMap)
  {
    FUNCNAME("MeshDistributor::deserialize()");

    int vecSize = 0;
    SerUtil::deserialize(in, vecSize);
    data.clear();
    data.resize(vecSize);
    for (int i = 0; i < vecSize; i++) {
      int dofIndex = 0;
      SerUtil::deserialize(in, dofIndex);

      TEST_EXIT_DBG(dofMap.count(dofIndex) != 0)
	("Dof index could not be deserialized correctly!\n");

      data[i] = dofMap[dofIndex];
    }
  }


  void MeshDistributor::serialize(ostream &out, RankToDofContainer &data)
  {
    int mapSize = data.size();
    SerUtil::serialize(out, mapSize);
    for (RankToDofContainer::iterator it = data.begin(); it != data.end(); ++it) {
      int rank = it->first;
      SerUtil::serialize(out, rank);
      serialize(out, it->second);
    }
  }

  
  void MeshDistributor::deserialize(istream &in, RankToDofContainer &data,
				    map<int, const DegreeOfFreedom*> &dofMap)
  {
    data.clear();

    int mapSize = 0;
    SerUtil::deserialize(in, mapSize);
    for (int i = 0; i < mapSize; i++) {
      int rank = 0;
      SerUtil::deserialize(in, rank);
      deserialize(in, data[rank], dofMap);      
    }
  }


  void MeshDistributor::setInitialElementWeights() 
  {
    FUNCNAME("MeshDistributor::setInitialElementWeights()");

    elemWeights.clear();