add/fix documentation

Signed-off-by: Lance-Drane <Lance-Drane@users.noreply.github.com>

Author: Lance-Drane

doc/user_guides/jupyter.rst

@@ -55,7 +55,7 @@ This code initializes JupyterHub to work with this run and contacts the web port
 
 ---
 
-For updating data files, we generally accommodate for two approaches: one where you want to multiple data files for each timestamp called, and one where you maintain multiple data files for a single timestamp but replace it per timestamp call. Both workflows utilize `self.services.add_analysis_data_file` .
+For updating data files, we generally accommodate for two approaches: one where you want to multiple data files for each timestamp called, and one where you maintain multiple data files for a single timestamp but replace it per timestamp call. Both workflows utilize `self.services.add_analysis_data_files` .
 
 For the approach where data files for multiple timestamps are maintained, the below code provides an example of loading it from a file which is regularly updated with the IPS state:
 
@@ -70,7 +70,7 @@ For the approach where data files for multiple timestamps are maintained, the be
             # and that this file is updated per timestamp call
             # In this example, we just want to snapshot our IPS state and save it in our JupyterHub workflow
             data_file = f'{timestamp}_state.json' # get current data file
-            self.services.add_analysis_data_file(
+            self.services.add_analysis_data_files(
                 current_data_file_path=data_file,
                 timestamp=timestamp,
             )
@@ -88,7 +88,7 @@ Or, if you only want to maintain a single timestamp, set the "replace" flag to T
         def step(self, timestamp=0.0):
             # assume that we continually update our state
             data_file = 'state.json' # get current data file
-            self.services.add_analysis_data_file(
+            self.services.add_analysis_data_files(
                 current_data_file_path=data_file,
                 replace=True,
             )

ipsframework/ips.py

@@ -561,16 +561,21 @@ def initiate_new_simulation(self, sim_name: str):
 
     def _send_monitor_event(self, sim_name='', eventType='', comment='', ok=True, target=None, operation=None, start_time=None, end_time=None, call_id=0):
         """
-        Publish a portal monitor event to the *_IPS_MONITOR* event topic.
+        Publish a monitor event to the *_IPS_MONITOR* event topic.
         Event topics that start with an underscore are reserved for use by the
         IPS Framework and services.
 
-          * *sim_name*: The name of the simulation to which this even belongs.
-          * *eventType*: The type of the event.
-          * *comment*: A string containing comment that describes the event.
-          * *ok*: A string containing the values 'True' or 'False', based on
+        The IPS *LocalLoggingBridge* component will always be at least one consumer of these messages. If the web portal has been configured,
+        the IPS *PortalBridge* component will also consume these messages.
+        When a single message is published, ALL of these components will handle the published message (there is no "shared queue").
+
+        :param sim_name: The name of the simulation to which this even belongs.
+        :param eventType: The type of the event.
+        :param comment: A string containing comment that describes the event.
+        :param ok: A string containing the values 'True' or 'False', based on
             whether the event indicates normal simulation execution, or an
             error condition.
+        :param target:
         """
         event_time = time.time()
         if self.verbose_debug:
@@ -584,10 +589,12 @@ def _send_monitor_event(self, sim_name='', eventType='', comment='', ok=True, ta
         portal_data['walltime'] = '%.2f' % (event_time - self.config_manager.sim_map[sim_name].start_time)
         portal_data['time'] = getTimeString(time.localtime(event_time))
 
-        topic_name = '_IPS_MONITOR'
         # portal_data['phystimestamp'] = self.timeStamp
         get_config = self.config_manager.get_config_parameter
         if eventType == 'IPS_START':
+            # The 'IPS_START' event is always the first event sent from a component, and it should always be submitted internally.
+            # This event will always mark the first time a component has registered,
+            # and sending this event is indicative of the first time we make a Web Portal call and the first time we write to the event log files.
             user = self.config_manager.get_platform_parameter('USER')
             host = self.config_manager.get_platform_parameter('HOST')
             d = datetime.datetime.now()
@@ -645,6 +652,7 @@ def _send_monitor_event(self, sim_name='', eventType='', comment='', ok=True, ta
                 pass
 
         elif eventType == 'IPS_END':
+            # The IPS_END event is always the last event called by the framework, ONLY sent out to indicate that there are no remaining messages to handle.
             portal_data['state'] = 'Completed'
             portal_data['stopat'] = getTimeString(time.localtime(event_time))
             # Zipkin json format
@@ -656,6 +664,7 @@ def _send_monitor_event(self, sim_name='', eventType='', comment='', ok=True, ta
                 'tags': {'total_cores': str(self.resource_manager.total_cores)},
             }
         elif eventType == 'IPS_CALL_END':
+            # The IPS_CALL_END event is always the last event called by the framework,
             trace = {}  # Zipkin json format
             if start_time is not None and end_time is not None:
                 trace['timestamp'] = int(start_time * 1e6)  # convert to microsecond
@@ -676,17 +685,17 @@ def _send_monitor_event(self, sim_name='', eventType='', comment='', ok=True, ta
 
         if self.verbose_debug:
             self.debug('Publishing %s', str(event_body))
-        self.event_manager.publish(topic_name, 'IPS_SIM', event_body)
+        # this message will be published to any component subscribed to '_IPS_MONITOR' - this generally includes the local logger bridge and the portal bridge
+        self.event_manager.publish(topicName='_IPS_MONITOR', eventName='IPS_SIM', eventBody=event_body)
 
     def _send_dynamic_sim_event(self, sim_name='', event_type='', ok=True):
         self.debug('_send_dynamic_sim_event(%s:%s)', event_type, sim_name)
         event_data = {}
         event_data['eventtype'] = event_type
         event_data['SIM_NAME'] = sim_name
         event_data['ok'] = ok
-        topic_name = '_IPS_DYNAMIC_SIMULATION'
         self.debug('Publishing %s', str(event_data))
-        self.event_manager.publish(topic_name, 'IPS_DYNAMIC_SIM', event_data)
+        self.event_manager.publish(topicName='_IPS_DYNAMIC_SIMULATION', eventName='IPS_DYNAMIC_SIM', eventBody=event_data)
 
     # TODO mark status as a "Literal" if we move to Python >= 3.8
     def send_terminate_msg(self, sim_name: str, status=Message.SUCCESS):

ipsframework/services.py

@@ -1994,9 +1994,8 @@ def initialize_jupyter_notebook(
 
         Does not modify the source notebook.
 
-        Params:
-          - source_notebook_path: location you want to load the source notebook from. This can be either an absolute path, or an IPS-appropriate relative path.
-          - dest_notebook_name: (optional, default None) filename of the notebook to use when saving it to the IPS Portal. If not provided, this will defauly to the filename of the source notebook.
+        :param source_notebook_path: location you want to load the source notebook from. This can be either an absolute path, or an IPS-appropriate relative path.
+        :param dest_notebook_name: (optional, default None) filename of the notebook to use when saving it to the IPS Portal. If not provided, this will defauly to the filename of the source notebook.
         """
         portal_runid = self._get_jupyter_runid()
         if portal_runid < 0:
@@ -2060,6 +2059,12 @@ def add_analysis_data_files(self, current_data_file_paths: list[str], timestamp:
     def publish(self, topicName: str, eventName: str, eventBody: Any) -> None:
         """
         Publish event consisting of *eventName* and *eventBody* to topic *topicName* to the IPS event service.
+
+        Publishing an event multiple components are subscribed to will cause each component to handle the message simultaneously.
+
+        :param topicName: the name of the topic to publish on, top-level namespace
+        :param eventName: event associated with the topic 
+        :param eventBody: data to send
         """
         if not topicName.startswith('_IPS'):
             topicName = self.sim_name + '_' + topicName
@@ -2068,6 +2073,11 @@ def publish(self, topicName: str, eventName: str, eventBody: Any) -> None:
     def subscribe(self, topicName: str, callback: Callable) -> None:
         """
         Subscribe to topic *topicName* on the IPS event service and register *callback* as the method to be invoked when an event is published to that topic.
+
+        Multiple components can subscribe to the same topic name; if this is the case, each component will handle the message separately when the topic is published to.
+        
+        :param topicName: the name of the topic to subscribe to, top-level namespace
+        :param callback: the function which will be called on receiving a message
         """
         if not topicName.startswith('_IPS'):
             topicName = self.sim_name + '_' + topicName
@@ -2076,6 +2086,8 @@ def subscribe(self, topicName: str, callback: Callable) -> None:
     def unsubscribe(self, topicName: str) -> None:
         """
         Remove subscription to topic *topicName*.
+
+        :param topicName: the name of the topic to unsubscribe from
         """
         if not topicName.startswith('_IPS'):
             topicName = self.sim_name + '_' + topicName