Extract refinement scaffolding into separate units

13 files changed, 909 insertions, 495 deletions

diff --git a/apps/adrian/poiseuille2d/poiseuille2d.cpp b/apps/adrian/poiseuille2d/poiseuille2d.cpp
index 9ef1ce8..f30e9b4 100644
--- a/apps/adrian/poiseuille2d/poiseuille2d.cpp
+++ b/apps/adrian/poiseuille2d/poiseuille2d.cpp
@@ -197,500 +197,6 @@ void getResults(const std::string& prefix,
   }
 }
 
-template <typename T, template<typename> class DESCRIPTOR> class FineCoupler;
-template <typename T, template<typename> class DESCRIPTOR> class CoarseCoupler;
-
-template <typename T, template<typename> class DESCRIPTOR>
-class Grid {
-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<Grid<T,DESCRIPTOR>>> _fineGrids;
-
-  std::vector<std::unique_ptr<FineCoupler<T,DESCRIPTOR>>> _fineCouplers;
-  std::vector<std::unique_ptr<CoarseCoupler<T,DESCRIPTOR>>> _coarseCouplers;
-
-public:
-  static std::unique_ptr<Grid<T,DESCRIPTOR>> make(IndicatorF2D<T>& domainF, int resolution, T tau, int re)
-  {
-    return std::unique_ptr<Grid<T,DESCRIPTOR>>(
-             new Grid<T,DESCRIPTOR>(domainF, resolution, tau, re)
-           );
-  }
-
-  Grid(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();
-  }
-
-  UnitConverter<T,DESCRIPTOR>& getConverter()
-  {
-    return *_converter;
-  }
-
-  CuboidGeometry2D<T>& getCuboidGeometry()
-  {
-    return *_cuboids;
-  }
-
-  LoadBalancer<T>& getLoadBalancer()
-  {
-    return *_balancer;
-  }
-
-  SuperGeometry2D<T>& getSuperGeometry()
-  {
-    return *_geometry;
-  }
-
-  SuperLattice2D<T,DESCRIPTOR>& getSuperLattice()
-  {
-    return *_lattice;
-  }
-
-  T getScalingFactor()
-  {
-    return 4. - _converter->getLatticeRelaxationFrequency();
-  }
-
-  T getInvScalingFactor()
-  {
-    return 1./getScalingFactor();
-  }
-
-  void 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();
-    }
-  }
-
-  FineCoupler<T,DESCRIPTOR>& addFineCoupling(
-    Grid<T,DESCRIPTOR>& fineGrid, Vector<T,2> origin, Vector<T,2> extend)
-  {
-    _fineCouplers.emplace_back(
-      new FineCoupler<T,DESCRIPTOR>(
-        *this, fineGrid, origin, extend));
-    return *_fineCouplers.back();
-  }
-
-  CoarseCoupler<T,DESCRIPTOR>& addCoarseCoupling(
-    Grid<T,DESCRIPTOR>& fineGrid, Vector<T,2> origin, Vector<T,2> extend)
-  {
-    _coarseCouplers.emplace_back(
-      new CoarseCoupler<T,DESCRIPTOR>(
-        *this, fineGrid, origin, extend));
-    return *_coarseCouplers.back();
-  }
-
-  Grid<T,DESCRIPTOR>& refine(IndicatorF2D<T>& domainF)
-  {
-    _fineGrids.emplace_back(
-      new Grid<T,DESCRIPTOR>(
-        domainF,
-        2*getConverter().getResolution(),
-        2.0*getConverter().getLatticeRelaxationTime() - 0.5,
-        getConverter().getReynoldsNumber()
-      ));
-    return *_fineGrids.back();
-  }
-
-  Grid<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;
-  }
-};
-
-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);
-}
-
-T order4interpolation(T fm3, T fm1, T f1, T f3)
-{
-  return 9./16. * (fm1 + f1) - 1./16. * (fm3 + f3);
-}
-
-T order3interpolation(T fm1, T f1, T f3)
-{
-  return 3./8. * fm1 + 3./4. * f1 - 1./8. * f3;
-}
-
-T order2interpolation(T f0, T f1)
-{
-  return 0.5 * (f0 + f1);
-}
-
-template <typename T, template<typename> class DESCRIPTOR>
-class Coupler {
-protected:
-  Grid<T,DESCRIPTOR>& _coarse;
-  Grid<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
-  {
-    if (_vertical) {
-      return _fineOrigin + Vector<int,3> {0, 0, y};
-    }
-    else {
-      return _fineOrigin + Vector<int,3> {0, y, 0};
-    }
-  }
-
-  Vector<int,3> getCoarseLatticeR(int y) const
-  {
-    if (_vertical) {
-      return _coarseOrigin + Vector<int,3> {0, 0, y};
-    }
-    else {
-      return _coarseOrigin + Vector<int,3> {0, y, 0};
-    }
-  }
-
-public:
-  Coupler(Grid<T,DESCRIPTOR>& coarse, Grid<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>
-class FineCoupler : public Coupler<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:
-  FineCoupler(Grid<T,DESCRIPTOR>& coarse, Grid<T,DESCRIPTOR>& fine, Vector<T,2> origin, Vector<T,2> extend):
-    Coupler<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;
-  }
-
-  void 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);
-    }
-  }
-
-  void 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]);
-      }
-    }
-  }
-
-  void 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>
-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>
-class CoarseCoupler : public Coupler<T,DESCRIPTOR> {
-public:
-  CoarseCoupler(Grid<T,DESCRIPTOR>& coarse, Grid<T,DESCRIPTOR>& fine, Vector<T,2> origin, Vector<T,2> extend):
-    Coupler<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;
-  }
-
-  void 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];
-      }
-    }
-  }
-};
-
 int main(int argc, char* argv[])
 {
   olbInit(&argc, &argv);
@@ -704,7 +210,7 @@ int main(int argc, char* argv[])
   Vector<T,2> fineOrigin   { 0.25 * lx, 0.2 };
   Vector<T,2> fineExtend   { 0.6  * lx, 0.6 };
 
-  auto coarseGrid = Grid<T,DESCRIPTOR>::make(coarseCuboid, N, 0.8, Re);
+  auto coarseGrid = Grid2D<T,DESCRIPTOR>::make(coarseCuboid, N, 0.8, Re);
   auto fineGrid   = &coarseGrid->refine(fineOrigin, fineExtend);
 
   prepareGeometry(coarseGrid->getConverter(), coarseGrid->getSuperGeometry());
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 < DESC