nost-tools 2.4.0__tar.gz → 3.0.0__tar.gz

{nost_tools-2.4.0 → nost_tools-3.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nost_tools
-Version: 2.4.0
+Version: 3.0.0
 Summary: Tools for Novel Observing Strategies Testbed (NOS-T) Applications
 Author-email: "Paul T. Grogan" <paul.grogan@asu.edu>, "Emmanuel M. Gonzalez" <emmanuelgonzalez@asu.edu>
 License-Expression: BSD-3-Clause

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/__init__.py

@@ -1,4 +1,4 @@
-__version__ = "2.4.0"
+__version__ = "3.0.0"
 
 from .application import Application
 from .application_utils import ConnectionConfig, ModeStatusObserver, TimeStatusPublisher
@@ -6,7 +6,7 @@ from .configuration import ConnectionConfig
 from .entity import Entity
 from .logger_application import LoggerApplication
 from .managed_application import ManagedApplication
-from .manager import Manager, TimeScaleUpdate
+from .manager import Manager
 from .observer import Observable, Observer
 from .publisher import ScenarioTimeIntervalPublisher, WallclockTimeIntervalPublisher
 from .schemas import (

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/application.py

@@ -217,21 +217,21 @@ class Application:
 
         def refresh_wallclock_periodically():
             while not self._should_stop.wait(
-                timeout=self.config.rc.wallclock_offset_properties.wallclock_offset_refresh_interval
+                timeout=self.config.rc.simulation_configuration.execution_parameters.general.wallclock_offset_refresh_interval
             ):
                 logger.debug("Wallclock refresh thread is running.")
                 try:
-                    logger.info(
-                        f"Contacting {self.config.rc.wallclock_offset_properties.ntp_host} to retrieve wallclock offset."
+                    logger.debug(
+                        f"Contacting {self.config.rc.simulation_configuration.execution_parameters.general.ntp_host} to retrieve wallclock offset."
                     )
                     response = ntplib.NTPClient().request(
-                        self.config.rc.wallclock_offset_properties.ntp_host,
+                        self.config.rc.simulation_configuration.execution_parameters.general.ntp_host,
                         version=3,
                         timeout=2,
                     )
                     offset = timedelta(seconds=response.offset)
                     self.simulator.set_wallclock_offset(offset)
-                    logger.info(f"Wallclock offset updated to {offset}.")
+                    logger.debug(f"Wallclock offset updated to {offset}.")
                 except Exception as e:
                     logger.debug(f"Failed to refresh wallclock offset: {e}")
 
@@ -338,7 +338,7 @@ class Application:
         if self.set_offset:
             # Start periodic wallclock offset updates instead of one-time call
             logger.info(
-                f"Wallclock offset will be set every {self.config.rc.wallclock_offset_properties.wallclock_offset_refresh_interval} seconds using {self.config.rc.wallclock_offset_properties.ntp_host}."
+                f"Wallclock offset will be set every {self.config.rc.simulation_configuration.execution_parameters.general.wallclock_offset_refresh_interval} seconds using {self.config.rc.simulation_configuration.execution_parameters.general.ntp_host}."
             )
             self.start_wallclock_refresh_thread()
 

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/configuration.py

@@ -21,7 +21,6 @@ from .schemas import (
     RuntimeConfig,
     ServersConfig,
     SimulationConfig,
-    WallclockOffsetProperties,
 )
 
 logger = logging.getLogger(__name__)
@@ -329,7 +328,6 @@ class ConnectionConfig:
             self.load_environment_variables()
 
         self.rc = RuntimeConfig(
-            wallclock_offset_properties=WallclockOffsetProperties(),
             credentials=self.credentials_config,
             server_configuration=server_config,
             simulation_configuration=self.simulation_config,

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/managed_application.py

@@ -4,12 +4,25 @@ Provides a base application that manages communication between a simulator and b
 
 import logging
 import threading
+import time
 import traceback
 from datetime import datetime, timedelta
 
+from nost_tools.simulator import Mode
+
 from .application import Application
 from .application_utils import ConnectionConfig
-from .schemas import InitCommand, StartCommand, StopCommand, UpdateCommand
+from .schemas import (
+    FreezeCommand,
+    FreezeRequest,
+    InitCommand,
+    ResumeCommand,
+    ResumeRequest,
+    StartCommand,
+    StopCommand,
+    UpdateCommand,
+    UpdateRequest,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -143,6 +156,17 @@ class ManagedApplication(Application):
             app_topic="update",
             user_callback=self.on_manager_update,
         )
+        self.add_message_callback(
+            app_name=self.manager_app_name,
+            app_topic="freeze",
+            user_callback=self.on_manager_freeze,
+        )
+
+        self.add_message_callback(
+            app_name=self.manager_app_name,
+            app_topic="resume",
+            user_callback=self.on_manager_resume,
+        )
 
     def shut_down(self) -> None:
         """
@@ -259,16 +283,166 @@ class ManagedApplication(Application):
             body (bytes): The actual message body sent, containing the message payload.
         """
         try:
-            # Parse message payload
             message = body.decode("utf-8")
-            params = UpdateCommand.model_validate_json(message).tasking_parameters
+            update_cmd = UpdateCommand.model_validate_json(message)
+            params = update_cmd.tasking_parameters
+            tcf = params.time_scaling_factor
+            sim_epoch = params.sim_update_time
+
             logger.info(f"Received update command {message}")
-            # update execution time scale factor
-            self.simulator.set_time_scale_factor(
-                params.time_scaling_factor, params.sim_update_time
+
+            def _apply_when_executing():
+                while self.simulator.get_mode() != Mode.EXECUTING:
+                    time.sleep(0.01)
+                # Apply update once executing
+                self.simulator.set_time_scale_factor(tcf, sim_epoch)
+
+            if self.simulator.get_mode() != Mode.EXECUTING:
+                logger.debug("Deferring time scale update until EXECUTING")
+                threading.Thread(target=_apply_when_executing, daemon=True).start()
+            else:
+                self.simulator.set_time_scale_factor(tcf, sim_epoch)
+        except Exception as e:
+            logger.error(
+                f"Exception (topic: {method.routing_key}, payload: {message}): {e}"
             )
+            print(traceback.format_exc())
+
+    def on_manager_freeze(self, ch, method, properties, body) -> None:
+        """
+        Callback function for the managed application ('self') to respond to a freeze command sent from the manager.
+        Parses the freeze duration and simulation freeze time and updates the simulator.
+
+        Args:
+            ch (:obj:`pika.channel.Channel`): The channel object used to communicate with the RabbitMQ server.
+            method (:obj:`pika.spec.Basic.Deliver`): Delivery-related information such as delivery tag, exchange, and routing key.
+            properties (:obj:`pika.BasicProperties`): Message properties including content type, headers, and more.
+            body (bytes): The actual message body sent, containing the message payload.
+        """
+        try:
+            # Parse message payload
+            message = body.decode("utf-8")
+            params = FreezeCommand.model_validate_json(message).tasking_parameters
+            logger.info(f"Received freeze command {message}")
+            # freeze simulation time
+            self.simulator.pause()
+
+        except Exception as e:
+            logger.error(
+                f"Exception (topic: {method.routing_key}, payload: {message}): {e}"
+            )
+            print(traceback.format_exc())
+
+    def on_manager_resume(self, ch, method, properties, body) -> None:
+        """
+        Callback function for the managed application ('self') to respond to a resume command sent from the manager.
+        Resumes the simulator execution.
+
+        Args:
+            ch (:obj:`pika.channel.Channel`): The channel object used to communicate with the RabbitMQ server.
+            method (:obj:`pika.spec.Basic.Deliver`): Delivery-related information such as delivery tag, exchange, and routing key.
+            properties (:obj:`pika.BasicProperties`): Message properties including content type, headers, and more.
+            body (bytes): The actual message body sent, containing the message payload.
+        """
+        try:
+            # Parse message payload
+            message = body.decode("utf-8")
+            params = ResumeCommand.model_validate_json(message).tasking_parameters
+            logger.info(f"Received resume command {message}")
+            # resume simulation time
+            self.simulator.resume()
         except Exception as e:
             logger.error(
                 f"Exception (topic: {method.routing_key}, payload: {message}): {e}"
             )
             print(traceback.format_exc())
+
+    def request_freeze(
+        self, freeze_duration: timedelta = None, sim_freeze_time: datetime = None
+    ) -> None:
+        """
+        Request a freeze from the manager.
+
+        Args:
+            freeze_duration (:obj:`timedelta`, optional): Duration for which to freeze execution.
+                                                        If None, creates an indefinite freeze.
+            sim_freeze_time (:obj:`datetime`, optional): Scenario time at which to freeze execution.
+                                                        If None, freezes immediately.
+        """
+        # Publish a freeze request message
+        wallclock_time = self.simulator.get_wallclock_time_at_simulation_time(
+            sim_freeze_time
+        )
+        request_params = {
+            "simFreezeTime": sim_freeze_time,
+            "freezeTime": wallclock_time,
+            "requestingApp": self.app_name,
+        }
+        if freeze_duration is not None:
+            request_params["freezeDuration"] = freeze_duration
+            request_params["resumeTime"] = wallclock_time + freeze_duration
+        # Create the freeze request
+        request = FreezeRequest.model_validate({"taskingParameters": request_params})
+        freeze_type = (
+            "indefinite" if freeze_duration is None else f"timed ({freeze_duration})"
+        )
+        logger.info(
+            f"Requesting {freeze_type} freeze: {request.model_dump_json(by_alias=True)}"
+        )
+        # Send the request to the manager
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="request.freeze",
+            payload=request.model_dump_json(by_alias=True),
+        )
+
+    def request_resume(self) -> None:
+        """
+        Request a resume from the manager.
+        """
+        # Create the resume request
+        request = ResumeRequest.model_validate(
+            {"taskingParameters": {"requestingApp": self.app_name}}
+        )
+
+        logger.info(f"Requesting resume: {request.model_dump_json(by_alias=True)}")
+
+        # Send the request to the manager
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="request.resume",
+            payload=request.model_dump_json(by_alias=True),
+        )
+
+    def request_update(
+        self, time_scale_factor: float, sim_update_time: datetime = None
+    ) -> None:
+        """
+        Request a time scale factor update from the manager.
+
+        Args:
+            time_scale_factor (float): scenario seconds per wallclock second
+            sim_update_time (:obj:`datetime`, optional): Scenario time at which to update.
+                                                        If None, updates immediately.
+        """
+        # Publish an update request message
+        request_params = {
+            "timeScalingFactor": time_scale_factor,
+            "requestingApp": self.app_name,
+        }
+        if sim_update_time is not None:
+            request_params["simUpdateTime"] = sim_update_time
+
+        # Create the update request
+        request = UpdateRequest.model_validate({"taskingParameters": request_params})
+
+        logger.info(
+            f"Requesting time scale factor update to {time_scale_factor}: {request.model_dump_json(by_alias=True)}"
+        )
+
+        # Send the request to the manager
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="request.update",
+            payload=request.model_dump_json(by_alias=True),
+        )

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/manager.py

@@ -15,40 +15,23 @@ from pydantic import ValidationError
 from .application import Application
 from .application_utils import ConnectionConfig
 from .schemas import (
+    FreezeCommand,
+    FreezeRequest,
     InitCommand,
     ReadyStatus,
+    ResumeCommand,
+    ResumeRequest,
     StartCommand,
     StopCommand,
     TimeStatus,
     UpdateCommand,
+    UpdateRequest,
 )
 from .simulator import Mode
 
 logger = logging.getLogger(__name__)
 
 
-class TimeScaleUpdate(object):
-    """
-    Provides a scheduled update to the simulation time scale factor by sending a message at the designated sim_update_time
-    to change the time_scale_factor to the indicated value.
-
-    Attributes:
-        time_scale_factor (float): scenario seconds per wallclock second
-        sim_update_time (:obj:`datetime`): scenario time that the update will occur
-    """
-
-    def __init__(self, time_scale_factor: float, sim_update_time: datetime):
-        """
-        Instantiates a new time scale update.
-
-        Args:
-            time_scale_factor (float): scenario seconds per wallclock second
-            sim_update_time (:obj:`datetime`): scenario time that the update will occur
-        """
-        self.time_scale_factor = time_scale_factor
-        self.sim_update_time = sim_update_time
-
-
 class Manager(Application):
     """
     NOS-T Manager Application.
@@ -84,19 +67,17 @@ class Manager(Application):
             app_name, app_description, setup_signal_handlers=setup_signal_handlers
         )
         self.required_apps_status = {}
-
         self.sim_start_time = None
         self.sim_stop_time = None
-        start_time = None
-        time_step = None
-        time_scale_factor = None
-        time_scale_updates = None
-        time_status_step = None
-        time_status_init = None
-        command_lead = None
-        required_apps = None
-        init_retry_delay_s = None
-        init_max_retry = None
+        self.start_time = None
+        self.time_step = None
+        self.time_scale_factor = None
+        self.time_status_step = None
+        self.time_status_init = None
+        self.command_lead = None
+        self.required_apps = None
+        self.init_retry_delay_s = None
+        self.init_max_retry = None
 
     def establish_exchange(self):
         """
@@ -164,7 +145,7 @@ class Manager(Application):
         set_offset: bool = True,
         time_status_step: timedelta = None,
         time_status_init: datetime = None,
-        shut_down_when_terminated: bool = False
+        shut_down_when_terminated: bool = False,
     ) -> None:
         """
         Starts up the application by connecting to message broker, starting a background event loop,
@@ -190,8 +171,147 @@ class Manager(Application):
             shut_down_when_terminated,
         )
 
-        # Additional manager-specific setup: establish the exchange
+        # Establish the RabbitMQ exchange
         self.establish_exchange()
+        # Register callbacks for freeze, resume, and update requests from managed applications
+        self.add_message_callback("*", "request.freeze", self.on_freeze_request)
+        self.add_message_callback("*", "request.resume", self.on_resume_request)
+        self.add_message_callback("*", "request.update", self.on_update_request)
+
+    def on_freeze_request(self, ch, method, properties, body) -> None:
+        """
+        Callback to handle freeze requests from managed applications.
+
+        Args:
+            ch (:obj:`pika.channel.Channel`): The channel object used to communicate with the RabbitMQ server.
+            method (:obj:`pika.spec.Basic.Deliver`): Delivery-related information such as delivery tag, exchange, and routing key.
+            properties (:obj:`pika.BasicProperties`): Message properties including content type, headers, and more.
+            body (bytes): The actual message body sent, containing the message payload.
+        """
+        try:
+            # Parse the freeze request
+            message = body.decode("utf-8")
+            freeze_request = FreezeRequest.model_validate_json(message)
+            params = freeze_request.tasking_parameters
+
+            logger.info(
+                f"Received freeze request from {params.requesting_app}: {message}"
+            )
+
+            # Use a separate thread to handle the freeze to avoid blocking the callback
+            freeze_thread = threading.Thread(
+                target=self._handle_freeze_request,
+                args=(
+                    params.freeze_duration,
+                    params.sim_freeze_time,
+                    params.resume_time,
+                ),
+                daemon=True,
+            )
+            freeze_thread.start()
+
+        except ValidationError as e:
+            logger.error(f"Validation error in freeze request: {e}")
+        except Exception as e:
+            logger.error(
+                f"Exception handling freeze request (topic: {method.routing_key}, payload: {message}): {e}"
+            )
+            print(traceback.format_exc())
+
+    def _handle_freeze_request(
+        self,
+        freeze_duration: timedelta = None,
+        sim_freeze_time: datetime = None,
+        resume_time: datetime = None,
+    ) -> None:
+        try:
+            if freeze_duration is not None:
+                self.freeze(freeze_duration, sim_freeze_time, resume_time)
+                # Only resume if we are still paused and not terminating
+                if self.simulator.get_mode() == Mode.PAUSED:
+                    self.resume()
+            else:
+                self.freeze(None, sim_freeze_time, None)
+                logger.info("Indefinite freeze requested - manual resume required")
+
+        except Exception as e:
+            logger.error(f"Error handling freeze request: {e}")
+            print(traceback.format_exc())
+
+    def on_resume_request(self, ch, method, properties, body) -> None:
+        """
+        Callback to handle resume requests from managed applications.
+
+        Args:
+            ch (:obj:`pika.channel.Channel`): The channel object used to communicate with the RabbitMQ server.
+            method (:obj:`pika.spec.Basic.Deliver`): Delivery-related information such as delivery tag, exchange, and routing key.
+            properties (:obj:`pika.BasicProperties`): Message properties including content type, headers, and more.
+            body (bytes): The actual message body sent, containing the message payload.
+        """
+        try:
+            # Parse the resume request
+            message = body.decode("utf-8")
+            resume_request = ResumeRequest.model_validate_json(message)
+            params = resume_request.tasking_parameters
+            logger.info(
+                f"Received resume request from {params.requesting_app}: {message}"
+            )
+            # Execute the resume command
+            self.resume()
+
+        except ValidationError as e:
+            logger.error(f"Validation error in resume request: {e}")
+        except Exception as e:
+            logger.error(
+                f"Exception handling resume request (topic: {method.routing_key}, payload: {message}): {e}"
+            )
+            print(traceback.format_exc())
+
+    def on_update_request(self, ch, method, properties, body) -> None:
+        """
+        Callback to handle update requests from managed applications.
+
+        Args:
+            ch (:obj:`pika.channel.Channel`): The channel object used to communicate with the RabbitMQ server.
+            method (:obj:`pika.spec.Basic.Deliver`): Delivery-related information such as delivery tag, exchange, and routing key.
+            properties (:obj:`pika.BasicProperties`): Message properties including content type, headers, and more.
+            body (bytes): The actual message body sent, containing the message payload.
+        """
+        try:
+            message = body.decode("utf-8")
+            update_request = UpdateRequest.model_validate_json(message)
+            params = update_request.tasking_parameters
+            logger.info(
+                f"Received update request from {params.requesting_app}: {message}"
+            )
+
+            def _apply_update_when_executing():
+                while self.simulator.get_mode() != Mode.EXECUTING:
+                    self._sleep_with_heartbeat(0.01)
+                self.update(
+                    params.time_scale_factor,
+                    params.sim_update_time or self.simulator.get_time(),
+                )
+                # Wait until update takes effect
+                while (
+                    self.simulator.get_time_scale_factor() != params.time_scale_factor
+                ):
+                    self._sleep_with_heartbeat(0.01)
+
+            # Defer if not executing yet
+            if self.simulator.get_mode() != Mode.EXECUTING:
+                threading.Thread(
+                    target=_apply_update_when_executing, daemon=True
+                ).start()
+            else:
+                _apply_update_when_executing()
+        except ValidationError as e:
+            logger.error(f"Validation error in update request: {e}")
+        except Exception as e:
+            logger.error(
+                f"Exception handling update request (topic: {method.routing_key}, payload: {message}): {e}"
+            )
+            print(traceback.format_exc())
 
     def execute_test_plan(self, *args, **kwargs) -> None:
         """
@@ -214,7 +334,6 @@ class Manager(Application):
         start_time: datetime = None,
         time_step: timedelta = timedelta(seconds=1),
         time_scale_factor: float = 1.0,
-        time_scale_updates: List[TimeScaleUpdate] = [],
         time_status_step: timedelta = None,
         time_status_init: datetime = None,
         command_lead: timedelta = timedelta(seconds=0),
@@ -234,7 +353,6 @@ class Manager(Application):
             start_time (:obj:`datetime`): wallclock time at which to start execution (default: now)
             time_step (:obj:`timedelta`): scenario time step used in execution (default: 1 second)
             time_scale_factor (float): scenario seconds per wallclock second (default: 1.0)
-            time_scale_updates (list(:obj:`TimeScaleUpdate`)): list of scheduled time scale updates (default: [])
             time_status_step (:obj:`timedelta`): scenario duration between time status messages
             time_status_init (:obj:`datetime`): scenario time of first time status message
             command_lead (:obj:`timedelta`): wallclock lead time between command and action (default: 0 seconds)
@@ -243,7 +361,7 @@ class Manager(Application):
             init_max_retry (int): number of initialization commands while waiting for required applications before continuing to execution
         """
         if self.config.rc.yaml_file:
-            logger.info(
+            logger.debug(
                 f"Collecting execution parameters from YAML configuration file: {self.config.rc.yaml_file}"
             )
             parameters = getattr(
@@ -256,7 +374,6 @@ class Manager(Application):
             self.start_time = parameters.start_time
             self.time_step = parameters.time_step
             self.time_scale_factor = parameters.time_scale_factor
-            self.time_scale_updates = parameters.time_scale_updates
             self.time_status_step = parameters.time_status_step
             self.time_status_init = parameters.time_status_init
             self.command_lead = parameters.command_lead
@@ -266,7 +383,7 @@ class Manager(Application):
             self.init_retry_delay_s = parameters.init_retry_delay_s
             self.init_max_retry = parameters.init_max_retry
         else:
-            logger.info(
+            logger.debug(
                 f"Collecting execution parameters from user input or default values."
             )
             self.sim_start_time = sim_start_time
@@ -274,7 +391,6 @@ class Manager(Application):
             self.start_time = start_time
             self.time_step = time_step
             self.time_scale_factor = time_scale_factor
-            self.time_scale_updates = time_scale_updates
             self.time_status_step = time_status_step
             self.time_status_init = time_status_init
             self.command_lead = command_lead
@@ -282,17 +398,6 @@ class Manager(Application):
             self.init_retry_delay_s = init_retry_delay_s
             self.init_max_retry = init_max_retry
 
-        # Convert TimeScaleUpdateSchema objects to TimeScaleUpdate objects
-        converted_updates = []
-        for update_schema in self.time_scale_updates:
-            converted_updates.append(
-                TimeScaleUpdate(
-                    time_scale_factor=update_schema.time_scale_factor,
-                    sim_update_time=update_schema.sim_update_time,
-                )
-            )
-        self.time_scale_updates = converted_updates
-
         # Set up tracking of required applications
         self.required_apps_status = dict(
             zip(self.required_apps, [False] * len(self.required_apps))
@@ -346,44 +451,22 @@ class Manager(Application):
         while self.simulator.get_mode() != Mode.EXECUTING:
             time.sleep(0.001)
 
-        # Process time scale updates
-        for update in self.time_scale_updates:
-            update_time = self.simulator.get_wallclock_time_at_simulation_time(
-                update.sim_update_time
-            )
-            # Sleep until update time using heartbeat-safe approach
-            sleep_seconds = max(
-                0,
-                (
-                    (update_time - self.simulator.get_wallclock_time())
-                    - self.command_lead
-                )
-                / timedelta(seconds=1),
+        # Wait for stop time - simulator now handles freeze time internally
+        while True:
+            end_time = self.simulator.get_wallclock_time_at_simulation_time(
+                self.simulator.get_end_time()
             )
+            current_time = self.simulator.get_wallclock_time()
+            time_until_stop = (
+                end_time - current_time - self.command_lead
+            ).total_seconds()
 
-            # Use our heartbeat-safe sleep
-            self._sleep_with_heartbeat(sleep_seconds)
+            if time_until_stop <= 0:
+                break
 
-            # Issue the update command
-            self.update(update.time_scale_factor, update.sim_update_time)
-
-            # Wait until update takes effect
-            while self.simulator.get_time_scale_factor() != update.time_scale_factor:
-                time.sleep(0.001)
-
-        end_time = self.simulator.get_wallclock_time_at_simulation_time(
-            self.simulator.get_end_time()
-        )
-
-        # Sleep until stop time using heartbeat-safe approach
-        sleep_seconds = max(
-            0,
-            ((end_time - self.simulator.get_wallclock_time()) - self.command_lead)
-            / timedelta(seconds=1),
-        )
-
-        # Use our heartbeat-safe sleep
-        self._sleep_with_heartbeat(sleep_seconds)
+            # Wait for timeout
+            timeout = min(30.0, time_until_stop)
+            time.sleep(timeout)
 
         # Issue the stop command
         self.stop(self.sim_stop_time)
@@ -601,3 +684,134 @@ class Manager(Application):
         )
         # update the execution time scale factor
         self.simulator.set_time_scale_factor(time_scale_factor, sim_update_time)
+
+    def freeze(
+        self,
+        freeze_duration: timedelta = None,
+        sim_freeze_time: datetime = None,
+        resume_time: datetime = None,
+    ) -> None:
+        """
+        Command to freeze a test run execution by updating the execution freeze duration and publishing a freeze command.
+
+        Args:
+            freeze_duration (:obj:`timedelta`, optional): Duration for which to freeze execution.
+                                                        If None, creates an indefinite freeze.
+            sim_freeze_time (:obj:`datetime`, optional): Scenario time at which to freeze execution.
+                                                        If None, freezes immediately.
+        """
+        # publish a freeze command message
+        command_params = {"simFreezeTime": sim_freeze_time}
+        if freeze_duration is not None:
+            command_params["freezeDuration"] = freeze_duration
+        command = FreezeCommand.model_validate({"taskingParameters": command_params})
+        freeze_type = (
+            "indefinite" if freeze_duration is None else f"timed ({freeze_duration})"
+        )
+        logger.info(
+            f"Sending {freeze_type} freeze command {command.model_dump_json(by_alias=True)}."
+        )
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="freeze",
+            payload=command.model_dump_json(by_alias=True),
+        )
+
+        # If a future scenario freeze time is specified, wait until that time before pausing
+        if sim_freeze_time is not None:
+            try:
+                if self.simulator.get_time() < sim_freeze_time:
+                    target_wc = self.simulator.get_wallclock_time_at_simulation_time(
+                        sim_freeze_time
+                    )
+                    delay = (
+                        target_wc - self.simulator.get_wallclock_time()
+                    ).total_seconds()
+                    if delay > 0:
+                        self._sleep_with_heartbeat(delay)
+            except Exception as e:
+                logger.warning(
+                    f"Could not align to simFreezeTime={sim_freeze_time}: {e}"
+                )
+
+        # Freeze simulation time (skip if already paused/pausing)
+        if self.simulator.get_mode() not in (Mode.PAUSED, Mode.PAUSING):
+            self.simulator.pause()
+        # Wait until the simulator is paused to anchor the resume time
+        while self.simulator.get_mode() == Mode.PAUSING:
+            self._sleep_with_heartbeat(0.01)
+        while self.simulator.get_mode() != Mode.PAUSED:
+            if self.simulator.get_mode() in (Mode.TERMINATING, Mode.TERMINATED):
+                logger.info("Abort freeze wait due to termination")
+                return
+            self._sleep_with_heartbeat(0.01)
+
+        # Snapshot wallclock time at the moment of freeze
+        base = self.simulator.get_wallclock_time()
+
+        if freeze_duration is not None:
+            # Validate duration
+            if freeze_duration.total_seconds() <= 0:
+                logger.warning(
+                    f"Ignoring non-positive freeze duration: {freeze_duration}"
+                )
+                return
+
+            # Compute authoritative resume time
+            target_resume_time = base + freeze_duration
+            # Optionally honor requested resume_time if it's later than base
+            if resume_time is not None and resume_time > base:
+                # Keep the earlier of the two if you want to minimize drift across nodes,
+                # or the later if you prefer never resuming before a requested time.
+                # Here we choose the later to avoid early resume vs. a peer's expectation.
+                target_resume_time = max(target_resume_time, resume_time)
+
+            logger.info(
+                f"Resume Time: requested={resume_time} calculated={target_resume_time} "
+                f"delta={abs((target_resume_time - (resume_time or target_resume_time)).total_seconds())}s"
+            )
+
+            # Poll until we reach the target, allowing early exit and heartbeats
+            while True:
+                mode = self.simulator.get_mode()
+                if mode in (
+                    Mode.EXECUTING,
+                    Mode.RESUMING,
+                    Mode.TERMINATING,
+                    Mode.TERMINATED,
+                ):
+                    break
+                remaining = (
+                    target_resume_time - self.simulator.get_wallclock_time()
+                ).total_seconds()
+                if remaining <= 0:
+                    break
+                self._sleep_with_heartbeat(min(1.0, max(0.01, remaining)))
+        else:
+            logger.info("Indefinite freeze active. Call resume() to continue.")
+            while self.simulator.get_mode() not in (Mode.EXECUTING, Mode.RESUMING):
+                if self.simulator.get_mode() in (Mode.TERMINATING, Mode.TERMINATED):
+                    break
+                self._sleep_with_heartbeat(0.01)
+
+    def resume(self) -> None:
+        """
+        Command to resume a test run execution by unpausing the simulator.
+        """
+        # resume the simulator execution
+        command = ResumeCommand.model_validate(
+            {
+                "taskingParameters": {
+                    "resumeTime": self.simulator.get_wallclock_time(),
+                    "simResumeTime": self.simulator.get_time(),
+                }
+            }
+        )
+        logger.info(f"Sending resume command {command.model_dump_json(by_alias=True)}.")
+        self.send_message(
+            app_name=self.app_name,
+            app_topics="resume",
+            payload=command.model_dump_json(by_alias=True),
+        )
+        # resume simulation time
+        self.simulator.resume()

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/observer.py

@@ -247,6 +247,16 @@ class WallclockTimeIntervalCallback(Observer):
     ):
         from nost_tools.simulator import Mode, Simulator
 
+        # Reset timing when resuming
+        if (
+            property_name == Simulator.PROPERTY_MODE
+            and old_value == Mode.RESUMING
+            and new_value == Mode.EXECUTING
+        ):
+            wallclock_now = self.simulator.get_wallclock_time()
+            self._next_time = wallclock_now + (self.time_interval if self.time_interval is not None else timedelta())
+            return
+
         if property_name == Simulator.PROPERTY_MODE and new_value == Mode.INITIALIZED:
             self._next_time = self.time_init
         elif property_name == Simulator.PROPERTY_TIME:

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/publisher.py

@@ -125,6 +125,17 @@ class WallclockTimeIntervalPublisher(Observer, ABC):
             old_value (obj): old value of the named property
             new_value (obj): new value of the named property
         """
+        # Reset timing when resuming from pause
+        if (
+            property_name == Simulator.PROPERTY_MODE
+            and old_value == Mode.RESUMING
+            and new_value == Mode.EXECUTING
+        ):
+            self._next_time_status = self.app.simulator.get_wallclock_time()
+            if self.time_status_step is not None:
+                self._next_time_status += self.time_status_step
+            return
+
         if property_name == Simulator.PROPERTY_MODE and new_value == Mode.INITIALIZED:
             if self.time_status_init is None:
                 self._next_time_status = self.app.simulator.get_wallclock_time()

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/schemas.py

@@ -132,6 +132,162 @@ class UpdateCommand(BaseModel):
     )
 
 
