Extract refinement scaffolding into separate units

12 files changed, 908 insertions, 0 deletions

diff --git a/src/olb2D.h b/src/olb2D.h
index 1f2caa1..a5d72df 100644
--- a/src/olb2D.h
+++ b/src/olb2D.h
@@ -7,3 +7,4 @@
 #include <io/io2D.h>
 #include <utilities/utilities2D.h>
 #include <particles/hlbm/hlbmDynamics2D.h>
+#include <refinement/refinement2D.h>
diff --git a/src/olb2D.hh b/src/olb2D.hh
index 481ab5b..77189a9 100644
--- a/src/olb2D.hh
+++ b/src/olb2D.hh
@@ -7,3 +7,4 @@
 #include <io/io2D.hh>
 #include <utilities/utilities2D.hh>
 #include <particles/hlbm/hlbmDynamics2D.hh>
+#include <refinement/refinement2D.hh>
diff --git a/src/refinement/MakeHeader b/src/refinement/MakeHeader
new file mode 100644
index 0000000..bfcbf33
--- /dev/null
+++ b/src/refinement/MakeHeader
@@ -0,0 +1,27 @@
+#  This file is part of the OpenLB library
+#
+#  Copyright (C) 2019 Adrian Kummerländer
+#  E-mail contact: info@openlb.net
+#  The most recent release of OpenLB can be downloaded at
+#  <http://www.openlb.net/>
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  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 General Public License for more details.
+#
+#  You should have received a copy of the GNU General Public
+#  License along with this program; if not, write to the Free
+#  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+#  Boston, MA  02110-1301, USA.
+
+
+generic        :=
+
+precompiled    := grid2D \
+                  coupler2D
diff --git a/src/refinement/coupler2D.cpp b/src/refinement/coupler2D.cpp
new file mode 100644
index 0000000..37997f5
--- /dev/null
+++ b/src/refinement/coupler2D.cpp
@@ -0,0 +1,36 @@
+/*  This file is part of the OpenLB library
+ *
+ *  Copyright (C) 2019 Adrian Kummerländer
+ *  E-mail contact: info@openlb.net
+ *  The most recent release of OpenLB can be downloaded at
+ *  <http://www.openlb.net/>
+ *
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU General Public License
+ *  as published by the Free Software Foundation; either version 2
+ *  of the License, or (at your option) any later version.
+ *
+ *  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 General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public
+ *  License along with this program; if not, write to the Free
+ *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ *  Boston, MA  02110-1301, USA.
+ */
+
+#include "coupler2D.h"
+#include "coupler2D.hh"
+
+#include "dynamics/latticeDescriptors.h"
+#include "dynamics/latticeDescriptors.hh"
+
+namespace olb {
+
+template class Coupler2D<double,descriptors::D2Q9Descriptor>;
+template class FineCoupler2D<double,descriptors::D2Q9Descriptor>;
+template class CoarseCoupler2D<double,descriptors::D2Q9Descriptor>;
+
+}
diff --git a/src/refinement/coupler2D.h b/src/refinement/coupler2D.h
new file mode 100644
index 0000000..b218eff
--- /dev/null
+++ b/src/refinement/coupler2D.h
@@ -0,0 +1,85 @@
+/*  This file is part of the OpenLB library
+ *
+ *  Copyright (C) 2019 Adrian Kummerländer
+ *  E-mail contact: info@openlb.net
+ *  The most recent release of OpenLB can be downloaded at
+ *  <http://www.openlb.net/>
+ *
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU General Public License
+ *  as published by the Free Software Foundation; either version 2
+ *  of the License, or (at your option) any later version.
+ *
+ *  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 General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public
+ *  License along with this program; if not, write to the Free
+ *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ *  Boston, MA  02110-1301, USA.
+*/
+
+#ifndef REFINEMENT_COUPLER_2D_H
+#define REFINEMENT_COUPLER_2D_H
+
+#include "grid2D.h"
+
+namespace olb {
+
+
+template <typename T, template<typename> class DESCRIPTOR>
+class Coupler2D {
+protected:
+  Grid2D<T,DESCRIPTOR>& _coarse;
+  Grid2D<T,DESCRIPTOR>& _fine;
+
+  const int  _coarseSize;
+  const int  _fineSize;
+  const bool _vertical;
+
+  Vector<T,2>   _physOrigin;
+  Vector<int,3> _coarseOrigin;
+  Vector<int,3> _fineOrigin;
+
+  Vector<int,3> getFineLatticeR(int y) const;
+  Vector<int,3> getCoarseLatticeR(int y) const;
+
+public:
+  Coupler2D(Grid2D<T,DESCRIPTOR>& coarse, Grid2D<T,DESCRIPTOR>& fine,
+            Vector<T,2> origin, Vector<T,2> extend);
+
+};
+
+template <typename T, template<typename> class DESCRIPTOR>
+class FineCoupler2D : public Coupler2D<T,DESCRIPTOR> {
+private:
+  std::vector<T>           _c2f_rho;
+  std::vector<Vector<T,2>> _c2f_u;
+  std::vector<Vector<T,DESCRIPTOR<T>::q>> _c2f_fneq;
+
+public:
+  FineCoupler2D(Grid2D<T,DESCRIPTOR>& coarse, Grid2D<T,DESCRIPTOR>& fine,
+                Vector<T,2> origin, Vector<T,2> extend);
+
+  void store();
+  void interpolate();
+  void couple();
+
+};
+
+template <typename T, template<typename> class DESCRIPTOR>
+class CoarseCoupler2D : public Coupler2D<T,DESCRIPTOR> {
+public:
+  CoarseCoupler2D(Grid2D<T,DESCRIPTOR>& coarse, Grid2D<T,DESCRIPTOR>& fine,
+                  Vector<T,2> origin, Vector<T,2> extend);
+
+  void couple();
+
+};
+
+
+}
+
+#endif
diff --git a/src/refinement/coupler2D.hh b/src/refinement/coupler2D.hh
new file mode 100644
index 0000000..49efe57
--- /dev/null
+++ b/src/refinement/coupler2D.hh
@@ -0,0 +1,348 @@
+/*  This file is part of the OpenLB library
+ *
+ *  Copyright (C) 2019 Adrian Kummerländer
+ *  E-mail contact: info@openlb.net
+ *  The most recent release of OpenLB can be downloaded at
+ *  <http://www.openlb.net/>
+ *
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU General Public License
+ *  as published by the Free Software Foundation; either version 2
+ *  of the License, or (at your option) any later version.
+ *
+ *  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 General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public
+ *  License along with this program; if not, write to the Free
+ *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ *  Boston, MA  02110-1301, USA.
+*/
+
+#ifndef REFINEMENT_COUPLER_2D_HH
+#define REFINEMENT_COUPLER_2D_HH
+
+#include "coupler2D.h"
+
+#include "dynamics/lbHelpers.h"
+
+namespace olb {
+
+
+template <typename T, template<typename> class DESCRIPTOR>
+void computeFeq(const Cell<T,DESCRIPTOR>& cell, T fEq[DESCRIPTOR<T>::q])
+{
+  T rho{};
+  T u[2] {};
+  cell.computeRhoU(rho, u);
+  const T uSqr = u[0]*u[0] + u[1]*u[1];
+  for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+    fEq[iPop] = lbHelpers<T,DESCRIPTOR>::equilibrium(iPop, rho, u, uSqr);
+  }
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+void computeFneq(const Cell<T,DESCRIPTOR>& cell, T fNeq[DESCRIPTOR<T>::q])
+{
+  T rho{};
+  T u[2] {};
+  cell.computeRhoU(rho, u);
+  lbHelpers<T,DESCRIPTOR>::computeFneq(cell, fNeq, rho, u);
+}
+
+template <typename T>
+T order4interpolation(T fm3, T fm1, T f1, T f3)
+{
+  return 9./16. * (fm1 + f1) - 1./16. * (fm3 + f3);
+}
+
+template <typename T>
+T order3interpolation(T fm1, T f1, T f3)
+{
+  return 3./8. * fm1 + 3./4. * f1 - 1./8. * f3;
+}
+
+template <typename T>
+T order2interpolation(T f0, T f1)
+{
+  return 0.5 * (f0 + f1);
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+void computeRestrictedFneq(const SuperLattice2D<T,DESCRIPTOR>& lattice, Vector<int,3> pos, T restrictedFneq[DESCRIPTOR<T>::q])
+{
+  for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+    T fNeq[DESCRIPTOR<T>::q] {};
+    computeFneq(lattice.get(pos[0], pos[1] + DESCRIPTOR<T>::c[iPop][0], pos[2] + DESCRIPTOR<T>::c[iPop][1]), fNeq);
+
+    for (int jPop=0; jPop < DESCRIPTOR<T>::q; ++jPop) {
+      restrictedFneq[jPop] += fNeq[jPop];
+    }
+  }
+
+  for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+    restrictedFneq[iPop] /= DESCRIPTOR<T>::q;
+  }
+}
+
+
+template <typename T, template<typename> class DESCRIPTOR>
+Vector<int,3> Coupler2D<T,DESCRIPTOR>::getFineLatticeR(int y) const
+{
+  if (_vertical) {
+    return _fineOrigin + Vector<int,3> {0, 0, y};
+  }
+  else {
+    return _fineOrigin + Vector<int,3> {0, y, 0};
+  }
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+Vector<int,3> Coupler2D<T,DESCRIPTOR>::getCoarseLatticeR(int y) const
+{
+  if (_vertical) {
+    return _coarseOrigin + Vector<int,3> {0, 0, y};
+  }
+  else {
+    return _coarseOrigin + Vector<int,3> {0, y, 0};
+  }
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+Coupler2D<T,DESCRIPTOR>::Coupler2D(Grid2D<T,DESCRIPTOR>& coarse, Grid2D<T,DESCRIPTOR>& fine,
+                                   Vector<T,2> origin, Vector<T,2> extend):
+  _coarse(coarse),
+  _fine(fine),
+  _coarseSize(floor(extend.norm() / coarse.getConverter().getPhysDeltaX() + 0.5)+1),
+  _fineSize(2*_coarseSize-1),
+  _vertical(util::nearZero(extend[0]))
+{
+  OLB_ASSERT(util::nearZero(extend[0]) || util::nearZero(extend[1]), "Coupling is only implemented alongside unit vectors");
+
+  const auto& coarseGeometry = _coarse.getCuboidGeometry();
+  const auto& fineGeometry   = _fine.getCuboidGeometry();
+
+  Vector<int,3> tmpLatticeOrigin{};
+  coarseGeometry.getLatticeR(origin, tmpLatticeOrigin);
+  _physOrigin = coarseGeometry.getPhysR(tmpLatticeOrigin.toStdVector());
+
+  coarseGeometry.getLatticeR(_physOrigin, _coarseOrigin);
+  fineGeometry.getLatticeR(_physOrigin, _fineOrigin);
+}
+
+
+template <typename T, template<typename> class DESCRIPTOR>
+FineCoupler2D<T,DESCRIPTOR>::FineCoupler2D(Grid2D<T,DESCRIPTOR>& coarse, Grid2D<T,DESCRIPTOR>& fine,
+    Vector<T,2> origin, Vector<T,2> extend):
+  Coupler2D<T,DESCRIPTOR>(coarse, fine, origin, extend),
+  _c2f_rho(this->_coarseSize),
+  _c2f_u(this->_coarseSize, Vector<T,2>(T{})),
+  _c2f_fneq(this->_coarseSize, Vector<T,DESCRIPTOR<T>::q>(T{}))
+{
+  OstreamManager clout(std::cout,"C2F");
+  clout << "coarse origin: " << this->_coarseOrigin[0] << " " << this->_coarseOrigin[1] << " " << this->_coarseOrigin[2] << std::endl;
+  clout << "fine origin:   " << this->_fineOrigin[0] << " " << this->_fineOrigin[1] << " " << this->_fineOrigin[2] << std::endl;
+  clout << "fine size:   " << this->_fineSize << std::endl;
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+void FineCoupler2D<T,DESCRIPTOR>::store()
+{
+  auto& coarseLattice = this->_coarse.getSuperLattice();
+
+  for (int y=0; y < this->_coarseSize; ++y) {
+    const auto pos = this->getCoarseLatticeR(y);
+
+    T rho{};
+    T u[2] {};
+    T fNeq[DESCRIPTOR<T>::q] {};
+    coarseLattice.get(pos).computeRhoU(rho, u);
+    computeFneq(coarseLattice.get(pos), fNeq);
+
+    _c2f_rho[y]  = rho;
+    _c2f_u[y]    = Vector<T,2>(u);
+    _c2f_fneq[y] = Vector<T,DESCRIPTOR<T>::q>(fNeq);
+  }
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+void FineCoupler2D<T,DESCRIPTOR>::interpolate()
+{
+  auto& coarseLattice = this->_coarse.getSuperLattice();
+
+  for (int y=0; y < this->_coarseSize; ++y) {
+    const auto coarsePos = this->getCoarseLatticeR(y);
+
+    T rho{};
+    T u[2] {};
+    coarseLattice.get(coarsePos).computeRhoU(rho, u);
+    _c2f_rho[y]  = order2interpolation(rho, _c2f_rho[y]);
+    _c2f_u[y][0] = order2interpolation(u[0], _c2f_u[y][0]);
+    _c2f_u[y][1] = order2interpolation(u[1], _c2f_u[y][1]);
+
+    T fNeq[DESCRIPTOR<T>::q] {};
+    computeFneq(coarseLattice.get(coarsePos), fNeq);
+    for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+      _c2f_fneq[y][iPop] = order2interpolation(fNeq[iPop], _c2f_fneq[y][iPop]);
+    }
+  }
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+void FineCoupler2D<T,DESCRIPTOR>::couple()
+{
+  auto& coarseLattice = this->_coarse.getSuperLattice();
+  auto& fineLattice   = this->_fine.getSuperLattice();
+
+  for (int y=0; y < this->_coarseSize; ++y) {
+    const auto coarsePos = this->getCoarseLatticeR(y);
+    const auto finePos   = this->getFineLatticeR(2*y);
+
+    T fEq[DESCRIPTOR<T>::q] {};
+    computeFeq(coarseLattice.get(coarsePos), fEq);
+
+    for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+      fineLattice.get(finePos)[iPop] = fEq[iPop] + this->_coarse.getScalingFactor() * _c2f_fneq[y][iPop];
+    }
+  }
+
+  for (int y=1; y < this->_coarseSize-2; ++y) {
+    const T rho = order4interpolation(
+                    _c2f_rho[y-1],
+                    _c2f_rho[y],
+                    _c2f_rho[y+1],
+                    _c2f_rho[y+2]
+                  );
+    T u[2] {};
+    u[0] = order4interpolation(
+             _c2f_u[y-1][0],
+             _c2f_u[y][0],
+             _c2f_u[y+1][0],
+             _c2f_u[y+2][0]
+           );
+    u[1] = order4interpolation(
+             _c2f_u[y-1][1],
+             _c2f_u[y][1],
+             _c2f_u[y+1][1],
+             _c2f_u[y+2][1]
+           );
+    const T uSqr = u[0]*u[0] + u[1]*u[1];
+
+    const auto finePos = this->getFineLatticeR(1+2*y);
+
+    for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+      const T fneq = order4interpolation(
+                       _c2f_fneq[y-1][iPop],
+                       _c2f_fneq[y][iPop],
+                       _c2f_fneq[y+1][iPop],
+                       _c2f_fneq[y+2][iPop]
+                     );
+
+      fineLattice.get(finePos)[iPop] = lbHelpers<T,DESCRIPTOR>::equilibrium(iPop, rho, u, uSqr) + this->_coarse.getScalingFactor() * fneq;
+    }
+  }
+
+  {
+    const T rho = order3interpolation(
+                    _c2f_rho[0],
+                    _c2f_rho[1],
+                    _c2f_rho[2]
+                  );
+    T u[2] {};
+    u[0] = order3interpolation(
+             _c2f_u[0][0],
+             _c2f_u[1][0],
+             _c2f_u[2][0]
+           );
+    u[1] = order3interpolation(
+             _c2f_u[0][1],
+             _c2f_u[1][1],
+             _c2f_u[2][1]
+           );
+    const T uSqr = u[0]*u[0] + u[1]*u[1];
+
+    const auto finePos = this->getFineLatticeR(1);
+
+    for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+      const T fneq = order3interpolation(
+                       _c2f_fneq[0][iPop],
+                       _c2f_fneq[1][iPop],
+                       _c2f_fneq[2][iPop]
+                     );
+      fineLattice.get(finePos)[iPop] = lbHelpers<T,DESCRIPTOR>::equilibrium(iPop, rho, u, uSqr) + this->_coarse.getScalingFactor() * fneq;
+    }
+  }
+
+  {
+    const T rho = order3interpolation(
+                    _c2f_rho[this->_coarseSize-1],
+                    _c2f_rho[this->_coarseSize-2],
+                    _c2f_rho[this->_coarseSize-3]
+                  );
+    T u[2] {};
+    u[0] = order3interpolation(
+             _c2f_u[this->_coarseSize-1][0],
+             _c2f_u[this->_coarseSize-2][0],
+             _c2f_u[this->_coarseSize-3][0]
+           );
+    u[1] = order3interpolation(
+             _c2f_u[this->_coarseSize-1][1],
+             _c2f_u[this->_coarseSize-2][1],
+             _c2f_u[this->_coarseSize-3][1]
+           );
+    const T uSqr = u[0]*u[0] + u[1]*u[1];
+
+    const auto finePos = this->getFineLatticeR(this->_fineSize-2);
+
+    for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+      const T fneq = order3interpolation(
+                       _c2f_fneq[this->_coarseSize-1][iPop],
+                       _c2f_fneq[this->_coarseSize-2][iPop],
+                       _c2f_fneq[this->_coarseSize-3][iPop]
+                     );
+      fineLattice.get(finePos)[iPop] = lbHelpers<T,DESCRIPTOR>::equilibrium(iPop, rho, u, uSqr) + this->_coarse.getScalingFactor() * fneq;
+    }
+  }
+}
+
+
+template <typename T, template<typename> class DESCRIPTOR>
+CoarseCoupler2D<T,DESCRIPTOR>::CoarseCoupler2D(
+  Grid2D<T,DESCRIPTOR>& coarse, Grid2D<T,DESCRIPTOR>& fine,
+  Vector<T,2> origin, Vector<T,2> extend):
+  Coupler2D<T,DESCRIPTOR>(coarse, fine, origin, extend)
+{
+  OstreamManager clout(std::cout,"F2C");
+  clout << "coarse origin: " << this->_coarseOrigin[0] << " " << this->_coarseOrigin[1] << " " << this->_coarseOrigin[2] << std::endl;
+  clout << "fine origin:   " << this->_fineOrigin[0] << " " << this->_fineOrigin[1] << " " << this->_fineOrigin[2] << std::endl;
+  clout << "coarse size:   " << this->_coarseSize << std::endl;
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+void CoarseCoupler2D<T,DESCRIPTOR>::couple()
+{
+  auto& fineLattice = this->_fine.getSuperLattice();
+  auto& coarseLattice = this->_coarse.getSuperLattice();
+
+  for (int y=0; y < this->_coarseSize; ++y) {
+    const auto finePos   = this->getFineLatticeR(2*y);
+    const auto coarsePos = this->getCoarseLatticeR(y);
+
+    T fEq[DESCRIPTOR<T>::q] {};
+    computeFeq(fineLattice.get(finePos), fEq);
+
+    T fNeq[DESCRIPTOR<T>::q] {};
+    computeRestrictedFneq(fineLattice, finePos, fNeq);
+
+    for (int iPop=0; iPop < DESCRIPTOR<T>::q; ++iPop) {
+      coarseLattice.get(coarsePos)[iPop] = fEq[iPop] + this->_coarse.getInvScalingFactor() * fNeq[iPop];
+    }
+  }
+}
+
+
+}
+
+#endif
diff --git a/src/refinement/grid2D.cpp b/src/refinement/grid2D.cpp
new file mode 100644
index 0000000..b371d0c
--- /dev/null
+++ b/src/refinement/grid2D.cpp
@@ -0,0 +1,34 @@
+/*  This file is part of the OpenLB library
+ *
+ *  Copyright (C) 2019 Adrian Kummerländer
+ *  E-mail contact: info@openlb.net
+ *  The most recent release of OpenLB can be downloaded at
+ *  <http://www.openlb.net/>
+ *
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU General Public License
+ *  as published by the Free Software Foundation; either version 2
+ *  of the License, or (at your option) any later version.
+ *
+ *  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 General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public
+ *  License along with this program; if not, write to the Free
+ *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ *  Boston, MA  02110-1301, USA.
+ */
+
+#include "grid2D.h"
+#include "grid2D.hh"
+
+#include "dynamics/latticeDescriptors.h"
+#include "dynamics/latticeDescriptors.hh"
+
+namespace olb {
+
+template class Grid2D<double,descriptors::D2Q9Descriptor>;
+
+}
diff --git a/src/refinement/grid2D.h b/src/refinement/grid2D.h
new file mode 100644
index 0000000..fda38ed
--- /dev/null
+++ b/src/refinement/grid2D.h
@@ -0,0 +1,87 @@
+/*  This file is part of the OpenLB library
+ *
+ *  Copyright (C) 2019 Adrian Kummerländer
+ *  E-mail contact: info@openlb.net
+ *  The most recent release of OpenLB can be downloaded at
+ *  <http://www.openlb.net/>
+ *
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU General Public License
+ *  as published by the Free Software Foundation; either version 2
+ *  of the License, or (at your option) any later version.
+ *
+ *  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 General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public
+ *  License along with this program; if not, write to the Free
+ *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ *  Boston, MA  02110-1301, USA.
+*/
+
+#ifndef REFINEMENT_GRID_2D_H
+#define REFINEMENT_GRID_2D_H
+
+#include <memory>
+#include <vector>
+
+#include "core/unitConverter.h"
+#include "core/superLattice2D.h"
+#include "geometry/superGeometry2D.h"
+#include "geometry/cuboidGeometry2D.h"
+#include "geometry/superGeometry2D.h"
+#include "communication/loadBalancer.h"
+#include "functors/analytical/indicator/indicatorF2D.h"
+
+namespace olb {
+
+
+template <typename T, template<typename> class DESCRIPTOR> class FineCoupler2D;
+template <typename T, template<typename> class DESCRIPTOR> class CoarseCoupler2D;
+
+template <typename T, template<typename> class DESCRIPTOR>
+class Grid2D {
+private:
+  std::unique_ptr<UnitConverter<T,DESCRIPTOR>>  _converter;
+  std::unique_ptr<CuboidGeometry2D<T>>          _cuboids;
+  std::unique_ptr<LoadBalancer<T>>              _balancer;
+  std::unique_ptr<SuperGeometry2D<T>>           _geometry;
+  std::unique_ptr<SuperLattice2D<T,DESCRIPTOR>> _lattice;
+
+  std::vector<std::unique_ptr<Grid2D<T,DESCRIPTOR>>> _fineGrids;
+
+  std::vector<std::unique_ptr<FineCoupler2D<T,DESCRIPTOR>>>   _fineCouplers;
+  std::vector<std::unique_ptr<CoarseCoupler2D<T,DESCRIPTOR>>> _coarseCouplers;
+
+public:
+  static std::unique_ptr<Grid2D<T,DESCRIPTOR>> make(IndicatorF2D<T>& domainF, int resolution, T tau, int re);
+
+  Grid2D(IndicatorF2D<T>& domainF, int resolution, T tau, int re);
+
+  UnitConverter<T,DESCRIPTOR>& getConverter();
+  CuboidGeometry2D<T>& getCuboidGeometry();
+  LoadBalancer<T>& getLoadBalancer();
+  SuperGeometry2D<T>& getSuperGeometry();
+  SuperLattice2D<T,DESCRIPTOR>& getSuperLattice();
+
+  T getScalingFactor();
+  T getInvScalingFactor();
+
+  void collideAndStream();
+
+  FineCoupler2D<T,DESCRIPTOR>& addFineCoupling(
+    Grid2D<T,DESCRIPTOR>& fineGrid, Vector<T,2> origin, Vector<T,2> extend);
+  CoarseCoupler2D<T,DESCRIPTOR>& addCoarseCoupling(
+    Grid2D<T,DESCRIPTOR>& fineGrid, Vector<T,2> origin, Vector<T,2> extend);
+
+  Grid2D<T,DESCRIPTOR>& refine(IndicatorF2D<T>& domainF);
+  Grid2D<T,DESCRIPTOR>& refine(Vector<T,2> origin, Vector<T,2> extend);
+
+};
+
+
+}
+
+#endif
diff --git a/src/refinement/grid2D.hh b/src/refinement/grid2D.hh
new file mode 100644
index 0000000..86c3102
--- /dev/null
+++ b/src/refinement/grid2D.hh
@@ -0,0 +1,208 @@
+/*  This file is part of the OpenLB library
+ *
+ *  Copyright (C) 2019 Adrian Kummerländer
+ *  E-mail contact: info@openlb.net
+ *  The most recent release of OpenLB can be downloaded at
+ *  <http://www.openlb.net/>
+ *
+ *  This program is free software; you can redistribute it and/or
+ *  modify it under the terms of the GNU General Public License
+ *  as published by the Free Software Foundation; either version 2
+ *  of the License, or (at your option) any later version.
+ *
+ *  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 General Public License for more details.
+ *
+ *  You should have received a copy of the GNU General Public
+ *  License along with this program; if not, write to the Free
+ *  Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+ *  Boston, MA  02110-1301, USA.
+*/
+
+#ifndef REFINEMENT_GRID_2D_HH
+#define REFINEMENT_GRID_2D_HH
+
+#include "grid2D.h"
+#include "coupler2D.hh"
+
+#include "communication/heuristicLoadBalancer.h"
+
+namespace olb {
+
+
+template <typename T, template<typename> class DESCRIPTOR>
+std::unique_ptr<Grid2D<T,DESCRIPTOR>> Grid2D<T,DESCRIPTOR>::make(
+                                     IndicatorF2D<T>& domainF,
+                                     int resolution, T tau, int re)
+{
+  return std::unique_ptr<Grid2D<T,DESCRIPTOR>>(
+           new Grid2D<T,DESCRIPTOR>(domainF, resolution, tau, re)
+         );
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+Grid2D<T,DESCRIPTOR>::Grid2D(IndicatorF2D<T>& domainF, int resolution, T tau, int re):
+  _converter(new UnitConverterFromResolutionAndRelaxationTime<T,DESCRIPTOR>(
+               resolution, // resolution: number of voxels per charPhysL
+               tau,        // latticeRelaxationTime: relaxation time, has to be greater than 0.5!
+               T{1},       // charPhysLength: reference length of simulation geometry
+               T{1},       // charPhysVelocity: maximal/highest expected velocity during simulation in __m / s__
+               T{1./re},   // physViscosity: physical kinematic viscosity in __m^2 / s__
+               T{1},       // physDensity: physical density in __kg / m^3__
+               T{1})),
+  _cuboids(new CuboidGeometry2D<T>(
+             domainF,
+             _converter->getConversionFactorLength(),
+             1)),
+  _balancer(new HeuristicLoadBalancer<T>(
+              *_cuboids)),
+  _geometry(new SuperGeometry2D<T>(
+              *_cuboids,
+              *_balancer,
+              2)),
+  _lattice(new SuperLattice2D<T,DESCRIPTOR>(
+             *_geometry))
+{
+  _converter->print();
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+UnitConverter<T,DESCRIPTOR>& Grid2D<T,DESCRIPTOR>::getConverter()
+{
+  return *_converter;
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+CuboidGeometry2D<T>& Grid2D<T,DESCRIPTOR>::getCuboidGeometry()
+{
+  return *_cuboids;
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+LoadBalancer<T>& Grid2D<T,DESCRIPTOR>::getLoadBalancer()
+{
+  return *_balancer;
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+SuperGeometry2D<T>& Grid2D<T,DESCRIPTOR>::getSuperGeometry()
+{
+  return *_geometry;
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+SuperLattice2D<T,DESCRIPTOR>& Grid2D<T,DESCRIPTOR>::getSuperLattice()
+{
+  return *_lattice;
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+T Grid2D<T,DESCRIPTOR>::getScalingFactor()
+{
+  return 4. - _converter->getLatticeRelaxationFrequency();
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+T Grid2D<T,DESCRIPTOR>::getInvScalingFactor()
+{
+  return 1./getScalingFactor();
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+void Grid2D<T,DESCRIPTOR>::collideAndStream()
+{
+  for ( auto& fineCoupler : _fineCouplers ) {
+    fineCoupler->store();
+  }
+
+  this->getSuperLattice().collideAndStream();
+
+  for ( auto& fineGrid : _fineGrids ) {
+    fineGrid->getSuperLattice().collideAndStream();
+  }
+
+  for ( auto& fineCoupler : _fineCouplers ) {
+    fineCoupler->interpolate();
+    fineCoupler->couple();
+  }
+
+  for ( auto& fineGrid : _fineGrids ) {
+    fineGrid->getSuperLattice().collideAndStream();
+  }
+
+  for ( auto& fineCoupler : _fineCouplers ) {
+    fineCoupler->store();
+    fineCoupler->couple();
+  }
+
+  for ( auto& coarseCoupler : _coarseCouplers ) {
+    coarseCoupler->couple();
+  }
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+FineCoupler2D<T,DESCRIPTOR>& Grid2D<T,DESCRIPTOR>::addFineCoupling(
+  Grid2D<T,DESCRIPTOR>& fineGrid, Vector<T,2> origin, Vector<T,2> extend)
+{
+  _fineCouplers.emplace_back(
+    new FineCoupler2D<T,DESCRIPTOR>(
+      *this, fineGrid, origin, extend));
+  return *_fineCouplers.back();
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+CoarseCoupler2D<T,DESCRIPTOR>& Grid2D<T,DESCRIPTOR>::addCoarseCoupling(
+  Grid2D<T,DESCRIPTOR>& fineGrid, Vector<T,2> origin, Vector<T,2> extend)
+{
+  _coarseCouplers.emplace_back(
+    new CoarseCoupler2D<T,DESCRIPTOR>(
+      *this, fineGrid, origin, extend));
+  return *_coarseCouplers.back();
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+Grid2D<T,DESCRIPTOR>& Grid2D<T,DESCRIPTOR>::refine(IndicatorF2D<T>& domainF)
+{
+  _fineGrids.emplace_back(
+    new Grid2D<T,DESCRIPTOR>(
+      domainF,
+      2*getConverter().getResolution(),
+      2.0*getConverter().getLatticeRelaxationTime() - 0.5,
+      getConverter().getReynoldsNumber()
+    ));
+  return *_fineGrids.back();
+}
+
+template <typename T, template<typename> class DESCRIPTOR>
+Grid2D<T,DESCRIPTOR>& Grid2D<T,DESCRIPTOR>::refine(Vector<T,2> origin, Vector<T,2> extend)
+{
+  IndicatorCuboid2D<T> fineCuboid(extend, origin);
+  auto& fineGrid = refine(fineCuboid);
+
+  const Vector<T,2> extendX = {extend[0],0};
+  const Vector<T,2> extendY = {0,extend[1]};
+
+  addFineCoupling(fineGrid, origin,           extendY);
+  addFineCoupling(fineGrid, origin + extendX, extendY);
+  addFineCoupling(fineGrid, origin + extendY, extendX);
+  addFineCoupling(fineGrid, origin,           extendX);
+
+  const T coarseDeltaX = getConverter().getPhysDeltaX();
+  const Vector<T,2> innerOrigin = origin + coarseDeltaX;
+  const Vector<T,2> innerExtendX = extendX - Vector<T,2> {2*coarseDeltaX,0};
+  const Vector<T,2> innerExtendY = extendY - Vector<T,2> {0,2*coarseDeltaX};
+
+  addCoarseCoupling(fineGrid, innerOrigin,                innerExtendY);
+  addCoarseCoupling(fineGrid, innerOrigin + innerExtendX, innerExtendY);
+  addCoarseCoupling(fineGrid, innerOrigin + innerExtendY, innerExtendX);
+  addCoarseCoupling(fineGrid, innerOrigin,                innerExtendX);
+
+  return fineGrid;
+}
+
+
+}
+
+#endif
diff --git a/src/refinement/module.mk b/src/refinement/module.mk
new file mode 100644
index 0000000..6e42e3e
--- /dev/null
+++ b/src/refinement/module.mk
@@ -0,0 +1,27 @@
+#  This file is part of the OpenLB library
+#
+#  Copyright (C) 2017 Markus Mohrhard
+#  E-mail contact: info@openlb.net
+#  The most recent release of OpenLB can be downloaded at
+#  <http://www.openlb.net/>
+#
+#  This program is free software; you can redistribute it and/or
+#  modify it under the terms of the GNU General Public License
+#  as published by the Free Software Foundation; either version 2
+#  of the License, or (at your option) any later version.
+#
+#  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 General Public License for more details.
+#
+#  You should have received a c