/home/runner/work/OpenPFC/OpenPFC/include/openpfc/time.hpp

Time class to handle simulation time stepping and output intervals.

Time class to handle simulation time stepping and output intervalsThis class provides functionalities to manage time in simulations. It supports time intervals, time increments, and data saving at specific intervals.

The Time class is used by Simulator to orchestrate the time integration loop. It tracks the current simulation time based on time step size (dt) and the number of steps taken (increment), and determines when results should be saved based on the saveat interval.

Key Responsibilities

• Define simulation time span: start time (t0), end time (t1), and time step size (dt)
• Track current time based on number of steps taken: t_current = t0 + increment * dt
• Determine when simulation is complete: t_current >= t1
• Manage output intervals: control when results should be written via saveat
• Provide validation: ensure dt > 0, t0 < t1, and saveat is valid

Design Philosophy

Time follows OpenPFC's "laboratory" philosophy:

• Immutable core: Start time, end time, and time step are const (set at construction)
• Transparent state: Current time is computed from increment (no hidden state)
• Mutable progress: Only the increment counter can be changed (via next())
• Explicit: No automatic time advancement; user controls when next() is called

Usage Pattern

Typical simulation loop:

using namespace pfc;
 
// Create time object: simulate from t=0 to t=10 with dt=0.01, save every 1.0
Time time({0.0, 10.0, 0.01}, 1.0);
 
while (!time.done()) {
    // ... perform time step ...
 
    if (time.do_save()) {
        // ... write results ...
    }
 
    time.next();  // Advance to next time step
}

Basic Time Stepping

using namespace pfc;
 
// Simulate from t=0 to t=1 with dt=0.1
Time time({0.0, 1.0, 0.1}, 0.0);  // No automatic saving (saveat=0)
 
std::cout << "Initial time: " << time.get_current() << "\n";  // 0.0
std::cout << "Time step: " << time.get_dt() << "\n";          // 0.1
std::cout << "End time: " << time.get_t1() << "\n";           // 1.0

// SPDX-FileCopyrightText: 2025 VTT Technical Research Centre of Finland Ltd
// SPDX-License-Identifier: AGPL-3.0-or-later
 
#ifndef PFC_TIME_HPP
#define PFC_TIME_HPP
 
#include <array>
#include <cmath>
#include <iostream>
 
namespace pfc {
 
class Time {
private:
  double m_t0;     
  double m_t1;     
  double m_dt;     
  int m_increment; 
  double m_saveat; 
 
public:
  Time(const std::array<double, 3> &time, double saveat)
      : m_t0(time[0]), m_t1(time[1]), m_dt(time[2]), m_increment(0),
        m_saveat(saveat) {
    if (m_t0 < 0) {
      throw std::invalid_argument("Start time cannot be negative: " +
                                  std::to_string(m_t0));
    }
    if (m_dt <= 0) {
      throw std::invalid_argument("Time step (dt) must be greater than zero: " +
                                  std::to_string(m_dt));
    }
    if (m_dt < 1e-9) {
      throw std::invalid_argument("Time step (dt) is too small: " +
                                  std::to_string(m_dt));
    }
    if (std::abs(m_t0 - m_t1) < 1e-9) {
      throw std::invalid_argument("Start time cannot equal end time: t0 == t1");
    }
    if (m_saveat > m_t1) {
      throw std::invalid_argument(
          "Save interval cannot exceed end time: " + std::to_string(m_saveat) +
          " > " + std::to_string(m_t1));
    }
  }
 
  Time(const std::array<double, 3> &time) : Time(time, time[2]) {}
 
  double get_t0() const { return m_t0; }
 
  double get_t1() const { return m_t1; }
 
  double get_dt() const { return m_dt; }
 
  int get_increment() const { return m_increment; }
 
  double get_current() const {
    double current_time = m_t0 + m_increment * m_dt;
    return (current_time > m_t1) ? m_t1
                                 : current_time; // Clamp to m_t1 if it exceeds
  }
 
  double get_saveat() const { return m_saveat; }
 
  void set_increment(int increment) { m_increment = increment; }
 
  void set_saveat(double saveat) { m_saveat = saveat; }
 
  bool done() const {
    return (get_current() >= m_t1 - 1e-9); // Adjust for floating-point precision
  }
 
  void next() { m_increment += 1; }
 
  bool do_save() const {
    if (m_saveat <= 0) {
      return false; // Save interval of 0 means no saving
    }
    return (std::fmod(get_current() + 1.0e-9, m_saveat) < 1.e-6) || done() ||
           (m_increment == 0);
  }
 
  operator double() const { return get_current(); }
 
  friend std::ostream &operator<<(std::ostream &os, const Time &t) {
    os << "(t0 = " << t.m_t0 << ", t1 = " << t.m_t1 << ", dt = " << t.m_dt;
    os << ", saveat = " << t.m_saveat << ", t_current = " << t.get_current()
       << ")\n";
    return os;
  };
};
 
} // namespace pfc
 
#endif