+class FreezeTaskingParameters(BaseModel):
+    """
+    Tasking parameters to freeze an execution.
+    """
+
+    sim_freeze_time: datetime = Field(
+        ...,
+        gt=0,
+        description="Scenario time at which to freeze execution.",
+        alias="simFreezeTime",
+    )
+    freeze_duration: Optional[timedelta] = Field(
+        None,
+        # timedelta(seconds=60),
+        description="Wallclock time duration for which to freeze execution.",
+        alias="freezeDuration",
+    )
+
+
+class FreezeCommand(BaseModel):
+    """
+    Command message to freeze an execution.
+    """
+
+    tasking_parameters: FreezeTaskingParameters = Field(
+        ...,
+        description="Tasking parameters for the freeze command.",
+        alias="taskingParameters",
+    )
+
+
+class ResumeTaskingParameters(BaseModel):
+    """
+    Tasking parameters to resume an execution.
+    """
+
+    resume_time: datetime = Field(
+        ...,
+        gt=0,
+        description="Wallclock time at which to resume execution.",
+        alias="resumeTime",
+    )
+
+    sim_resume_time: datetime = Field(
+        ...,
+        gt=0,
+        description="Scenario time at which to resume execution.",
+        alias="simResumeTime",
+    )
+
+
+class ResumeCommand(BaseModel):
+    """
+    Command message to resume an execution.
+    """
+
+    tasking_parameters: ResumeTaskingParameters = Field(
+        ...,
+        description="Tasking parameters for the resume command.",
+        alias="taskingParameters",
+    )
+
+
+class FreezeRequestParameters(BaseModel):
+    """
+    Parameters for requesting a freeze from a managed application.
+    """
+
+    sim_freeze_time: datetime = Field(
+        ...,
+        gt=0,
+        description="Scenario time at which to freeze execution.",
+        alias="simFreezeTime",
+    )
+    freezeTime: datetime = Field(
+        ...,
+        description="Wallclock time at which to freeze execution.",
+        alias="freezeTime",
+    )
+    freeze_duration: Optional[timedelta] = Field(
+        None,
+        description="Wallclock time duration for which to freeze execution.",
+        alias="freezeDuration",
+    )
+    resume_time: Optional[datetime] = Field(
+        None,
+        description="Scenario time at which to resume execution.",
+        alias="resumeTime",
+    )
+    requesting_app: str = Field(
+        ...,
+        description="Name of the application requesting the freeze.",
+        alias="requestingApp",
+    )
+
+
+class FreezeRequest(BaseModel):
+    """
+    Request message for a managed application to request a freeze.
+    """
+
+    tasking_parameters: FreezeRequestParameters = Field(alias="taskingParameters")
+
+
+class ResumeRequestParameters(BaseModel):
+    """
+    Parameters for requesting a resume from a managed application.
+    """
+
+    requesting_app: str = Field(
+        ...,
+        description="Name of the application requesting the freeze.",
+        alias="requestingApp",
+    )
+
+
+class ResumeRequest(BaseModel):
+    """
+    Request message for a managed application to request a resume.
+    """
+
+    tasking_parameters: ResumeRequestParameters = Field(alias="taskingParameters")
+
+
+class UpdateRequestParameters(BaseModel):
+    """
+    Parameters for requesting an update from a managed application.
+    """
+
+    time_scale_factor: float = Field(
+        ...,
+        gt=0,
+        description="Time scaling factor (scenario seconds per wallclock second).",
+        alias="timeScalingFactor",
+    )
+    sim_update_time: Optional[datetime] = Field(
+        # ...,
+        None,
+        description="Scenario time at which to update the time scaling factor.",
+        alias="simUpdateTime",
+    )
+    requesting_app: str = Field(
+        ...,
+        description="Name of the application requesting the update.",
+        alias="requestingApp",
+    )
+
+
+class UpdateRequest(BaseModel):
+    """
+    Request message for a managed application to request an update.
+    """
+
+    tasking_parameters: UpdateRequestParameters = Field(alias="taskingParameters")
+
+
 class TimeStatusProperties(BaseModel):
     """
     Properties to report time status.
@@ -307,11 +463,8 @@ class ServersConfig(BaseModel):
         return values
 
 
-class WallclockOffsetProperties(BaseModel):
-    """
-    Properties to report wallclock offset.
-    """
-
+class GeneralConfig(BaseModel):
+    prefix: Optional[str] = Field("nost", description="Execution prefix.")
     wallclock_offset_refresh_interval: Optional[int] = Field(
         10800, description="Wallclock offset refresh interval, in seconds."
     )
@@ -320,23 +473,6 @@ class WallclockOffsetProperties(BaseModel):
     )
 
 
-class GeneralConfig(BaseModel):
-    prefix: Optional[str] = Field("nost", description="Execution prefix.")
-
-
-class TimeScaleUpdateSchema(BaseModel):
-    """
-    Provides a scheduled update to the simulation time scale factor.
-    """
-
-    time_scale_factor: float = Field(
-        ..., description="Scenario seconds per wallclock second"
-    )
-    sim_update_time: datetime = Field(
-        ..., description="Scenario time that the update will occur"
-    )
-
-
 class LoggingConfig(BaseModel):
     """
     Configuration for logging.
