✨ SiQAD coordinate iteration

docs/layouts/coordinates.rst

@@ -12,8 +12,6 @@ An offset coordinate is a coordinate that defines a location via an offset from
 
 .. doxygenstruct:: fiction::offset::ucoord_t
 
-.. doxygenclass:: fiction::offset::coord_iterator
-
 Cube coordinates
 ----------------
 
@@ -23,13 +21,20 @@ At the same time, they can be used to address 3-dimensional grids.
 .. doxygenstruct:: fiction::cube::coord_t
 
 SiQAD coordinates
-----------------
+-----------------
 
-SiQAD coordinates are used to describe locations of Silicon Dangling Bonds on the H-Si(100) 2x1 surface were dimer columns and rows are identified by x and y values, respecitvely,
+SiQAD coordinates are used to describe locations of Silicon Dangling Bonds on the H-Si(100) 2x1 surface were dimer columns and rows are identified by x and y values, respectively,
 while the z value (0,1) points to the top or bottom Si atom in the dimer. The coordinates are originally used in the SiQAD simulator (https://github.com/siqad).
 
 .. doxygenstruct:: fiction::siqad::coord_t
 
+Coordinate iterator
+-------------------
+
+An iterator type that allows to enumerate coordinates in order within a boundary.
+
+.. doxygenclass:: fiction::coord_iterator
+
 Utility functions
 -----------------
 

include/fiction/io/print_layout.hpp

@@ -12,7 +12,6 @@
 #include <fmt/color.h>
 #include <fmt/format.h>
 
-#include <algorithm>
 #include <array>
 #include <cmath>
 #include <cstdint>
@@ -368,51 +367,46 @@ void print_charge_layout(std::ostream& os, const charge_distribution_surface<Lyt
     const coordinate<Lyt> min{std::max(min_x - 2, 0), std::max(min_y - 1, 0)};
     const coordinate<Lyt> max{std::min(max_x + 2, cds.x()), std::min(max_y + 1, cds.y())};
 
-    // loop over dimer pairs
-    for (decltype(cds.y()) y_pos = min.y; y_pos <= max.y; ++y_pos)
-    {
-        // loop over rows of a dimer pair
-        for (uint8_t r = 0; r <= 1; ++r)
+    // iterate over all coordinates in the rows determined by the vertical crop
+    cds.foreach_coordinate(
+        [&](const coordinate<Lyt>& c)
         {
-            for (decltype(cds.x()) x_pos = min.x; x_pos <= max.x; ++x_pos)
+            if (c.x < min.x || c.x > max.x)  // apply horizontal crop
             {
-                const cell<Lyt> c{x_pos, y_pos, r};
+                return;
+            }
 
-                if (cds.is_empty_cell(c))
+            switch (cds.get_charge_state(c))  // switch over the charge state of the SiDB at the current coordinate
+            {
+                case sidb_charge_state::NEGATIVE:
                 {
-                    os << (draw_lattice ? fmt::format(cs_color ? detail::SIDB_LAT_COLOR : detail::NO_COLOR, " · ") :
-                                          "  ");
-                    continue;
+                    os << fmt::format(cs_color ? detail::SIDB_NEG_COLOR : detail::NO_COLOR, " ● ");
+                    break;
                 }
-
-                // switch over the charge state of the SiDB index associated with the current cell, and update count
-                switch (cds.get_charge_state(c))
+                case sidb_charge_state::POSITIVE:
                 {
-                    case sidb_charge_state::NEGATIVE:
-                    {
-                        os << fmt::format(cs_color ? detail::SIDB_NEG_COLOR : detail::NO_COLOR, " ● ");
-                        continue;
-                    }
-                    case sidb_charge_state::POSITIVE:
-                    {
-                        os << fmt::format(cs_color ? detail::SIDB_POS_COLOR : detail::NO_COLOR, " ⨁ ");
-                        continue;
-                    }
-                    case sidb_charge_state::NEUTRAL:
-                    {
-                        os << fmt::format(cs_color ? detail::SIDB_NEUT_COLOR : detail::NO_COLOR, " ◯ ");
-                        continue;
-                    }
-                    default:  // NONE charge state case
-                    {
-                        os << fmt::format(cs_color ? detail::SIDB_LAT_COLOR : detail::NO_COLOR, " ◌ ");
-                    }
+                    os << fmt::format(cs_color ? detail::SIDB_POS_COLOR : detail::NO_COLOR, " ⨁ ");
+                    break;
+                }
+                case sidb_charge_state::NEUTRAL:
+                {
+                    os << fmt::format(cs_color ? detail::SIDB_NEUT_COLOR : detail::NO_COLOR, " ◯ ");
+                    break;
+                }
+                default:  // NONE charge state case -> empty cell
+                {
+                    os << (draw_lattice || !cds.is_empty_cell(c) ?
+                               fmt::format(cs_color ? detail::SIDB_LAT_COLOR : detail::NO_COLOR, " · ") :
+                               "  ");
                 }
             }
-            os << '\n';
-        }
-        os << '\n';
-    }
+
+            if (c.x == max.x)
+            {
+                os << (c.z == 1 ? "\n\n" : "\n");
+            }
+        },
+        min, {0, max.y + 1, 0});
 
     // flush stream
     os << std::endl;

include/fiction/layouts/cartesian_layout.hpp

@@ -621,15 +621,15 @@ class cartesian_layout
      * will be iterated first, then y, then z.
      *
      * @param start First coordinate to include in the range of all coordinates.
-     * @param stop Last coordinate to include in the range of all coordinates.
+     * @param stop Last coordinate (exclusive) to include in the range of all coordinates.
      * @return An iterator range from `start` to `stop`. If they are not provided, the first/last coordinate is used as
      * a default.
      */
     [[nodiscard]] auto coordinates(const OffsetCoordinateType& start = {}, const OffsetCoordinateType& stop = {}) const
     {
         return range_t{std::make_pair(
-            offset::coord_iterator{strg->dimension, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
-            offset::coord_iterator{strg->dimension, stop.is_dead() ? strg->dimension.get_dead() : stop})};
+            coord_iterator{strg->dimension, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
+            coord_iterator{strg->dimension, stop.is_dead() ? strg->dimension.get_dead() : stop})};
     }
     /**
      * Applies a function to all coordinates accessible in the layout between `start` and `stop`. The iteration order is
@@ -638,22 +638,22 @@ class cartesian_layout
      * @tparam Fn Functor type that has to comply with the restrictions imposed by `mockturtle::foreach_element`.
      * @param fn Functor to apply to each coordinate in the range.
      * @param start First coordinate to include in the range of all coordinates.
-     * @param stop Last coordinate to include in the range of all coordinates.
+     * @param stop Last coordinate (exclusive) to include in the range of all coordinates.
      */
     template <typename Fn>
     void foreach_coordinate(Fn&& fn, const OffsetCoordinateType& start = {},
                             const OffsetCoordinateType& stop = {}) const
     {
         mockturtle::detail::foreach_element(
-            offset::coord_iterator{strg->dimension, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
-            offset::coord_iterator{strg->dimension, stop.is_dead() ? strg->dimension.get_dead() : stop}, fn);
+            coord_iterator{strg->dimension, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
+            coord_iterator{strg->dimension, stop.is_dead() ? strg->dimension.get_dead() : stop}, fn);
     }
     /**
      * Returns a range of all coordinates accessible in the layout's ground layer between `start` and `stop`. The
      * iteration order is the same as for the coordinates function but without the z dimension.
      *
      * @param start First coordinate to include in the range of all ground coordinates.
-     * @param stop Last coordinate to include in the range of all ground coordinates.
+     * @param stop Last coordinate (exclusive) to include in the range of all ground coordinates.
      * @return An iterator range from `start` to `stop`. If they are not provided, the first/last coordinate in the
      * ground layer is used as a default.
      */
@@ -665,8 +665,8 @@ class cartesian_layout
         const auto ground_layer = aspect_ratio{x(), y(), 0};
 
         return range_t{
-            std::make_pair(offset::coord_iterator{ground_layer, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
-                           offset::coord_iterator{ground_layer, stop.is_dead() ? ground_layer.get_dead() : stop})};
+            std::make_pair(coord_iterator{ground_layer, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
+                           coord_iterator{ground_layer, stop.is_dead() ? ground_layer.get_dead() : stop})};
     }
     /**
      * Applies a function to all coordinates accessible in the layout's ground layer between `start` and `stop`. The
@@ -675,7 +675,7 @@ class cartesian_layout
      * @tparam Fn Functor type that has to comply with the restrictions imposed by `mockturtle::foreach_element`.
      * @param fn Functor to apply to each coordinate in the range.
      * @param start First coordinate to include in the range of all ground coordinates.
-     * @param stop Last coordinate to include in the range of all ground coordinates.
+     * @param stop Last coordinate (exclusive) to include in the range of all ground coordinates.
      */
     template <typename Fn>
     void foreach_ground_coordinate(Fn&& fn, const OffsetCoordinateType& start = {},
@@ -686,8 +686,8 @@ class cartesian_layout
         const auto ground_layer = aspect_ratio{x(), y(), 0};
 
         mockturtle::detail::foreach_element(
-            offset::coord_iterator{ground_layer, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
-            offset::coord_iterator{ground_layer, stop.is_dead() ? ground_layer.get_dead() : stop}, fn);
+            coord_iterator{ground_layer, start.is_dead() ? OffsetCoordinateType{0, 0} : start},
+            coord_iterator{ground_layer, stop.is_dead() ? ground_layer.get_dead() : stop}, fn);
     }
     /**
      * Returns a container that contains all coordinates that are adjacent to a given one. Thereby, only cardinal