helics  2.8.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();
74  Time time_block = Time::maxVal();
80  std::vector<std::pair<Time, int32_t>> timeBlocks;
83  std::function<void(const ActionMessage&)>
85 
86  public:
88  0};
91  bool checkingExec{
93  false};
94  bool executionMode{false};
95  bool hasInitUpdates{false};
96  protected:
98  std::atomic<int32_t> iteration{0};
99  bool disconnected{false};
100  bool nonGranting{false}; // specify that the timeCoordinator should not grant times and
101  // instead operate in a continuous manner until completion
102  public:
104  TimeCoordinator();
106  explicit TimeCoordinator(std::function<void(const ActionMessage&)> userSendMessageFunction);
107 
109  void setProperty(int timeProperty, Time propertyVal);
111  void setProperty(int intProperty, int propertyVal);
113  void setOptionFlag(int optionFlag, bool value);
115  Time getTimeProperty(int timeProperty) const;
117  bool getOptionFlag(int optionFlag) const;
119  int getIntegerProperty(int intProperty) const;
121  void setMessageSender(std::function<void(const ActionMessage&)> userSendMessageFunction);
122 
124  Time getGrantedTime() const { return time_granted; }
126  Time allowedSendTime() const { return time_granted + info.outputDelay; }
128  std::vector<global_federate_id> getDependencies() const;
130  std::vector<global_federate_id> getDependents() const
131  {
132  return *dependent_federates.lock_shared();
133  }
137  int32_t getCurrentIteration() const { return iteration.load(); }
141  bool updateTimeFactors();
145  void updateValueTime(Time valueUpdateTime, bool allowRequestSend);
149  void updateMessageTime(Time messageUpdateTime, bool allowRequestSend);
150 
151  void specifyNonGranting(bool value = true) { nonGranting = value; }
152 
153  private:
157  DependencyInfo* getDependencyInfo(global_federate_id ofed);
159  bool isDependency(global_federate_id ofed) const;
160 
161  private:
163  bool updateNextExecutionTime();
166  void updateNextPossibleEventTime();
168  Time getNextPossibleTime() const;
169  Time generateAllowedTime(Time testTime) const;
170  /* return true if the skip federate was detected*/
171  bool checkAndSendTimeRequest(ActionMessage& upd, global_federate_id skip) const;
172 
173  void sendTimeRequest() const;
174  void updateTimeGrant();
176  bool transmitTimingMessages(ActionMessage& msg,
177  global_federate_id skipFed = global_federate_id{}) const;
178 
179  message_process_result processTimeBlockMessage(const ActionMessage& cmd);
180 
181  Time updateTimeBlocks(int32_t blockId, Time newTime);
182 
183  public:
187  message_process_result processTimeMessage(const ActionMessage& cmd);
188 
192  void processConfigUpdateMessage(const ActionMessage& cmd);
194  void processDependencyUpdateMessage(const ActionMessage& cmd);
198  bool addDependency(global_federate_id fedID);
202  bool addDependent(global_federate_id fedID);
205  void removeDependency(global_federate_id fedID);
208  void removeDependent(global_federate_id fedID);
209 
210  void setAsChild(global_federate_id fedID);
211 
212  void setAsParent(global_federate_id fedID);
221  void timeRequest(Time nextTime,
222  iteration_request iterate,
223  Time newValueTime,
224  Time newMessageTime);
232  void disconnect();
234  void localError();
236  std::string printTimeStatus() const;
238  bool hasActiveTimeDependencies() const;
240  void generateConfig(Json::Value& base) const;
241 
243  void generateDebuggingTimeInfo(Json::Value& base) const;
244 
246  int dependencyCount() const;
248  global_federate_id getMinDependency() const;
249 };
250 } // namespace helics
helics::timeZero
constexpr Time timeZero
Definition: helics-time.hpp:31
helics::TimeCoordinator::processConfigUpdateMessage
void processConfigUpdateMessage(const ActionMessage &cmd)
Definition: TimeCoordinator.cpp:1101
helics::ActionMessage::source_id
global_federate_id source_id
12 – for federate_id or route_id
Definition: ActionMessage.hpp:36
helics::TimeDependencies::removeDependency
void removeDependency(global_federate_id id)
Definition: TimeDependencies.cpp:264
helics::TimeDependencies::isDependency
bool isDependency(global_federate_id ofed) const
Definition: TimeDependencies.cpp:201
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:421
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:55
helics::TimeCoordinator::getGrantedTime
Time getGrantedTime() const
Definition: TimeCoordinator.hpp:124
helics::TimeCoordinator::hasInitUpdates
bool hasInitUpdates
Definition: TimeCoordinator.hpp:95
helics::TimeCoordinator::removeDependent
void removeDependent(global_federate_id fedID)
Definition: TimeCoordinator.cpp:726
helics::message_process_result::delay_processing
@ delay_processing
the message should be delayed and reprocessed later
helics::iteration_request
iteration_request
Definition: core-types.hpp:90
helics::TimeDependencies::getMinDependency
global_federate_id getMinDependency() const
Definition: TimeDependencies.cpp:362
helics::TimeCoordinator::processDependencyUpdateMessage
void processDependencyUpdateMessage(const ActionMessage &cmd)
Definition: TimeCoordinator.cpp:958
helics::TimeDependencies::addDependency
bool addDependency(global_federate_id id)
Definition: TimeDependencies.cpp:239
helics::TimeCoordinator::setMessageSender
void setMessageSender(std::function< void(const ActionMessage &)> userSendMessageFunction)
Definition: TimeCoordinator.cpp:33
helics::TimeCoordinator::executionMode
bool executionMode
flag that the coordinator has entered the execution Mode
Definition: TimeCoordinator.hpp:94
helics::TimeCoordinator::checkExecEntry
message_processing_result checkExecEntry()
Definition: TimeCoordinator.cpp:763
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::global_federate_id
Definition: global_federate_id.hpp:68
helics::setIterationFlags
void setIterationFlags(ActionMessage &command, iteration_request iterate)
Definition: ActionMessage.cpp:950
helics::TimeCoordinator::source_id
global_federate_id source_id
the identifier for inserting into the source id field of any generated messages;
Definition: TimeCoordinator.hpp:87
helics::TimeDependencies::resetDependentEvents
void resetDependentEvents(Time grantTime)
Definition: TimeDependencies.cpp:434
helics::TimeCoordinator::timeBlocks
std::vector< std::pair< Time, int32_t > > timeBlocks
blocks for a particular timeblocking link
Definition: TimeCoordinator.hpp:81
helics::TimeCoordinator::printTimeStatus
std::string printTimeStatus() const
Definition: TimeCoordinator.cpp:649
helics::parent_broker_id
constexpr global_broker_id parent_broker_id
Definition: global_federate_id.hpp:60
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: helics-time.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
Definition: TimeCoordinator.hpp:74
helics::TimeCoordinator::enteringExecMode
void enteringExecMode(iteration_request mode)
Definition: TimeCoordinator.cpp:42
helics::ActionMessage
Definition: ActionMessage.hpp:29
helics::TimeCoordinator::dependent_federates
shared_guarded_m< std::vector< global_federate_id > > dependent_federates
these are to maintain an accessible record of dependent federates
Definition: TimeCoordinator.hpp:76
helics::message_processing_result::error
@ error
indicator that an error has occurred
helics::message_process_result
message_process_result
Definition: TimeCoordinator.hpp:23
helics::iteration_request::force_iteration
@ force_iteration
force an iteration whether it is needed or not
helics::TimeCoordinator::processTimeMessage
message_process_result processTimeMessage(const ActionMessage &cmd)
Definition: TimeCoordinator.cpp:844
helics::TimeDependencies::resetIteratingExecRequests
void resetIteratingExecRequests()
Definition: TimeDependencies.cpp:377
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:386
helics::appendMessage
int appendMessage(ActionMessage &m, const ActionMessage &newMessage)
Definition: ActionMessage.cpp:939
helics::ActionMessage::counter
uint16_t counter
26 counter for filter tracking or message counter
Definition: ActionMessage.hpp:40
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:75
helics::message_processing_result
message_processing_result
Definition: core-types.hpp:65
helics::TimeDependencies::size
auto size() const
Definition: TimeDependencies.hpp:100
helics::global_federate_id::isValid
bool isValid() const
Definition: global_federate_id.hpp:108
helics::TimeCoordinator::time_value
Time time_value
the time of the earliest value event
Definition: TimeCoordinator.hpp:70
helics::message_processing_result::halted
@ halted
indicator that the simulation has been halted
helics::message_processing_result::continue_processing
@ continue_processing
the current loop should continue
helics::TimeCoordinator::disconnect
void disconnect()
Definition: TimeCoordinator.cpp:60
helics::TimeCoordinator::getOptionFlag
bool getOptionFlag(int optionFlag) const
Definition: TimeCoordinator.cpp:1083
child_flag
constexpr uint16_t child_flag
overload of extra_flag4 indicating a message is from a child object
Definition: flagOperations.hpp:46
helics::iteration_request::iterate_if_needed
@ iterate_if_needed
indicator that the iterations need to continue
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::TimeCoordinator::removeDependency
void removeDependency(global_federate_id fedID)
Definition: TimeCoordinator.cpp:715
helics::iteration_request::no_iterations
@ no_iterations
indicator that the iterations have completed
helics::TimeDependencies::activeDependencyCount
int activeDependencyCount() const
Definition: TimeDependencies.cpp:355
helics::tcoptions::event_triggered
bool event_triggered
Definition: TimeCoordinator.hpp:47
helics::ActionMessage::payload
std::string payload
Definition: ActionMessage.hpp:44
helics::TimeCoordinator::addDependency
bool addDependency(global_federate_id fedID)
Definition: TimeCoordinator.cpp:668
helics::global_federate_id::baseValue
constexpr base_type baseValue() const
Definition: global_federate_id.hpp:83
helics::TimeDependencies::updateTime
bool updateTime(const ActionMessage &m)
Definition: TimeDependencies.cpp:325
helics::tcoptions
Definition: TimeCoordinator.hpp:30
helics::TimeCoordinator::updateMessageTime
void updateMessageTime(Time messageUpdateTime, bool allowRequestSend)
Definition: TimeCoordinator.cpp:411
helics::TimeCoordinator::setOptionFlag
void setOptionFlag(int optionFlag, bool value)
Definition: TimeCoordinator.cpp:1033
helics::TimeCoordinator::time_allow
Time time_allow
the current allowable time
Definition: TimeCoordinator.hpp:67
helics::ActionMessage::messageID
int32_t messageID
8 – message ID for a variety of purposes
Definition: ActionMessage.hpp:35
helics::TimeCoordinator::iteration
std::atomic< int32_t > iteration
iteration counter
Definition: TimeCoordinator.hpp:98
helics::TimeCoordinator::hasActiveTimeDependencies
bool hasActiveTimeDependencies() const
Definition: TimeCoordinator.cpp:348
helics::ActionMessage::setExtraData
void setExtraData(int32_t data)
Definition: ActionMessage.hpp:157
helics::TimeDependencies::begin
auto begin()
Definition: TimeDependencies.hpp:102
indicator_flag
@ indicator_flag
flag used for setting values
Definition: flagOperations.hpp:21
helics::TimeCoordinator::updateTimeFactors
bool updateTimeFactors()
Definition: TimeCoordinator.cpp:443
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:52
helics::TimeCoordinator::dependencies
TimeDependencies dependencies
Definition: TimeCoordinator.hpp:79
setActionFlag
void setActionFlag(FlagContainer &M, FlagIndex flag)
Definition: flagOperations.hpp:67
helics::TimeCoordinator::time_minDe
Time time_minDe
the minimum event time of the dependencies
Definition: TimeCoordinator.hpp:66
helics::TimeCoordinator::updateValueTime
void updateValueTime(Time valueUpdateTime, bool allowRequestSend)
Definition: TimeCoordinator.cpp:246
helics::TimeCoordinator::TimeCoordinator
TimeCoordinator()
Definition: TimeCoordinator.cpp:23
helics::ActionMessage::Te
Time Te
48 event time
Definition: ActionMessage.hpp:47
helics::TimeDependencies::addDependent
bool addDependent(global_federate_id id)
Definition: TimeDependencies.cpp:277
helics::DependencyInfo
Definition: TimeDependencies.hpp:53
helics::TimeCoordinator::dependencyCount
int dependencyCount() const
Definition: TimeCoordinator.cpp:353
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:1053
helics::TimeCoordinator::getMinDependency
global_federate_id getMinDependency() const
Definition: TimeCoordinator.cpp:359
helics::TimeCoordinator::checkingExec
bool checkingExec
flag indicating that the coordinator is trying to enter the exec mode
Definition: TimeCoordinator.hpp:92
parent_flag
constexpr uint16_t parent_flag
overload of extra_flag3 indicating the message is from a parent object
Definition: flagOperations.hpp:43
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:996
helics::TimeCoordinator::time_grantBase
Time time_grantBase
Definition: TimeCoordinator.hpp:73
helics::ActionMessage::Tdemin
Time Tdemin
56 min dependent event time
Definition: ActionMessage.hpp:48
helics::ActionMessage::actionTime
Time actionTime
40 the time an action took place or will take place //32
Definition: ActionMessage.hpp:43
helics::TimeCoordinator::addDependent
bool addDependent(global_federate_id fedID)
Definition: TimeCoordinator.cpp:684
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:336
helics
the main namespace for the helics co-simulation library User functions will be in the helics namespac...
Definition: AsyncFedCallInfo.hpp:14
helics::TimeCoordinator::dependency_federates
shared_guarded_m< std::vector< global_federate_id > > dependency_federates
these are to maintain an accessible record of dependency federates
Definition: TimeCoordinator.hpp:78
helics::TimeCoordinator::getIntegerProperty
int getIntegerProperty(int intProperty) const
Definition: TimeCoordinator.cpp:1072
helics::TimeDependencies::hasActiveTimeDependencies
bool hasActiveTimeDependencies() const
Definition: TimeDependencies.cpp:348
helics::TimeCoordinator::iterating
iteration_request iterating
Definition: TimeCoordinator.hpp:89
helics::TimeCoordinator::generateDebuggingTimeInfo
void generateDebuggingTimeInfo(Json::Value &base) const
Definition: TimeCoordinator.cpp:302
helics::TimeData::minDe
Time minDe
min dependency event time
Definition: TimeDependencies.hpp:40
helics::TimeCoordinator::time_requested
Time time_requested
the most recent time requested
Definition: TimeCoordinator.hpp:63
helics::TimeCoordinator::getDependencies
std::vector< global_federate_id > getDependencies() const
Definition: TimeCoordinator.cpp:742
helics::TimeCoordinator::upstream
TimeData upstream
the variables for time coordination
Definition: TimeCoordinator.hpp:58
gmlc::libguarded::shared_guarded
Definition: application_api/Federate.hpp:26
helics::timeEpsilon
constexpr Time timeEpsilon
Definition: helics-time.hpp:33
helics::ActionMessage::dest_id
global_federate_id dest_id
20 fed_id for a targeted message
Definition: ActionMessage.hpp:38
helics::TimeCoordinator::getDependents
std::vector< global_federate_id > getDependents() const
Definition: TimeCoordinator.hpp:130
helics::TimeCoordinator::info
tcoptions info
basic time control information
Definition: TimeCoordinator.hpp:82
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:84
helics::TimeCoordinator::getCurrentIteration
int32_t getCurrentIteration() const
Definition: TimeCoordinator.hpp:137
flagOperations.hpp
helics::message_processing_result::next_step
@ next_step
indicator that the iterations have completed
helics::TimeCoordinator::checkTimeGrant
message_processing_result checkTimeGrant()
Definition: TimeCoordinator.cpp:481
helics::TimeData::minFed
global_federate_id minFed
identifier for the min dependency
Definition: TimeDependencies.hpp:42
helics::TimeDependencies::getDependencyInfo
const DependencyInfo * getDependencyInfo(global_federate_id id) const
Definition: TimeDependencies.cpp:219
helics::TimeCoordinator::generateConfig
void generateConfig(Json::Value &base) const
Definition: TimeCoordinator.cpp:277
helics::message_processing_result::iterating
@ iterating
indicator that the iterations need to continue
helics::TimeCoordinator::localError
void localError()
Definition: TimeCoordinator.cpp:97
helics::TimeCoordinator::timeRequest
void timeRequest(Time nextTime, iteration_request iterate, Time newValueTime, Time newMessageTime)
Definition: TimeCoordinator.cpp:140
HELICS_INVALID_PROPERTY_VALUE
const int HELICS_INVALID_PROPERTY_VALUE
Definition: helics_enums.h:246
helics::TimeCoordinator::allowedSendTime
Time allowedSendTime() const
Definition: TimeCoordinator.hpp:126
helics::TimeDependencies::removeDependent
void removeDependent(global_federate_id id)
Definition: TimeDependencies.cpp:302