history.hpp

 
// File: history.hpp                                                          //
// Project: respond                                                           //
// Created Date: 2026-02-05                                                   //
// Author: Matthew Carroll                                                    //
// -----                                                                      //
// Last Modified: 2026-07-13                                                  //
// Modified By: Matthew Carroll                                               //
// -----                                                                      //
// Copyright (c) 2026 Syndemics Lab at Boston Medical Center                  //
#ifndef RESPOND_HISTORY_HPP_
#define RESPOND_HISTORY_HPP_
 
#include <respond/constants.hpp>
#include <respond/logging.hpp>
 
#include <algorithm>
#include <map>
#include <utility>
#include <vector>
 
#include <Eigen/Dense>
 
namespace respond {
 
enum class HistoryMode : int {
    kSnapshot = 0,    // Snapshot of state at each timestep
    kAccumulated = 1, // Accumulated contributions over timesteps
    kCount = 2        // Enum Counter
};
 
inline HistoryMode GetDefaultHistoryMode(const std::string &name) {
    if (name == "intervention_admission" || name == "total_overdose" ||
        name == "fatal_overdose" || name == "background_death") {
        return HistoryMode::kAccumulated;
    }
    return HistoryMode::kSnapshot;
}
 
class History {
public:
    //
    // Rule of Five: Copy and Move Semantics
    //
 
    History() : History("state") {}
 
    History(const std::string &name)
        : History(name, GetDefaultHistoryMode(name)) {}
 
    History(const std::string &name, const HistoryMode &mode)
        : History(name, mode, RESPOND_DEFAULT_LOG, RESPOND_DEFAULT_LOG_FILE) {}
 
    History(const std::string &name, const HistoryMode &mode,
            const std::string &log_name)
        : History(name, mode, log_name, RESPOND_DEFAULT_LOG_FILE) {}
 
    History(const std::string &name, const std::string &log_name)
        : History(name, GetDefaultHistoryMode(name), log_name,
                  RESPOND_DEFAULT_LOG_FILE) {}
 
    History(const std::string &name, const std::string &log_name,
            const std::string &log_filepath)
        : History(name, GetDefaultHistoryMode(name), log_name, log_filepath) {}
 
    History(const std::string &name, const HistoryMode &mode,
            const std::string &log_name, const std::string &log_filepath)
        : _name(name), _mode(mode), _log_name(log_name) {
        CreateFileLogger(log_name, log_filepath);
    }
 
    ~History() = default;
 
    History(const History &other) {
        _timesteps = other.GetRecordedTimesteps();
        _states = other.GetRecordedStates();
        _name = other._name;
        _log_name = other._log_name;
        _mode = other._mode;
        _pending_state = other.GetPendingState();
    }
 
    History &operator=(const History &other) {
        if (this != &other) {
            _timesteps = other.GetRecordedTimesteps();
            _states = other.GetRecordedStates();
            _name = other._name;
            _log_name = other._log_name;
            _mode = other._mode;
            _pending_state = other.GetPendingState();
        }
        return *this;
    }
 
    History(History &&other) noexcept {
        _timesteps = std::move(other._timesteps);
        _states = std::move(other._states);
        _name = other._name;
        _log_name = other._log_name;
        _mode = other._mode;
        _pending_state = std::move(other._pending_state);
    }
 
    History &operator=(History &&other) noexcept {
        if (this != &other) {
            _timesteps = std::move(other._timesteps);
            _states = std::move(other._states);
            _name = other._name;
            _log_name = other._log_name;
            _mode = other._mode;
            _pending_state = std::move(other._pending_state);
        }
        return *this;
    }
 
    //
    // History Methods: State Vector Management
    //
 
    void AddState(const Eigen::Ref<const Eigen::VectorXd> &state,
                  int timestep = -1) {
        if (timestep < 0) {
            timestep = GetNextTimestep();
        }
 
        const auto existing =
            std::find(_timesteps.begin(), _timesteps.end(), timestep);
        if (existing != _timesteps.end()) {
            const auto index =
                static_cast<size_t>(existing - _timesteps.begin());
            _states[index] = state;
            return;
        }
 
        _timesteps.push_back(timestep);
        _states.push_back(state);
    }
 
