tpl_ca_engine.H

Go to the documentation of this file.

/*
                          Aleph_w
 
  Data structures & Algorithms
  version 2.0.0b
  https://github.com/lrleon/Aleph-w
 
  This file is part of Aleph-w library
 
  Copyright (c) 2002-2026 Leandro Rabindranath Leon
 
  Permission is hereby granted, free of charge, to any person obtaining a copy
  of this software and associated documentation files (the "Software"), to deal
  in the Software without restriction, including without limitation the rights
  to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
  copies of the Software, and to permit persons to whom the Software is
  furnished to do so, subject to the following conditions:
 
  The above copyright notice and this permission notice shall be included in all
  copies or substantial portions of the Software.
 
  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
  OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
  SOFTWARE.
*/
 
#ifndef TPL_CA_ENGINE_H
#define TPL_CA_ENGINE_H
 
#include <array>
#include <concepts>
#include <cstddef>
#include <functional>
#include <span>
#include <type_traits>
#include <utility>
 
#include <ca-traits.H>
#include <tpl_ca_concepts.H>
#include <tpl_ca_neighborhood.H>
 
namespace Aleph {
namespace CA {
 
namespace ca_engine_detail {
template <typename O>
struct is_tile : std::false_type
{
};
 
template <std::size_t W, std::size_t H>
struct is_tile<Tile<W, H>> : std::true_type
{
};
 
template <typename O>
inline constexpr bool is_tile_v = is_tile<O>::value;
 
template <typename Coord, typename F>
inline void iterate_1d(ca_size_t n0, F &&f)
{
  Coord c{};
  for (ca_index_t i = 0; i < static_cast<ca_index_t>(n0); ++i)
    {
      c[0] = i;
      f(c);
    }
}
 
template <typename Coord, typename F>
inline void iterate_2d_row_major(ca_size_t n0, ca_size_t n1, F &&f)
{
  Coord c{};
  for (ca_index_t i = 0; i < static_cast<ca_index_t>(n0); ++i)
    for (ca_index_t j = 0; j < static_cast<ca_index_t>(n1); ++j)
      {
        c[0] = i;
        c[1] = j;
        f(c);
      }
}
 
template <typename Coord, typename F>
inline void iterate_2d_column_major(ca_size_t n0, ca_size_t n1, F &&f)
{
  Coord c{};
  for (ca_index_t j = 0; j < static_cast<ca_index_t>(n1); ++j)
    for (ca_index_t i = 0; i < static_cast<ca_index_t>(n0); ++i)
      {
        c[0] = i;
        c[1] = j;
        f(c);
      }
}
 
template <std::size_t W, std::size_t H, typename Coord, typename F>
inline void iterate_2d_tile(const ca_size_t n0, const ca_size_t n1, F &&f)
{
  Coord c{};
  for (ca_size_t ti = 0; ti < n0; ti += H)
    for (ca_size_t tj = 0; tj < n1; tj += W)
      {
        const ca_size_t i_end = ti + H < n0 ? ti + H : n0;
        const ca_size_t j_end = tj + W < n1 ? tj + W : n1;
        for (ca_size_t i = ti; i < i_end; ++i)
          for (ca_size_t j = tj; j < j_end; ++j)
            {
              c[0] = static_cast<ca_index_t>(i);
              c[1] = static_cast<ca_index_t>(j);
              f(c);
            }
      }
}
 
template <typename Coord, typename F>
inline void iterate_3d_row_major(const ca_size_t n0, const ca_size_t n1, const ca_size_t n2, F &&f)
{
  Coord c{};
  for (ca_index_t i = 0; i < static_cast<ca_index_t>(n0); ++i)
    for (ca_index_t j = 0; j < static_cast<ca_index_t>(n1); ++j)
      for (ca_index_t k = 0; k < static_cast<ca_index_t>(n2); ++k)
        {
          c[0] = i;
          c[1] = j;
          c[2] = k;
          f(c);
        }
}
}  // namespace ca_engine_detail
 
template <typename Lattice, typename Rule, typename Neighborhood, typename Order = RowMajor>
class Synchronous_Engine
{
  static_assert(LatticeLike<Lattice>, "Synchronous_Engine requires a LatticeLike lattice");
  static_assert(NeighborhoodLike<Neighborhood>,
                "Synchronous_Engine requires a NeighborhoodLike neighborhood");
  static_assert(RuleLike<Rule, Lattice>, "Synchronous_Engine requires a RuleLike rule");
  static_assert(Neighborhood::rank_v == Lattice::rank, "Neighborhood rank must match lattice rank");
 
public:
  using lattice_type = Lattice;
  using rule_type = Rule;
  using neighborhood_type = Neighborhood;
  using order_type = Order;
 
