TimeCoordinator.hpp

/*
Copyright (c) 2017-2026,
Battelle Memorial Institute; Lawrence Livermore National Security, LLC; Alliance for Energy
Innovation LLC.  See the top-level NOTICE for additional details. All rights reserved.
SPDX-License-Identifier: BSD-3-Clause
*/
#pragma once
 
#include "../common/GuardedTypes.hpp"
#include "ActionMessage.hpp"
#include "BaseTimeCoordinator.hpp"
 
#include <atomic>
#include <functional>
#include <nlohmann/json_fwd.hpp>
#include <string>
#include <utility>
#include <vector>
 
namespace helics {
 
class tcoptions {
  public:
    Time timeDelta = Time::epsilon();
    Time inputDelay = timeZero;
    Time outputDelay = timeZero;
    Time offset = timeZero;
    Time period = timeZero;
    // Time rtLag = timeZero;
    // Time rtLead = timeZero;
    // bool observer = false;
    // bool realtime = false;
    // bool source_only = false;
    bool wait_for_current_time_updates = false;
    bool uninterruptible = false;
    bool restrictive_time_policy = false;
    bool event_triggered = false;
    int maxIterations = 50;
};
 
class TimeCoordinator: public BaseTimeCoordinator {
  protected:
    TimeData upstream;
    TimeData total;
    mutable TimeData lastSend;
    // the variables for time coordination
    Time time_granted{Time::minVal()};  
    Time time_requested{Time::maxVal()};  
    Time time_next{timeZero};  
    Time time_minminDe{timeZero};  
    Time time_minDe{timeZero};  
    Time time_allow{Time::minVal()};  
    Time time_exec{Time::maxVal()};  
    Time time_message{Time::maxVal()};  
    Time time_value{Time::maxVal()};  
    Time time_grantBase{Time::minVal()};
    Time time_block{Time::maxVal()};
    Time maxTime{Time::maxVal()};
    shared_guarded_m<std::vector<GlobalFederateId>> dependent_federates;
    shared_guarded_m<std::vector<GlobalFederateId>> dependency_federates;
    std::vector<std::pair<Time, int32_t>> timeBlocks;
    tcoptions info;
    std::uint8_t currentRestrictionLevel{0};
 
  public:
    IterationRequest iterating{IterationRequest::NO_ITERATIONS};
 
    bool hasInitUpdates{false};
    bool hasIterationData{false};
    bool needSendAll{false};
    mutable bool triggered{false};
    bool globalTime{false};
 
  protected:
    bool dynamicJoining{false};
 
    std::atomic<int32_t> iteration{0};  
 
  public:
    TimeCoordinator() = default;
    explicit TimeCoordinator(std::function<void(const ActionMessage&)> userSendMessageFunction):
        BaseTimeCoordinator(std::move(userSendMessageFunction))
    {
    }
 
    void setProperty(int timeProperty, Time propertyVal);
    void setProperty(int intProperty, int propertyVal);
    void setOptionFlag(int optionFlag, bool value);
    void setDynamicJoining() { dynamicJoining = true; }
 
    Time getTimeProperty(int timeProperty) const;
    bool getOptionFlag(int optionFlag) const;
    int getIntegerProperty(int intProperty) const;
 
    Time getGrantedTime() const { return time_granted; }
    Time getRequestedTime() const { return time_requested; }
    Time allowedSendTime() const { return time_granted + info.outputDelay; }
    std::vector<GlobalFederateId> getDependencies() const;
    std::vector<GlobalFederateId> getDependents() const
    {
        return *dependent_federates.lock_shared();
    }
    const auto& getBarriers() const { return timeBlocks; }
    int32_t getCurrentIteration() const { return iteration.load(); }
    virtual bool updateTimeFactors() override;
    void updateValueTime(Time valueUpdateTime, bool allowRequestSend);
    void updateMessageTime(Time messageUpdateTime, bool allowRequestSend);
 
    void specifyNonGranting(bool value = true) { nonGranting = value; }
 
  private:
    bool updateNextExecutionTime();
    void updateNextPossibleEventTime();
    Time getNextPossibleTime() const;
    Time generateAllowedTime(Time testTime) const;
    /* return true,true if the message was sent and skip federate was detected
    true,false if the message was sent and skip federate was not detected
    false,false, if the message was not sent
    */
    std::pair<bool, bool> checkAndSendTimeRequest(ActionMessage& upd, GlobalFederateId skip) const;
 
    void sendTimeRequest(GlobalFederateId triggerFed) const;
    void updateTimeGrant();
    bool transmitTimingMessages(ActionMessage& msg,
                                GlobalFederateId skipFed = GlobalFederateId{}) const;
 
    TimeProcessingResult processTimeBlockMessage(const ActionMessage& cmd);
 
    Time updateTimeBlocks(int32_t blockId, Time newTime);
 
  public:
    virtual TimeProcessingResult processTimeMessage(const ActionMessage& cmd) override;
 
    void processConfigUpdateMessage(const ActionMessage& cmd);
    virtual bool addDependency(GlobalFederateId fedID) override;
    virtual bool addDependent(GlobalFederateId fedID) override;
    virtual void removeDependency(GlobalFederateId fedID) override;
    virtual void removeDependent(GlobalFederateId fedID) override;
 
    virtual MessageProcessingResult
        checkExecEntry(GlobalFederateId triggerFed = GlobalFederateId{}) override;
 
    void sendUpdatedExecRequest(GlobalFederateId target = GlobalFederateId{},
                                GlobalFederateId minFed = GlobalFederateId{},
                                std::int32_t responseSequenceCounter = 0);
    void timeRequest(Time nextTime,
                     IterationRequest iterate,
                     Time newValueTime,
                     Time newMessageTime);
 
    virtual void enteringExecMode(IterationRequest mode) override;
    MessageProcessingResult checkTimeGrant(GlobalFederateId triggerFed = GlobalFederateId{});
    void localError();
    virtual std::string printTimeStatus() const override;
    void generateConfig(nlohmann::json& base) const;
 
    virtual void generateDebuggingTimeInfo(nlohmann::json& base) const override;
 
    std::pair<GlobalFederateId, Time> getMinGrantedDependency() const;
    void enterInitialization();
    void requestTimeCheck();
 
    virtual Time getNextTime() const override;
};
 
}  // namespace helics