task.h

Go to the documentation of this file.

//
// SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
// Copyright (C) 2026 by the ryujin authors
//
 
#pragma once
 
#include <ryujin/base/compile_time_options.h>
#include <ryujin/base/convenience_macros.h>
#include <ryujin/base/patterns_conversion.h>
 
#include <deal.II/base/parameter_acceptor.h>
 
#include <boost/archive/binary_iarchive.hpp>
#include <boost/archive/binary_oarchive.hpp>
 
#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <functional>
#include <limits>
#include <span>
#include <string>
#include <vector>
 
namespace ryujin
{
  enum class TaskPhase : std::uint8_t {
    pre_step,
 
    adapt,
 
    step,
 
    post_step,
  };
 
 
  enum class TriggerMode : std::uint8_t {
    every_cycle,
 
    timer_tick,
 
    wall_clock,
 
    time_points,
  };
} // namespace ryujin
 
#ifndef DOXYGEN
DECLARE_ENUM(ryujin::TriggerMode,
             LIST({ryujin::TriggerMode::every_cycle, "every cycle"},
                  {ryujin::TriggerMode::timer_tick, "timer tick"},
                  {ryujin::TriggerMode::wall_clock, "wall clock"},
                  {ryujin::TriggerMode::time_points, "time points"}, ));
#endif
 
namespace ryujin
{
  namespace Interface
  {
    template <typename Number>
    class Task;
  } // namespace Interface
 
 
  template <typename Number = double>
  struct TaskContext {
    bool tick_reached() const
    {
      constexpr Number relax =
          Number(1.) - Number(10.) * std::numeric_limits<Number>::epsilon();
      return t >= relax * timer_cycle * timer_granularity;
    }
 
    Number t = Number(0.);
 
    Number tau = Number(0.);
 
    Number t_max = std::numeric_limits<Number>::max();
 
    unsigned int cycle = 0;
 
    unsigned int timer_cycle = 0;
 
    bool timer_tick = false;
 
    Number wall_time = Number(0.);
 
    Number t_final = Number(0.);
 
    Number timer_granularity = Number(0.);
 
    std::string base_name;
 
    bool prepare_required = false;
 
    std::span<Interface::Task<Number> *const> tasks;
 
    std::function<void(const std::string &)> info;
  };
 
 
  template <typename Number = double>
  class Trigger
  {
  public:
    Trigger(TriggerMode mode = TriggerMode::timer_tick,
            unsigned int multiplier = 1,
            Number interval = Number(0.))
        : mode_(mode)
        , multiplier_(multiplier)
        , interval_(interval)
        , last_fired_(Number(0.))
    {
    }
 
    Trigger(const Trigger &) = delete;
    Trigger &operator=(const Trigger &) = delete;
 
    void add_parameters(dealii::ParameterAcceptor &acceptor,
                        const std::string &prefix = "trigger")
    {
      acceptor.add_parameter(
          prefix,
          mode_,
          "The condition under which the task is executed: every cycle, timer "
          "tick, wall clock, time points");
 
      acceptor.add_parameter(prefix + " multiplier",
                             multiplier_,
                             "Execute only in every n-th cycle (every cycle), "
                             "or at every n-th timer tick (timer tick)");
 
      acceptor.add_parameter(prefix + " interval",
                             interval_,
                             "Execute after the given number of seconds of "
                             "wall time have passed (wall clock)");
 
      acceptor.add_parameter(prefix + " time points",
                             time_points_,
                             "Execute once whenever the time has reached one "
                             "of the given time points (time points)");
 
      acceptor.parse_parameters_call_back.connect([this] {
        std::ranges::sort(time_points_);
        next_time_point_ = std::numeric_limits<std::size_t>::max();
      });
    }
 
    bool fire(const TaskContext<Number> &context)
    {
      switch (mode_) {
      case TriggerMode::every_cycle:
        return context.cycle % multiplier_ == 0;
 
      case TriggerMode::timer_tick:
        return context.timer_tick && context.timer_cycle % multiplier_ == 0;
 
      case TriggerMode::wall_clock:
        if (context.wall_time < last_fired_ + interval_)
          return false;
        last_fired_ = context.wall_time;
        return true;
 
      case TriggerMode::time_points: {
        /* Skip all time points before the first evaluation: */
        if (next_time_point_ == std::numeric_limits<std::size_t>::max()) {
          next_time_point_ = 0;
          while (next_time_point_ < time_points_.size() &&
                 time_points_[next_time_point_] < context.t)
            ++next_time_point_;
        }
 
        bool fire = false;
        while (next_time_point_ < time_points_.size() &&
               time_points_[next_time_point_] <= context.t) {
          ++next_time_point_;
          fire = true;
        }
        return fire;
      }
      }
 
      __builtin_unreachable();
    }
 
  private:
    TriggerMode mode_;
    unsigned int multiplier_;
    Number interval_;
    std::vector<Number> time_points_;
 
    Number last_fired_;
    std::size_t next_time_point_ = std::numeric_limits<std::size_t>::max();
  };
 
 
  namespace Interface
  {
    template <typename Number = double>
    class Task
    {
    public:
      virtual ~Task() = default;
 
 
      virtual void initialize(TaskContext<Number> & /*context*/) {}
 
      virtual void start(TaskContext<Number> & /*context*/) {}
 
      virtual void prepare(TaskContext<Number> & /*context*/) {}
 
 
 
      virtual void execute(TaskContext<Number> &context) = 0;
 
      virtual void finalize(TaskContext<Number> & /*context*/) {}
 
 
 
      virtual void save(boost::archive::binary_oarchive & /*archive*/) const {}
 
      virtual void load(boost::archive::binary_iarchive & /*archive*/) {}
 
 
 
      ACCESSOR_READ_ONLY(name)
 
      
      ACCESSOR_READ_ONLY(phase)
 
      //@}
 
    protected:
      Task(const std::string &name, TaskPhase phase)
          : name_(name)
          , phase_(phase)
      {
      }
 
    private:
      std::string name_;
      TaskPhase phase_;
    };
  } // namespace Interface
} // namespace ryujin