helics  3.0.1
TimeCoordinator.hpp
1 /*
2 Copyright (c) 2017-2021,
3 Battelle Memorial Institute; Lawrence Livermore National Security, LLC; Alliance for Sustainable
4 Energy, LLC. See the top-level NOTICE for additional details. All rights reserved.
5 SPDX-License-Identifier: BSD-3-Clause
6 */
7 #pragma once
8 
9 #include "../common/GuardedTypes.hpp"
10 #include "ActionMessage.hpp"
11 #include "TimeDependencies.hpp"
12 
13 #include "json/forwards.h"
14 #include <atomic>
15 #include <functional>
16 #include <string>
17 #include <utility>
18 #include <vector>
19 
20 namespace helics {
21 
24  no_effect = 0,
25  processed,
27 };
28 
30 class tcoptions {
31  public:
32  Time timeDelta = Time::epsilon();
33  Time inputDelay = timeZero;
34  Time outputDelay = timeZero;
35  Time offset = timeZero;
36  Time period = timeZero;
37  // Time rtLag = timeZero;
38  // Time rtLead = timeZero;
39  // bool observer = false;
40  // bool realtime = false;
41  // bool source_only = false;
42  bool wait_for_current_time_updates = false;
43  bool uninterruptible = false;
44  bool restrictive_time_policy = false;
47  bool event_triggered = false;
48  int maxIterations = 50;
49 };
50 
56  protected:
59  TimeData total;
60  mutable TimeData lastSend;
61  // the variables for time coordination
62  Time time_granted{Time::minVal()};
63  Time time_requested{Time::maxVal()};
67  Time time_allow{Time::minVal()};
68  Time time_exec{Time::maxVal()};
69  Time time_message{Time::maxVal()};
70  Time time_value{Time::maxVal()};
71 
73  Time time_grantBase{Time::minVal()};
75  Time time_block{Time::maxVal()};
76  Time maxTime{Time::maxVal()};
84  std::vector<std::pair<Time, int32_t>> timeBlocks;
88  std::function<void(const ActionMessage&)> sendMessageFunction;
89 
90  public:
96  bool checkingExec{false};
98  bool executionMode{false};
100  bool hasInitUpdates{false};
101 
102  protected:
103  std::atomic<int32_t> iteration{0};
104  bool disconnected{false};
107  bool nonGranting{false};
109  bool dynamicJoining{false};
110 
111  public:
113  TimeCoordinator();
115  explicit TimeCoordinator(std::function<void(const ActionMessage&)> userSendMessageFunction);
116 
118  void setProperty(int timeProperty, Time propertyVal);
120  void setProperty(int intProperty, int propertyVal);
122  void setOptionFlag(int optionFlag, bool value);
125 
127  Time getTimeProperty(int timeProperty) const;
129  bool getOptionFlag(int optionFlag) const;
131  int getIntegerProperty(int intProperty) const;
133  void setMessageSender(std::function<void(const ActionMessage&)> userSendMessageFunction);
134 
136  Time getGrantedTime() const { return time_granted; }
138  Time allowedSendTime() const { return time_granted + info.outputDelay; }
140  std::vector<GlobalFederateId> getDependencies() const;
142  std::vector<GlobalFederateId> getDependents() const
143  {
144  return *dependent_federates.lock_shared();
145  }
149  int32_t getCurrentIteration() const { return iteration.load(); }
153  bool updateTimeFactors();
157  void updateValueTime(Time valueUpdateTime, bool allowRequestSend);
161  void updateMessageTime(Time messageUpdateTime, bool allowRequestSend);
162 
163  void specifyNonGranting(bool value = true) { nonGranting = value; }
165  GlobalFederateId getMinDependency() const;
166 
167  private:
171  DependencyInfo* getDependencyInfo(GlobalFederateId ofed);
173  bool isDependency(GlobalFederateId ofed) const;
174 
175  private:
177  bool updateNextExecutionTime();
180  void updateNextPossibleEventTime();
182  Time getNextPossibleTime() const;
183  Time generateAllowedTime(Time testTime) const;
184  /* return true if the skip federate was detected*/
185  bool checkAndSendTimeRequest(ActionMessage& upd, GlobalFederateId skip) const;
186 
187  void sendTimeRequest() const;
188  void updateTimeGrant();
190  bool transmitTimingMessages(ActionMessage& msg,
191  GlobalFederateId skipFed = GlobalFederateId{}) const;
192 
193  message_process_result processTimeBlockMessage(const ActionMessage& cmd);
194 
195  Time updateTimeBlocks(int32_t blockId, Time newTime);
196 
197  public:
201  message_process_result processTimeMessage(const ActionMessage& cmd);
202 
206  void processConfigUpdateMessage(const ActionMessage& cmd);
208  void processDependencyUpdateMessage(const ActionMessage& cmd);
212  bool addDependency(GlobalFederateId fedID);
216  bool addDependent(GlobalFederateId fedID);
219  void removeDependency(GlobalFederateId fedID);
222  void removeDependent(GlobalFederateId fedID);
223 
224  void setAsChild(GlobalFederateId fedID);
225 
226  void setAsParent(GlobalFederateId fedID);
235  void timeRequest(Time nextTime,
236  IterationRequest iterate,
237  Time newValueTime,
238  Time newMessageTime);
246  void disconnect();
248  void localError();
250  std::string printTimeStatus() const;
252  bool hasActiveTimeDependencies() const;
254  void generateConfig(Json::Value& base) const;
255 
257  void generateDebuggingTimeInfo(Json::Value& base) const;
258 
260  int dependencyCount() const;
262  std::pair<GlobalFederateId, Time> getMinGrantedDependency() const;
264  void enterInitialization();
266  void requestTimeCheck();
267 };
268 } // namespace helics
helics::timeZero
constexpr Time timeZero
Definition: helicsTime.hpp:31
helics::TimeCoordinator::processConfigUpdateMessage
void processConfigUpdateMessage(const ActionMessage &cmd)
Definition: TimeCoordinator.cpp:1197
helics::TimeCoordinator::enterInitialization
void enterInitialization()
Definition: TimeCoordinator.cpp:367
helics::TimeCoordinator::nonGranting
bool nonGranting
Definition: TimeCoordinator.hpp:107
helics::message_process_result::processed
@ processed
the message was used to update the current state
helics::TimeDependencies::resetIteratingTimeRequests
void resetIteratingTimeRequests(Time requestTime)
Definition: TimeDependencies.cpp:422
helics::GlobalFederateId::baseValue
constexpr BaseType baseValue() const
Definition: GlobalFederateId.hpp:80
delayed_timing_flag
constexpr uint16_t delayed_timing_flag
overload of extra_flag2 to indicate the request is from federate with delayed timing
Definition: flagOperations.hpp:65
helics::TimeCoordinator::getGrantedTime
Time getGrantedTime() const
Definition: TimeCoordinator.hpp:136
helics::TimeCoordinator::hasInitUpdates
bool hasInitUpdates
flag indicating that a value or message was received during initialization stage
Definition: TimeCoordinator.hpp:100
helics::TimeCoordinator::requestTimeCheck
void requestTimeCheck()
Definition: TimeCoordinator.cpp:385
helics::message_process_result::delay_processing
@ delay_processing
the message should be delayed and reprocessed later
helics::TimeDependencies::removeDependent
void removeDependent(GlobalFederateId id)
Definition: TimeDependencies.cpp:303
helics::TimeCoordinator::timeRequest
void timeRequest(Time nextTime, IterationRequest iterate, Time newValueTime, Time newMessageTime)
Definition: TimeCoordinator.cpp:143
helics::GlobalFederateId::isValid
bool isValid() const
Definition: GlobalFederateId.hpp:105
helics::TimeCoordinator::processDependencyUpdateMessage
void processDependencyUpdateMessage(const ActionMessage &cmd)
Definition: TimeCoordinator.cpp:1054
helics::TimeCoordinator::dependent_federates
shared_guarded_m< std::vector< GlobalFederateId > > dependent_federates
these are to maintain an accessible record of dependent federates
Definition: TimeCoordinator.hpp:78
helics::TimeCoordinator::setMessageSender
void setMessageSender(std::function< void(const ActionMessage &)> userSendMessageFunction)
Definition: TimeCoordinator.cpp:36
helics::TimeCoordinator::executionMode
bool executionMode
flag that the coordinator has entered the execution Mode
Definition: TimeCoordinator.hpp:98
helics::TimeDependencies
Definition: TimeDependencies.hpp:75
helics_definitions.hpp
base helics enumerations for C++ API's, a namespace wrapper for the definitions defined in helics_enu...
helics::TimeDependencies::getMinDependency
GlobalFederateId getMinDependency() const
Definition: TimeDependencies.cpp:363
helics::TimeCoordinator::source_id
GlobalFederateId source_id
the identifier for inserting into the source id field of any generated messages;
Definition: TimeCoordinator.hpp:92
helics::TimeCoordinator::removeDependency
void removeDependency(GlobalFederateId fedID)
Definition: TimeCoordinator.cpp:758
helics::TimeDependencies::removeDependency
void removeDependency(GlobalFederateId id)
Definition: TimeDependencies.cpp:265
helics::TimeDependencies::resetDependentEvents
void resetDependentEvents(Time grantTime)
Definition: TimeDependencies.cpp:435
helics::TimeCoordinator::timeBlocks
std::vector< std::pair< Time, int32_t > > timeBlocks
blocks for a particular timeblocking link
Definition: TimeCoordinator.hpp:84
helics::TimeCoordinator::printTimeStatus
std::string printTimeStatus() const
Definition: TimeCoordinator.cpp:692
helics::TimeData
Definition: TimeDependencies.hpp:36
helics::TimeCoordinator::time_minminDe
Time time_minminDe
the minimum of the minimum dependency event Time
Definition: TimeCoordinator.hpp:65
helics::Time
TimeRepresentation< count_time< 9 > > Time
Definition: helicsTime.hpp:27
helics::TimeCoordinator::time_next
Time time_next
the next possible internal event time
Definition: TimeCoordinator.hpp:64
helics::TimeData::Te
Time Te
the next currently scheduled event
Definition: TimeDependencies.hpp:39
helics::TimeCoordinator::time_block
Time time_block
a blocking time to not grant time >= the specified time
Definition: TimeCoordinator.hpp:75
helics::GlobalFederateId
Definition: GlobalFederateId.hpp:68
helics::ActionMessage
Definition: ActionMessage.hpp:30
helics::parent_broker_id
constexpr GlobalBrokerId parent_broker_id
Definition: GlobalFederateId.hpp:60
helics::message_process_result
message_process_result
Definition: TimeCoordinator.hpp:23
helics::TimeDependencies::isDependency
bool isDependency(GlobalFederateId ofed) const
Definition: TimeDependencies.cpp:202
helics::TimeCoordinator::processTimeMessage
message_process_result processTimeMessage(const ActionMessage &cmd)
Definition: TimeCoordinator.cpp:924
helics::TimeDependencies::resetIteratingExecRequests
void resetIteratingExecRequests()
Definition: TimeDependencies.cpp:378
iteration_requested_flag
@ iteration_requested_flag
indicator that an iteration has been requested
Definition: flagOperations.hpp:16
helics::TimeDependencies::checkIfReadyForTimeGrant
bool checkIfReadyForTimeGrant(bool iterating, Time desiredGrantTime) const
Definition: TimeDependencies.cpp:387
helics::appendMessage
int appendMessage(ActionMessage &m, const ActionMessage &newMessage)
Definition: ActionMessage.cpp:919
helics::ActionMessage::counter
uint16_t counter
26 counter for filter tracking or message counter
Definition: ActionMessage.hpp:41
helics::IterationRequest::FORCE_ITERATION
@ FORCE_ITERATION
force an iteration whether it is needed or not
helics::TimeCoordinator::time_granted
Time time_granted
the most recent time granted
Definition: TimeCoordinator.hpp:62
checkActionFlag
bool checkActionFlag(uint16_t flags, FlagIndex flag)
Definition: flagOperations.hpp:85
helics::TimeDependencies::size
auto size() const
Definition: TimeDependencies.hpp:100
helics::TimeCoordinator::time_value
Time time_value
the time of the earliest value event
Definition: TimeCoordinator.hpp:70
helics::MessageProcessingResult::ITERATING
@ ITERATING
indicator that the iterations need to continue
helics::TimeCoordinator::disconnect
void disconnect()
Definition: TimeCoordinator.cpp:63
helics::TimeCoordinator::dynamicJoining
bool dynamicJoining
if set to true the time coordinator is joining an ongoing co-simulation
Definition: TimeCoordinator.hpp:109
helics::TimeCoordinator::getOptionFlag
bool getOptionFlag(int optionFlag) const
Definition: TimeCoordinator.cpp:1179
child_flag
constexpr uint16_t child_flag
overload of extra_flag4 indicating a message is from a child object
Definition: flagOperations.hpp:49
helics::TimeData::next
Time next
next possible message or value
Definition: TimeDependencies.hpp:38
helics::TimeData::TeAlt
Time TeAlt
the second min event
Definition: TimeDependencies.hpp:41
helics::TimeDependencies::activeDependencyCount
int activeDependencyCount() const
Definition: TimeDependencies.cpp:356
helics::tcoptions::event_triggered
bool event_triggered
Definition: TimeCoordinator.hpp:47
helics::TimeDependencies::updateTime
bool updateTime(const ActionMessage &m)
Definition: TimeDependencies.cpp:326
helics::tcoptions
Definition: TimeCoordinator.hpp:30
helics::TimeCoordinator::updateMessageTime
void updateMessageTime(Time messageUpdateTime, bool allowRequestSend)
Definition: TimeCoordinator.cpp:453
helics::TimeCoordinator::setOptionFlag
void setOptionFlag(int optionFlag, bool value)
Definition: TimeCoordinator.cpp:1129
helics::IterationRequest
IterationRequest
Definition: CoreTypes.hpp:89
helics::TimeCoordinator::time_allow
Time time_allow
the current allowable time
Definition: TimeCoordinator.hpp:67
helics::TimeDependencies::getDependencyInfo
const DependencyInfo * getDependencyInfo(GlobalFederateId id) const
Definition: TimeDependencies.cpp:220
helics::ActionMessage::messageID
int32_t messageID
8 – message ID for a variety of purposes
Definition: ActionMessage.hpp:36
helics::TimeCoordinator::iteration
std::atomic< int32_t > iteration
iteration counter
Definition: TimeCoordinator.hpp:103
helics::TimeCoordinator::hasActiveTimeDependencies
bool hasActiveTimeDependencies() const
Definition: TimeCoordinator.cpp:351
helics::TimeCoordinator::getMinGrantedDependency
std::pair< GlobalFederateId, Time > getMinGrantedDependency() const
Definition: TimeCoordinator.cpp:906
helics::ActionMessage::setExtraData
void setExtraData(int32_t data)
Definition: ActionMessage.hpp:157
helics::TimeDependencies::begin
auto begin()
Definition: TimeDependencies.hpp:102
helics::TimeCoordinator::checkTimeGrant
MessageProcessingResult checkTimeGrant()
Definition: TimeCoordinator.cpp:524
indicator_flag
@ indicator_flag
flag used for setting values
Definition: flagOperations.hpp:21
helics::TimeCoordinator::updateTimeFactors
bool updateTimeFactors()
Definition: TimeCoordinator.cpp:485
non_granting_flag
constexpr uint16_t non_granting_flag
overload of extra_flag1 to indicate the request is from a non-granting federate
Definition: flagOperations.hpp:62
helics::TimeCoordinator::dependencies
TimeDependencies dependencies
federates which this Federate is temporally dependent on
Definition: TimeCoordinator.hpp:82
helics::TimeCoordinator::addDependency
bool addDependency(GlobalFederateId fedID)
Definition: TimeCoordinator.cpp:711
helics::IterationRequest::ITERATE_IF_NEEDED
@ ITERATE_IF_NEEDED
indicator that the iterations need to continue
setActionFlag
void setActionFlag(FlagContainer &M, FlagIndex flag)
Definition: flagOperations.hpp:77
helics::TimeCoordinator::time_minDe
Time time_minDe
the minimum event time of the dependencies
Definition: TimeCoordinator.hpp:66
helics::ActionMessage::payload
SmallBuffer payload
buffer to contain the data payload
Definition: ActionMessage.hpp:48
helics::ActionMessage::dest_id
GlobalFederateId dest_id
20 fed_id for a targeted message
Definition: ActionMessage.hpp:39
helics::TimeCoordinator::updateValueTime
void updateValueTime(Time valueUpdateTime, bool allowRequestSend)
Definition: TimeCoordinator.cpp:249
helics::TimeCoordinator::TimeCoordinator
TimeCoordinator()
Definition: TimeCoordinator.cpp:26
helics::ActionMessage::Te
Time Te
48 event time
Definition: ActionMessage.hpp:45
helics::TimeCoordinator::checkExecEntry
MessageProcessingResult checkExecEntry()
Definition: TimeCoordinator.cpp:806
helics::TimeDependencies::addDependency
bool addDependency(GlobalFederateId id)
Definition: TimeDependencies.cpp:240
helics::TimeCoordinator::getMinDependency
GlobalFederateId getMinDependency() const
Definition: TimeCoordinator.cpp:362
helics::DependencyInfo
Definition: TimeDependencies.hpp:53
helics::TimeCoordinator::dependencyCount
int dependencyCount() const
Definition: TimeCoordinator.cpp:356
helics::TimeCoordinator
Definition: TimeCoordinator.hpp:55
helics::TimeCoordinator::time_exec
Time time_exec
the time of the next targeted execution
Definition: TimeCoordinator.hpp:68
helics::TimeCoordinator::getTimeProperty
Time getTimeProperty(int timeProperty) const
Definition: TimeCoordinator.cpp:1149
helics::TimeCoordinator::checkingExec
bool checkingExec
flag indicating that the coordinator is trying to enter the exec mode
Definition: TimeCoordinator.hpp:96
helics::MessageProcessingResult::ERROR_RESULT
@ ERROR_RESULT
indicator that an error has occurred
parent_flag
constexpr uint16_t parent_flag
overload of extra_flag3 indicating the message is from a parent object
Definition: flagOperations.hpp:46
helics::ActionMessage::getExtraData
int32_t getExtraData() const
Definition: ActionMessage.hpp:159
helics::TimeCoordinator::time_message
Time time_message
the time of the earliest message event
Definition: TimeCoordinator.hpp:69
helics::TimeCoordinator::setProperty
void setProperty(int timeProperty, Time propertyVal)
Definition: TimeCoordinator.cpp:1092
helics::TimeCoordinator::time_grantBase
Time time_grantBase
Definition: TimeCoordinator.hpp:73
helics::ActionMessage::Tdemin
Time Tdemin
56 min dependent event time
Definition: ActionMessage.hpp:46
helics::TimeCoordinator::enteringExecMode
void enteringExecMode(IterationRequest mode)
Definition: TimeCoordinator.cpp:45
helics::ActionMessage::actionTime
Time actionTime
40 the time an action took place or will take place //32
Definition: ActionMessage.hpp:44
helics::TimeDependencies::addDependent
bool addDependent(GlobalFederateId id)
Definition: TimeDependencies.cpp:278
helics::TimeCoordinator::setDynamicJoining
void setDynamicJoining()
Definition: TimeCoordinator.hpp:124
helics::message_process_result::no_effect
@ no_effect
the message did not result in an update
helics::TimeDependencies::checkIfReadyForExecEntry
bool checkIfReadyForExecEntry(bool iterating) const
Definition: TimeDependencies.cpp:337
helics
the main namespace for the helics co-simulation library User functions will be in the helics namespac...
Definition: AsyncFedCallInfo.hpp:14
helics::TimeCoordinator::getIntegerProperty
int getIntegerProperty(int intProperty) const
Definition: TimeCoordinator.cpp:1168
helics::TimeDependencies::hasActiveTimeDependencies
bool hasActiveTimeDependencies() const
Definition: TimeDependencies.cpp:349
helics::TimeCoordinator::getDependencies
std::vector< GlobalFederateId > getDependencies() const
Definition: TimeCoordinator.cpp:785
helics::TimeCoordinator::generateDebuggingTimeInfo
void generateDebuggingTimeInfo(Json::Value &base) const
Definition: TimeCoordinator.cpp:305
helics::TimeData::minDe
Time minDe
min dependency event time
Definition: TimeDependencies.hpp:40
helics::TimeCoordinator::dependency_federates
shared_guarded_m< std::vector< GlobalFederateId > > dependency_federates
these are to maintain an accessible record of dependency federates
Definition: TimeCoordinator.hpp:80
helics::TimeCoordinator::addDependent
bool addDependent(GlobalFederateId fedID)
Definition: TimeCoordinator.cpp:727
helics::TimeCoordinator::time_requested
Time time_requested
the most recent time requested
Definition: TimeCoordinator.hpp:63
helics::TimeCoordinator::upstream
TimeData upstream
the variables for time coordination
Definition: TimeCoordinator.hpp:58
helics::TimeCoordinator::getDependents
std::vector< GlobalFederateId > getDependents() const
Definition: TimeCoordinator.hpp:142
gmlc::libguarded::shared_guarded
Definition: application_api/Federate.hpp:28
helics::timeEpsilon
constexpr Time timeEpsilon
Definition: helicsTime.hpp:33
helics::TimeCoordinator::iterating
IterationRequest iterating
indicator that the coordinator should be iteratingif need be
Definition: TimeCoordinator.hpp:94
helics::MessageProcessingResult::CONTINUE_PROCESSING
@ CONTINUE_PROCESSING
the current loop should continue
helics::MessageProcessingResult::HALTED
@ HALTED
indicator that the simulation has been halted
helics::TimeCoordinator::info
tcoptions info
basic time control information
Definition: TimeCoordinator.hpp:86
helics::TimeDependencies::empty
bool empty() const
Definition: TimeDependencies.hpp:115
helics::TimeCoordinator::sendMessageFunction
std::function< void(const ActionMessage &)> sendMessageFunction
callback used to send the messages
Definition: TimeCoordinator.hpp:88
helics::TimeCoordinator::getCurrentIteration
int32_t getCurrentIteration() const
Definition: TimeCoordinator.hpp:149
helics::TimeData::minFed
GlobalFederateId minFed
identifier for the min dependency
Definition: TimeDependencies.hpp:42
flagOperations.hpp
helics::MessageProcessingResult
MessageProcessingResult
Definition: CoreTypes.hpp:64
helics::IterationRequest::NO_ITERATIONS
@ NO_ITERATIONS
indicator that the iterations have completed
helics::TimeCoordinator::generateConfig
void generateConfig(Json::Value &base) const
Definition: TimeCoordinator.cpp:280
helics::TimeCoordinator::localError
void localError()
Definition: TimeCoordinator.cpp:100
helics::MessageProcessingResult::NEXT_STEP
@ NEXT_STEP
indicator that the iterations have completed
HELICS_INVALID_PROPERTY_VALUE
const int HELICS_INVALID_PROPERTY_VALUE
Definition: helics_enums.h:278
helics::TimeCoordinator::removeDependent
void removeDependent(GlobalFederateId fedID)
Definition: TimeCoordinator.cpp:769
helics::TimeCoordinator::allowedSendTime
Time allowedSendTime() const
Definition: TimeCoordinator.hpp:138
helics::ActionMessage::source_id
GlobalFederateId source_id
12 – for federate_id or route_id
Definition: ActionMessage.hpp:37
helics::setIterationFlags
void setIterationFlags(ActionMessage &command, IterationRequest iterate)
Definition: ActionMessage.cpp:930