ca-observer.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 CA_OBSERVER_H
#define CA_OBSERVER_H
 
#include <concepts>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <optional>
#include <tuple>
#include <utility>
 
#include <ah-errors.H>
#include <tpl_array.H>
 
#include <ca-metrics.H>
#include <ca-traits.H>
#include <tpl_ca_concepts.H>
 
namespace Aleph {
namespace CA {
 
template <typename O, typename Lattice>
concept ObserverLike = requires(O &o, std::size_t s, const Lattice &f) {
  o.on_step_begin(s, f);
  o.on_step_end(s, f);
};
 
// ---------------------------------------------------------------------------
// Composite observer.
// ---------------------------------------------------------------------------
 
template <typename... Observers>
class Composite_Observer
{
  std::tuple<Observers...> obs_;
 
public:
  explicit Composite_Observer(Observers... observers) : obs_(std::forward<Observers>(observers)...)
  {}
 
  template <std::size_t I>
  [[nodiscard]] const auto &get() const noexcept
  {
    return std::get<I>(obs_);
  }
 
  template <std::size_t I>
  [[nodiscard]] auto &get() noexcept
  {
    return std::get<I>(obs_);
  }
 
  [[nodiscard]] static constexpr std::size_t size() noexcept
  {
    return sizeof...(Observers);
  }
 
  template <typename Lattice>
  void on_step_begin(std::size_t step, const Lattice &frame)
  {
    std::apply([&](auto &...o)
    {
      (o.on_step_begin(step, frame), ...);
    }, obs_);
  }
 
  template <typename Lattice>
  void on_step_end(std::size_t step, const Lattice &frame)
  {
    std::apply([&](auto &...o)
    {
      (o.on_step_end(step, frame), ...);
    }, obs_);
  }
};
 
template <typename... Observers>
[[nodiscard]] inline auto make_composite_observer(Observers &&...observers)
{
  return Composite_Observer<Observers...>(std::forward<Observers>(observers)...);
}
 
// ---------------------------------------------------------------------------
// Engine plumbing.
// ---------------------------------------------------------------------------
 
template <typename Engine, typename Observer>
inline void attach_observer(Engine &engine, Observer &observer)
{
  using Lat = typename Engine::lattice_type;
  engine.on_pre_step([&observer](std::size_t step, const Lat &frame)
  {
    observer.on_step_begin(step, frame);
  });
  engine.on_post_step([&observer](std::size_t step, const Lat &frame)
  {
    observer.on_step_end(step, frame);
  });
}
 
template <typename Engine, typename Observer>
inline void attach_observer_graph(Engine &engine, Observer &observer)
{
  engine.on_pre_step([&observer](std::size_t step, const auto &frame)
  {
    observer.on_step_begin(step, frame);
  });
  engine.on_post_step([&observer](std::size_t step, const auto &frame)
  {
    observer.on_step_end(step, frame);
  });
}
 
// ---------------------------------------------------------------------------
// Density observer.
// ---------------------------------------------------------------------------
 
template <typename State>
class Density_Observer
{
  State tracked_state_{};
  Array<ca_size_t> counts_;
  Array<ca_size_t> totals_;
  bool seeded_ = false;
 
public:
  Density_Observer() = default;
 
  explicit Density_Observer(State s) : tracked_state_(std::move(s)) {}
 
  [[nodiscard]] const Array<ca_size_t> &counts() const noexcept
  {
    return counts_;
  }
 
  [[nodiscard]] const Array<ca_size_t> &totals() const noexcept
  {
    return totals_;
  }
 
  [[nodiscard]] double density_at(const std::size_t i) const
  {
    ah_out_of_range_error_if(i >= counts_.size())
      << "Density_Observer: index " << i << " out of range";
    return totals_[i] == 0 ? 0.0 : static_cast<double>(counts_[i]) / static_cast<double>(totals_[i]);
  }
 
  [[nodiscard]] std::size_t size() const noexcept
  {
    return counts_.size();
  }
 
  void reset() noexcept
  {
    counts_.clear();
    totals_.clear();
    seeded_ = false;
  }
 
  template <typename Lattice>
  void on_step_begin(const std::size_t step, const Lattice &frame)
  {
    if (step == 0 and not seeded_)
      {
        counts_.append(count_state(frame, tracked_state_));
        totals_.append(total_cells(frame));
        seeded_ = true;
      }
  }
 
  template <typename Lattice>
  void on_step_end(const std::size_t step, const Lattice &frame)
  {
    (void) step;
    counts_.append(count_state(frame, tracked_state_));
    totals_.append(total_cells(frame));
  }
};
 
// ---------------------------------------------------------------------------
// Activity observer.
// ---------------------------------------------------------------------------
 
template <typename Lattice>
class Activity_Observer
{
  std::optional<Lattice> prev_;
  Array<ca_size_t> activity_;
 
public:
  Activity_Observer() = default;
 
  [[nodiscard]] const Array<ca_size_t> &activity() const noexcept
  {
    return activity_;
  }
 
  [[nodiscard]] std::size_t size() const noexcept
  {
    return activity_.size();
  }
 
  void reset() noexcept
  {
    prev_.reset();
    activity_.clear();
  }
 