  using state_type = typename Lattice::state_type;
  using coord_type = typename Lattice::coord_type;
  using extents_type = typename Lattice::extents_type;
 
  static constexpr std::size_t rank = Lattice::rank;
  static constexpr std::size_t neighbour_count = Neighborhood::size_v;
 
  using hook_type = std::function<void(std::size_t, const Lattice &)>;
 
private:
  Lattice cur_buf_;
  Lattice nxt_buf_;
  Rule rule_;
  Neighborhood nh_;
  hook_type pre_hook_;
  hook_type post_hook_;
  std::size_t step_count_ = 0;
 
public:
  Synchronous_Engine(Lattice initial, Rule r, Neighborhood n)
    : cur_buf_(std::move(initial)), nxt_buf_(cur_buf_.extents()), rule_(std::move(r)), nh_(std::move(n))
  {}
 
  Synchronous_Engine(Lattice initial, Rule r)
    requires std::default_initializable<Neighborhood>
    : Synchronous_Engine(std::move(initial), std::move(r), Neighborhood{})
  {}
 
  [[nodiscard]] const Lattice &frame() const noexcept
  {
    return cur_buf_;
  }
 
  [[nodiscard]] std::size_t steps_run() const noexcept
  {
    return step_count_;
  }
 
  [[nodiscard]] const extents_type &extents() const noexcept
  {
    return cur_buf_.extents();
  }
 
  [[nodiscard]] const Rule &rule() const noexcept
  {
    return rule_;
  }
 
  [[nodiscard]] Rule &rule() noexcept
  {
    return rule_;
  }
 
  [[nodiscard]] Lattice &write_lattice() noexcept
  {
    return cur_buf_;
  }
 
  void set_step_count(const std::size_t s) noexcept
  {
    step_count_ = s;
  }
 
  template <typename F>
  void on_pre_step(F &&f)
  {
    pre_hook_ = std::forward<F>(f);
  }
 
  template <typename F>
  void on_post_step(F &&f)
  {
    post_hook_ = std::forward<F>(f);
  }
 
  void step()
  {
    using namespace ca_engine_detail;
 
    // Refresh the ghost layer, if the lattice has one. This is what
    // allows Phase 4 lattices to keep the boundary logic out of the
    // inner loop: by the time `gather_neighbors` runs, every cell
    // inside the halo already carries the correct policy value.
    if constexpr (HasRefreshHalo<Lattice>)
      cur_buf_.refresh_halo();
 
    if (pre_hook_)
      pre_hook_(step_count_, cur_buf_);
 
    // Stack buffer for the gathered neighbour values. Size is fixed
    // by the neighbourhood at compile time, so no heap involvement.
    std::array<state_type, neighbour_count> nbuf{};
 
    auto compute_one = [&](const coord_type &c)
    {
      const std::size_t neigh_sz = std::min(nh_.size(), nbuf.size());
      gather_neighbors(nh_, cur_buf_, c, std::span<state_type>(nbuf.data(), neigh_sz));
      const Cell_Context<rank> ctx{step_count_, c};
      nxt_buf_.set(c,
                   apply_rule(rule_,
                              cur_buf_.at(c),
                              Neighbor_View<state_type>(nbuf.data(), neigh_sz),
                              ctx));
    };
 
    if constexpr (rank == 1)
      {
        iterate_1d<coord_type>(cur_buf_.size(0), compute_one);
      }
    else if constexpr (rank == 2)
      {
        if constexpr (is_tile_v<Order>)
          iterate_2d_tile<Order::width, Order::height, coord_type>(cur_buf_.size(0),
                                                                   cur_buf_.size(1),
                                                                   compute_one);
        else if constexpr (std::is_same_v<Order, ColumnMajor>)
          iterate_2d_column_major<coord_type>(cur_buf_.size(0), cur_buf_.size(1), compute_one);
        else
          iterate_2d_row_major<coord_type>(cur_buf_.size(0), cur_buf_.size(1), compute_one);
      }
    else if constexpr (rank == 3)
      {
        iterate_3d_row_major<coord_type>(cur_buf_.size(0), cur_buf_.size(1), cur_buf_.size(2), compute_one);
      }
    else
      static_assert(rank <= 3, "Synchronous_Engine currently supports rank <= 3");
 
    cur_buf_.swap(nxt_buf_);
    ++step_count_;
 
    if (post_hook_)
      post_hook_(step_count_, cur_buf_);
  }
 
  void run(const std::size_t steps)
  {
    for (std::size_t i = 0; i < steps; ++i)
      step();
  }
};
 
}  // namespace CA
}  // namespace Aleph
 
#endif  // TPL_CA_ENGINE_H