    void AccumulateState(const Eigen::Ref<const Eigen::VectorXd> &state) {
        if (_mode != HistoryMode::kAccumulated) {
            LogWarning(_log_name, "AccumulateState called on non-accumulated "
                                  "history, adding state instead: " +
                                      _name);
            AddState(state);
            return;
        }
 
        if (_pending_state.size() == 0) {
            _pending_state = state;
            return;
        }
        _pending_state += state;
    }
 
    void FlushPendingState(int timestep, Eigen::Index state_size) {
        if (_mode != HistoryMode::kAccumulated) {
            LogInfo(_log_name,
                    "FlushPendingState called on non-accumulated history, "
                    "no pending state to flush: " +
                        _name);
            return;
        }
 
        Eigen::VectorXd value;
        if (_pending_state.size() > 0) {
            value = _pending_state;
        } else {
            LogInfo(_log_name,
                    "FlushPendingState called with no pending state, "
                    "recording zero vector: " +
                        _name);
            value = Eigen::VectorXd::Zero(state_size);
        }
 
        AddState(value, timestep);
        _pending_state.resize(0);
    }
 
    void Clear() {
        _timesteps.clear();
        _states.clear();
        _pending_state.resize(0);
    }
 
    bool HasPendingState() const { return _pending_state.size() > 0; }
 
    //
    // Getters and Setters for History Vectors
    //
 
    std::map<int, Eigen::VectorXd> GetStateMap() const {
        std::map<int, Eigen::VectorXd> state_map;
        for (size_t index = 0; index < _timesteps.size(); ++index) {
            state_map[_timesteps[index]] = _states[index];
        }
        return state_map;
    }
 
    const std::vector<int> &GetRecordedTimesteps() const { return _timesteps; }
 
    const std::vector<Eigen::VectorXd> &GetRecordedStates() const {
        return _states;
    }
 
    HistoryMode GetHistoryMode() const { return _mode; }
 
    Eigen::VectorXd GetPendingState() const { return _pending_state; }
 
    int GetLatestRecordedTimestep() const {
        if (_timesteps.empty()) {
            LogWarning(_log_name,
                       "GetLatestRecordedTimestep called on empty history: " +
                           _name);
            return -1;
        }
        return _timesteps.back();
    }
 
    std::string GetName() const { return _name; }
 
    std::vector<Eigen::VectorXd> GetStateAsVector() const {
        std::vector<Eigen::VectorXd> ret;
        if (_states.empty()) {
            LogWarning(_log_name,
                       "GetStateAsVector called on empty history: " + _name);
            return {};
        }
        int default_size = _states.front().size();
        int tstep = 0;
        for (size_t index = 0; index < _timesteps.size(); ++index) {
            const int recorded_timestep = _timesteps[index];
            const auto &recorded_state = _states[index];
            while (recorded_timestep > tstep) {
                ret.push_back(GetZeroVector(default_size));
                tstep++;
            }
            ret.push_back(recorded_state);
            tstep++;
        }
        return ret;
    }
 
    //
    // Operator Comparisons and Stream Output
    //
 
    bool operator==(const History &other) const {
        return _name == other._name && _log_name == other._log_name &&
               _mode == other._mode && GetStateMap() == other.GetStateMap() &&
               GetPendingState().isApprox(other.GetPendingState());
    }
 
    bool operator!=(const History &other) const { return !(*this == other); }
 
    friend std::ostream &operator<<(std::ostream &os, const History &history) {
        os << "History(name=" << history._name << ", timesteps=[";
        for (const auto &t : history._timesteps) {
            os << t << ",";
        }
        os << "], pending_state=" << history._pending_state.transpose() << ")";
        return os;
    }
 
private:
    std::string _log_name;
    std::string _name;
    HistoryMode _mode;
    std::vector<int> _timesteps;
    std::vector<Eigen::VectorXd> _states;
    Eigen::VectorXd _pending_state;
 
    int GetNextTimestep() {
        if (_timesteps.empty()) {
            return 0;
        }
        return _timesteps.back() + 1;
    }
 
    Eigen::VectorXd GetZeroVector(const int &size) const {
        return Eigen::VectorXd::Zero(size);
    }
};
} // namespace respond
 
#endif // RESPOND_HISTORY_HPP_