  void on_step_begin(std::size_t step, const Lattice &frame)
  {
    (void) step;
    prev_.emplace(frame);
  }
 
  void on_step_end(const std::size_t step, const Lattice &frame)
  {
    (void) step;
    if (prev_.has_value())
      activity_.append(cell_diff_count(*prev_, frame));
    else
      activity_.append(0);
  }
};
 
// ---------------------------------------------------------------------------
// Entropy observer.
// ---------------------------------------------------------------------------
 
template <std::size_t MaxState>
class Entropy_Observer
{
  Array<double> entropy_;
  bool seeded_ = false;
 
public:
  Entropy_Observer() = default;
 
  [[nodiscard]] const Array<double> &entropy() const noexcept
  {
    return entropy_;
  }
 
  [[nodiscard]] std::size_t size() const noexcept
  {
    return entropy_.size();
  }
 
  void reset() noexcept
  {
    entropy_.clear();
    seeded_ = false;
  }
 
  template <typename Lattice>
  void on_step_begin(const std::size_t step, const Lattice &frame)
  {
    if (step == 0 and not seeded_)
      {
        entropy_.append(shannon_entropy(frame, MaxState));
        seeded_ = true;
      }
  }
 
  template <typename Lattice>
  void on_step_end(const std::size_t step, const Lattice &frame)
  {
    (void) step;
    entropy_.append(shannon_entropy(frame, MaxState));
  }
};
 
// ---------------------------------------------------------------------------
// Stationary detector.
// ---------------------------------------------------------------------------
 
class Stationary_Detector
{
  std::size_t max_cycle_length_ = 0;
  Array<std::uint64_t> hashes_;
  Array<std::size_t> steps_;
  std::optional<std::size_t> cycle_length_;
  std::optional<std::size_t> cycle_start_;
 
  void push(const std::uint64_t h, const std::size_t step) noexcept
  {
    if (hashes_.size() >= max_cycle_length_ + 1)
      {
        // Drop the oldest entry (front of the buffer); remove_first
        // closes the gap, preserving the window order.
        (void) hashes_.remove_first();
        (void) steps_.remove_first();
      }
    hashes_.append(h);
    steps_.append(step);
  }
 
public:
  Stationary_Detector() = default;
 
  explicit Stationary_Detector(std::size_t max_cycle_length) : max_cycle_length_(max_cycle_length)
  {}
 
  [[nodiscard]] bool cycle_detected() const noexcept
  {
    return cycle_length_.has_value();
  }
 
  [[nodiscard]] std::optional<std::size_t> cycle_length() const noexcept
  {
    return cycle_length_;
  }
 
  [[nodiscard]] std::optional<std::size_t> cycle_start() const noexcept
  {
    return cycle_start_;
  }
 
  [[nodiscard]] std::size_t buffered_hashes() const noexcept
  {
    return hashes_.size();
  }
 
  void reset() noexcept
  {
    hashes_.clear();
    steps_.clear();
    cycle_length_.reset();
    cycle_start_.reset();
  }
 
  template <typename Lattice>
  void on_step_begin(const std::size_t step, const Lattice &frame)
  {
    if (max_cycle_length_ == 0)
      max_cycle_length_ = 16;
    if (step == 0 and hashes_.is_empty())
      push(frame_hash(frame), step);
  }
 
  template <typename Lattice>
  void on_step_end(std::size_t step, const Lattice &frame)
  {
    if (max_cycle_length_ == 0)
      max_cycle_length_ = 16;
    const std::uint64_t h = frame_hash(frame);
 
    if (not cycle_length_.has_value())
      for (std::size_t i = 0; i < hashes_.size(); ++i)
        if (hashes_[i] == h)
          {
            cycle_start_ = steps_[i];
            cycle_length_ = step - steps_[i];
            break;
          }
    push(h, step);
  }
};
 
// ---------------------------------------------------------------------------
// Sampling observer.
// ---------------------------------------------------------------------------
 
template <typename Lattice>
class Sampling_Observer
{
  std::size_t period_ = 1;
  Array<Lattice> snapshots_;
  Array<std::size_t> step_indices_;
 
public:
  Sampling_Observer() = default;
 
  explicit Sampling_Observer(const std::size_t period) : period_(period) {}
 
  [[nodiscard]] const Array<Lattice> &snapshots() const noexcept
  {
    return snapshots_;
  }
 
  [[nodiscard]] const Array<std::size_t> &step_indices() const noexcept
  {
    return step_indices_;
  }
 
  [[nodiscard]] std::size_t size() const noexcept
  {
    return snapshots_.size();
  }
 
  void reset() noexcept
  {
    snapshots_.clear();
    step_indices_.clear();
  }
 
  void on_step_begin(const std::size_t step, const Lattice &frame)
  {
    if (period_ != 0 and step == 0 and snapshots_.is_empty())
      {
        snapshots_.append(frame);
        step_indices_.append(0);
      }
  }
 
  void on_step_end(const std::size_t step, const Lattice &frame)
  {
    if (period_ == 0)
      return;
    if (step % period_ == 0)
      {
        snapshots_.append(frame);
        step_indices_.append(step);
      }
  }
};
 
}  // namespace CA
}  // namespace Aleph
 
#endif  // CA_OBSERVER_H