@@ -345,9 +481,7 @@ class LoggingConfig(BaseModel):
     enable_file_logging: Optional[bool] = Field(
         False, description="Enable file logging."
     )
-    log_dir: Optional[str] = Field(
-        "logs", description="Directory path for log files."
-    )
+    log_dir: Optional[str] = Field("logs", description="Directory path for log files.")
     log_filename: Optional[str] = Field(None, description="Path to the log file.")
     log_level: Optional[str] = Field(
         "INFO", description="Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)."
@@ -376,9 +510,6 @@ class ManagerConfig(LoggingConfig):
         description="Time step for the simulation.",
     )
     time_scale_factor: float = Field(1.0, description="Time scale factor.")
-    time_scale_updates: List[TimeScaleUpdateSchema] = Field(
-        default_factory=list, description="List of time scale updates."
-    )
     time_status_step: Optional[timedelta] = Field(None, description="Time status step.")
     time_status_init: Optional[datetime] = Field(None, description="Time status init.")
     command_lead: timedelta = Field(
@@ -586,9 +717,6 @@ class SimulationConfig(BaseModel):
 
 
 class RuntimeConfig(BaseModel):
-    wallclock_offset_properties: WallclockOffsetProperties = Field(
-        ..., description="Properties for wallclock offset."
-    )
     credentials: Credentials = Field(..., description="Credentials for authentication.")
     server_configuration: Config = (
         Field(..., description="Simulation configuration."),

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools/simulator.py

@@ -33,6 +33,9 @@ class Mode(str, Enum):
     INITIALIZING = "INITIALIZING"
     INITIALIZED = "INITIALIZED"
     EXECUTING = "EXECUTING"
+    PAUSING = "PAUSING"
+    PAUSED = "PAUSED"
+    RESUMING = "RESUMING"
     TERMINATING = "TERMINATING"
     TERMINATED = "TERMINATED"
 
@@ -89,12 +92,10 @@ class Simulator(Observable):
         Args:
             entity (:obj:`Entity`): entity to be added
         """
-        if self._mode == Mode.INITIALIZING:
-            raise RuntimeError("Cannot add entity: simulator is initializing")
-        elif self._mode == Mode.EXECUTING:
-            raise RuntimeError("Cannot add entity: simulator is executing")
-        elif self._mode == Mode.TERMINATING:
-            raise RuntimeError("Cannot add entity: simulator is terminating")
+        if self._mode not in [Mode.UNDEFINED, Mode.INITIALIZED, Mode.TERMINATED]:
+            raise RuntimeError(
+                "Can only add entity from UNDEFINED, INITIALIZED, or TERMINATED modes."
+            )
         self._set_mode(Mode.UNDEFINED)
         self._entities.append(entity)
 
@@ -141,12 +142,10 @@ class Simulator(Observable):
         Returns:
             :obj:`Entity`: removed entity
         """
-        if self._mode == Mode.INITIALIZING:
-            raise RuntimeError("Cannot add entity: simulator is initializing")
-        elif self._mode == Mode.EXECUTING:
-            raise RuntimeError("Cannot add entity: simulator is executing")
-        elif self._mode == Mode.TERMINATING:
-            raise RuntimeError("Cannot add entity: simulator is terminating")
+        if self._mode not in [Mode.UNDEFINED, Mode.INITIALIZED, Mode.TERMINATED]:
+            raise RuntimeError(
+                "Can only remove entity from UNDEFINED, INITIALIZED, or TERMINATED modes."
+            )
         if entity in self._entities:
             self._set_mode(Mode.UNDEFINED)
             return self._entities.remove(entity)
@@ -173,12 +172,10 @@ class Simulator(Observable):
                 initial scenario time, None uses the current wallclock time (default: None)
             time_scale_factor (float): number of scenario seconds per wallclock second (default: 1)
         """
-        if self._mode == Mode.INITIALIZING:
-            raise RuntimeError("Cannot initialize: simulator is initializing.")
-        elif self._mode == Mode.EXECUTING:
-            raise RuntimeError("Cannot initialize: simulator is executing.")
-        elif self._mode == Mode.TERMINATING:
-            raise RuntimeError("Cannot initialize: simulator is terminating.")
+        if self._mode not in [Mode.UNDEFINED, Mode.INITIALIZED, Mode.TERMINATED]:
+            raise RuntimeError(
+                "Can only initialize from UNDEFINED, INITIALIZED, or TERMINATED modes."
+            )
         self._set_mode(Mode.INITIALIZING)
         logger.info(
             f"Initializing simulator to time {init_time} (wallclock time {wallclock_epoch})"
@@ -219,6 +216,11 @@ class Simulator(Observable):
                 initial scenario time, None uses the current wallclock time (default: None)
             time_scale_factor (float): number of scenario seconds per wallclock second (default value: 1)
         """
+        if self._mode not in [Mode.UNDEFINED, Mode.INITIALIZED, Mode.TERMINATED]:
+            raise RuntimeError(
+                f"Cannot execute: simulator is {self._mode}. Wait for TERMINATED or terminate the current run."
+            )
+
         if self._mode != Mode.INITIALIZED:
             self.initialize(init_time, wallclock_epoch, time_scale_factor)
 
@@ -233,9 +235,8 @@ class Simulator(Observable):
 
         logger.info("Starting main simulation loop.")
         while (
-            self._mode == Mode.EXECUTING
-            and self.get_time() < self.get_init_time() + self.get_duration()
-        ):
+            self._mode == Mode.EXECUTING or self._mode == Mode.PAUSING
+        ) and self.get_time() < self.get_init_time() + self.get_duration():
             # compute time step (last step may be shorter)
             time_step = min(
                 self._time_step, self._init_time + self._duration - self._time
@@ -302,6 +303,17 @@ class Simulator(Observable):
         """
         Waits until the wallclock time matches the next time step interval.
         """
+        if self._mode == Mode.PAUSING:
+            self._set_mode(Mode.PAUSED)
+        while self._mode == Mode.PAUSED:
+            time.sleep(0.01)
+        if self._mode == Mode.RESUMING:
+            # reset the wallclock and simulation epochs
+            self._wallclock_epoch = self.get_wallclock_time()
+            self._simulation_epoch = self._time
+            self._set_mode(Mode.EXECUTING)
+            # Return immediately after resume to avoid waiting
+            return
         while (
             self._mode == Mode.EXECUTING
             and self.get_wallclock_time_at_simulation_time(self._next_time)
@@ -520,6 +532,25 @@ class Simulator(Observable):
             raise RuntimeError("Cannot set wallclock offset: simulator is terminating")
         self._wallclock_offset = wallclock_offset
 
+    def pause(self) -> None:
+        """
+        Pauses the scenario execution. Requires that the simulator is in EXECUTING mode.
+        """
+        logger.info("Pausing simulation execution.")
+        if self._mode != Mode.EXECUTING:
+            raise RuntimeError("Cannot pause: simulator is not executing.")
+
+        self._set_mode(Mode.PAUSING)
+
+    def resume(self) -> None:
+        """
+        Resumes the scenario execution. Requires that the simulator is in PAUSING or PAUSED mode.
+        """
+        if self._mode not in [Mode.PAUSING, Mode.PAUSED]:
+            raise RuntimeError("Cannot resume: simulator is not pausing or paused.")
+        self._next_time = self._time
+        self._set_mode(Mode.RESUMING)
+
     def terminate(self) -> None:
         """
         Terminates the scenario execution. Requires that the simulator is in EXECUTING mode.

{nost_tools-2.4.0 → nost_tools-3.0.0}/nost_tools.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: nost_tools
-Version: 2.4.0
+Version: 3.0.0
 Summary: Tools for Novel Observing Strategies Testbed (NOS-T) Applications
 Author-email: "Paul T. Grogan" <paul.grogan@asu.edu>, "Emmanuel M. Gonzalez" <emmanuelgonzalez@asu.edu>
 License-Expression: BSD-3-Clause