Freeze, Resume, and Update System

As of version 3.0.0, NOS-T supports a distributed freeze/resume/update system that allows managed applications to dynamically request changes to simulation execution. This replaces the previous YAML-based time_scale_updates configuration.

Overview

The system follows a request-command pattern:

  1. A ManagedApplication sends a request message (e.g., FreezeRequest) to the Manager.

  2. The Manager receives the request, validates it, and issues a command message (e.g., FreezeCommand) to all applications.

  3. All applications respond to the command by pausing, resuming, or updating their simulators.

This design ensures that all applications freeze and resume in a coordinated manner, with the Manager maintaining control of the simulation timeline.

        ---
config:
    theme: neutral
    look: neo
---
sequenceDiagram
    participant MA as ManagedApplication
    participant M as Manager
    participant All as All Applications

    MA->>M: FreezeRequest
    M->>All: FreezeCommand
    Note over All: All pause

    MA->>M: ResumeRequest
    M->>All: ResumeCommand
    Note over All: All resume

Requesting a Freeze

A managed application can request a freeze using the request_freeze() method:

# Freeze immediately for 5 minutes
app.request_freeze(
    freeze_duration=timedelta(minutes=5)
)

# Freeze at a specific scenario time for 10 minutes
app.request_freeze(
    freeze_duration=timedelta(minutes=10),
    sim_freeze_time=datetime(2020, 1, 1, 8, 0, 0, tzinfo=timezone.utc)
)

# Indefinite freeze (requires a separate resume request)
app.request_freeze()

Parameters:

  • freeze_duration (Optional[timedelta]): How long to freeze. If None, the freeze is indefinite and requires an explicit resume request.

  • sim_freeze_time (Optional[datetime]): The scenario time at which to freeze. If None, freezes immediately.

Indefinite vs Timed Freezes

  • Timed freeze: When freeze_duration is provided, the Manager will automatically resume after the specified duration elapses.

  • Indefinite freeze: When freeze_duration is None, the simulation remains frozen until a managed application explicitly sends a ResumeRequest.

Requesting a Resume

A managed application (or unmanaged Application) can request a resume using the request_resume() method:

# Resume immediately
app.request_resume()

# Resume with a target scenario time and tolerance
app.request_resume(
    sim_resume_time=datetime(2020, 1, 1, 8, 0, 0, tzinfo=timezone.utc),
    tolerance=timedelta(minutes=30)
)

Parameters:

  • sim_resume_time (Optional[datetime]): Target scenario time for resume. If None, resumes immediately.

  • tolerance (Optional[timedelta]): If provided, the Manager only resumes if the current scenario time is within this tolerance of sim_resume_time. If not provided, defaults to the global resume_tolerance configuration.

Resume Tolerance

The tolerance mechanism allows managed applications to send multiple resume requests, with the Manager only acting when the scenario time is within the specified window. This is useful for applications that periodically check conditions and request resume when appropriate.

Tolerance behavior:

  • If tolerance is not provided: ResumeCommand is sent immediately (regardless of sim_resume_time).

  • If tolerance is provided with sim_resume_time: The Manager checks if the current scenario time is within tolerance of the requested time.

    • Within tolerance: ResumeCommand is sent immediately.

    • Outside tolerance: The request is ignored.

  • If only tolerance is provided (no sim_resume_time): ResumeCommand is sent immediately.

The global default tolerance can be configured in YAML:

execution:
  general:
    resume_tolerance: "12:00:00"  # 12 hours (default)

Requesting a Time Scale Update

A managed application can request a change to the time scale factor during execution:

# Update time scale factor immediately
app.request_update(
    time_scale_factor=120.0
)

# Update at a specific scenario time
app.request_update(
    time_scale_factor=120.0,
    sim_update_time=datetime(2020, 1, 1, 8, 20, 0, tzinfo=timezone.utc)
)

Parameters:

  • time_scale_factor (float): The new time scale factor (scenario seconds per wallclock second).

  • sim_update_time (Optional[datetime]): The scenario time at which to apply the update. If None, updates immediately.

Message Schemas

The following message schemas are used in the freeze/resume/update system. See the API Reference for full field documentation.

Commands (Manager to all applications):

  • FreezeCommand / FreezeTaskingParameters

  • ResumeCommand / ResumeTaskingParameters

Requests (Managed applications to Manager):

  • FreezeRequest / FreezeRequestParameters

  • ResumeRequest / ResumeRequestParameters

  • UpdateRequest / UpdateRequestParameters