spectre-core 0.0.11__py3-none-any.whl → 0.0.13__py3-none-any.whl

spectre_core/capture_configs/_pvalidators.py

@@ -2,46 +2,64 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from logging import getLogger
-_LOGGER = getLogger(__name__)
-
-from dataclasses import dataclass
 from math import floor
+from typing import Optional, cast
+
 from scipy.signal import get_window
-from numbers import Number
-from warnings import warn
-from typing import Optional
 
 from ._parameters import Parameters
-from ._ptemplates import PNames
+from ._pnames import PName
 
+# ----------------------------------------------------------------------- # 
+# Throughout this module, repeated calls to `cast` will be seen on using the
+# `get_parameter_value` method. This is purely to signify intent and keep
+# the static type checkers happy.
+# 
+# This is okay, as whenever the validators are called, the parameter values 
+# have already been individually casted and constrained according to the 
+# parameter templates. There is negligible runtime impact. Though a bit
+# of a pain for maintenance.
+# ----------------------------------------------------------------------- # 
 
-def _validate_window(
+
+def validate_window(
         parameters: Parameters
 ) -> None:
-    window_size = parameters.get_parameter_value(PNames.WINDOW_SIZE)
-    window_type = parameters.get_parameter_value(PNames.WINDOW_TYPE)
-    sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-    batch_size  = parameters.get_parameter_value(PNames.BATCH_SIZE)
+    """Ensure that the capture config describes a valid window.
+
+    :param parameters: The parameters to be validated.
+    :raises ValueError: If the window interval is greater than the batch size.
+    :raises ValueError: If the specified window type cannot be fetched using 
+    the SciPy `get_window` function.
+    """
+    window_size = cast(int, parameters.get_parameter_value(PName.WINDOW_SIZE))
+    sample_rate = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
+    batch_size  = cast(int, parameters.get_parameter_value(PName.BATCH_SIZE))
+    window_type = cast(str, parameters.get_parameter_value(PName.WINDOW_TYPE))
     
     window_interval = window_size*(1 / sample_rate)
     if window_interval > batch_size:
-        raise ValueError((f"The windowing interval must be strictly less than the chunk size. "
+        raise ValueError((f"The windowing interval must be strictly less than the batch size. "
                           f"Computed the windowing interval to be {window_interval} [s], "
-                          f"but the chunk size is {batch_size} [s]"))
+                          f"but the batch size is {batch_size} [s]"))
     
     try:
         _ = get_window(window_type, window_size)
     except Exception as e:
-        raise Exception((f"An error has occurred while validating the window. "
-                         f"Got {str(e)}"))
+        raise ValueError((f"An error has occurred while validating the window. "
+                          f"Got {str(e)}"))
     
 
-def _validate_nyquist_criterion(
+def validate_nyquist_criterion(
         parameters: Parameters
 ) -> None:
-    sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-    bandwidth   = parameters.get_parameter_value(PNames.BANDWIDTH)
+    """Ensure that the Nyquist criterion is satisfied.
+
+    :param parameters: The parameters to be validated.
+    :raises ValueError: If the sample rate is less than the bandwidth.
+    """
+    sample_rate = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
+    bandwidth   = cast(float, parameters.get_parameter_value(PName.BANDWIDTH))
 
     if sample_rate < bandwidth:
         raise ValueError((f"Nyquist criterion has not been satisfied. "
@@ -51,56 +69,76 @@ def _validate_nyquist_criterion(
 
 def _compute_num_steps_per_sweep(min_freq: float, 
                                  max_freq: float,
-                                 samp_rate: int,
                                  freq_step: float) -> int:
-     return floor((max_freq - min_freq + samp_rate/2) / freq_step)
+    """Compute the number of steps in one frequency sweep.
 
+    The center frequency starts at `min_freq` and increments in steps of `freq_step` 
+    until the next step would exceed `max_freq`.
 
-def _validate_num_steps_per_sweep(
+    :param min_freq: The minimum frequency of the sweep.
+    :param max_freq: The maximum frequency of the sweep.
+    :param freq_step: The frequency step size.
+    :return: The number of steps in one frequency sweep.
+    """
+    return floor((max_freq - min_freq) / freq_step)
+
+
+def validate_num_steps_per_sweep(
         parameters: Parameters
 ) -> None:
-    min_freq    = parameters.get_parameter_value(PNames.MIN_FREQUENCY)
-    max_freq    = parameters.get_parameter_value(PNames.MAX_FREQUENCY)
-    sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-    freq_step   = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
+    """Ensure that there are at least two steps in frequency per sweep.
+
+    :param parameters: The parameters to be validated.
+    :raises ValueError: If the number of steps per sweep is less than or equal to one.
+    """
+    min_freq    = cast(float, parameters.get_parameter_value(PName.MIN_FREQUENCY))
+    max_freq    = cast(float, parameters.get_parameter_value(PName.MAX_FREQUENCY))
+    freq_step   = cast(float, parameters.get_parameter_value(PName.FREQUENCY_STEP))
 
     num_steps_per_sweep = _compute_num_steps_per_sweep(min_freq, 
                                                        max_freq, 
-                                                       sample_rate, 
                                                        freq_step)
     if num_steps_per_sweep <= 1:
         raise ValueError((f"We need strictly greater than one step per sweep. "
                           f"Computed {num_steps_per_sweep} step per sweep"))
     
 
-def _validate_sweep_interval(
+def validate_sweep_interval(
         parameters: Parameters
 ) -> None: 
-    min_freq         = parameters.get_parameter_value(PNames.MIN_FREQUENCY)
-    max_freq         = parameters.get_parameter_value(PNames.MAX_FREQUENCY)
-    sample_rate      = parameters.get_parameter_value(PNames.SAMPLE_RATE)
-    freq_step        = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
-    samples_per_step = parameters.get_parameter_value(PNames.SAMPLES_PER_STEP)
-    batch_size       = parameters.get_parameter_value(PNames.BATCH_SIZE)
+    """Ensure that the sweep interval is greater than the batch size.
+
+    :param parameters: The parameters to be validated.
+    :raises ValueError: If the sweep interval is greater than the batch size.
+    """
+    min_freq         = cast(float, parameters.get_parameter_value(PName.MIN_FREQUENCY))
+    max_freq         = cast(float, parameters.get_parameter_value(PName.MAX_FREQUENCY))
+    freq_step        = cast(float, parameters.get_parameter_value(PName.FREQUENCY_STEP))
+    samples_per_step = cast(int, parameters.get_parameter_value(PName.SAMPLES_PER_STEP))
+    batch_size       = cast(int, parameters.get_parameter_value(PName.BATCH_SIZE))
+    sample_rate      = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
 
     num_steps_per_sweep = _compute_num_steps_per_sweep(min_freq, 
                                                        max_freq, 
-                                                       sample_rate, 
                                                        freq_step)
     num_samples_per_sweep = num_steps_per_sweep * samples_per_step
     sweep_interval = num_samples_per_sweep * 1/sample_rate
     if sweep_interval > batch_size:
-        raise ValueError((f"Sweep interval must be less than the chunk size. "
+        raise ValueError((f"Sweep interval must be less than the batch size. "
                           f"The computed sweep interval is {sweep_interval} [s], "
-                          f"but the given chunk size is {batch_size} [s]"))
+                          f"but the given batch size is {batch_size} [s]"))
     
 
-def _validate_num_samples_per_step(
+def validate_num_samples_per_step(
         parameters: Parameters
 ) -> None:
+    """Ensure that the number of samples per step is greater than the window size.
 
-    window_size      = parameters.get_parameter_value(PNames.WINDOW_SIZE)
-    samples_per_step = parameters.get_parameter_value(PNames.SAMPLES_PER_STEP)
+    :param parameters: The parameters to be validated.
+    :raises ValueError: If the window size is greater than the number of samples per step.
+    """
+    window_size      = cast(int, parameters.get_parameter_value(PName.WINDOW_SIZE))
+    samples_per_step = cast(int, parameters.get_parameter_value(PName.SAMPLES_PER_STEP))
 
     if window_size >= samples_per_step:
         raise ValueError((f"Window size must be strictly less than the number of samples per step. "
@@ -108,12 +146,17 @@ def _validate_num_samples_per_step(
                           f"to the number of samples per step {samples_per_step}"))
     
 
-def _validate_non_overlapping_steps(
+def validate_non_overlapping_steps(
         parameters: Parameters
 ) -> None:
+    """Ensure that the stepped spectrograms are non-overlapping in the frequency domain.
+
+    :param parameters: The parameters to be validated.
+    :raises NotImplementedError: If the spectrograms overlap in the frequency domain.
+    """
     
-    freq_step = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
-    sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+    freq_step   = cast(float, parameters.get_parameter_value(PName.FREQUENCY_STEP))
+    sample_rate = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
 
     if freq_step < sample_rate:
         raise NotImplementedError(f"SPECTRE does not yet support spectral steps overlapping in frequency. "
@@ -121,51 +164,52 @@ def _validate_non_overlapping_steps(
                                   f"rate {sample_rate * 1e-6} [MHz]")
     
 
-def _validate_step_interval(
+def validate_step_interval(
         parameters: Parameters,
-        api_latency: Number
+        api_retuning_latency: float
 ) -> None:
-    
-    samples_per_step = parameters.get_parameter_value(PNames.SAMPLES_PER_STEP)
-    sample_rate      = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+    """Ensure that the time elapsed collecting samples at a fixed frequency is greater 
+    than the empirically derived API retuning latency.
+
+    :param parameters: The parameters to be validated.
+    :param api_retuning_latency: The empirically derived API retuning latency (in seconds).
+    :raises ValueError: If the time elapsed for a step is less than the API retuning latency.
+    """
+    samples_per_step = cast(int, parameters.get_parameter_value(PName.SAMPLES_PER_STEP))
+    sample_rate      = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
 
     step_interval = samples_per_step * 1/ sample_rate # [s]
-    if step_interval < api_latency:
+    if step_interval < api_retuning_latency:
         raise ValueError(f"The computed step interval of {step_interval} [s] is of the order of empirically "
-                         f"derived api latency {api_latency} [s]; you may experience undefined behaviour!")
+                         f"derived api latency {api_retuning_latency} [s]; you may experience undefined behaviour!")
 
 
-def _validate_fixed_center_frequency_parameters(
+def validate_fixed_center_frequency(
     parameters: Parameters
 ) -> None:
-    _validate_nyquist_criterion(parameters)
-    _validate_window(parameters)
+    """Apply validators for capture config parameters describing fixed center frequency capture.
 
+    :param parameters: The parameters to be validated.
+    """
+    validate_nyquist_criterion(parameters)
+    validate_window(parameters)
 
-def _validate_swept_center_frequency_parameters(
+
+def validate_swept_center_frequency(
     parameters: Parameters,
-    api_retuning_latency: Optional[Number] = None,
+    api_retuning_latency: Optional[float] = None,
 ) -> None:
-    _validate_nyquist_criterion(parameters)
-    _validate_window(parameters)
-    _validate_non_overlapping_steps(parameters)
-    _validate_num_steps_per_sweep(parameters)
-    _validate_num_samples_per_step(parameters)
-    _validate_sweep_interval(parameters)
+    """Apply validators for capture config parameters describing swept center frequency capture.
+
+    :param parameters: The parameters to be validated.
+    :param api_retuning_latency: The empirically derived API retuning latency. Defaults to None.
+    """
+    validate_nyquist_criterion(parameters)
+    validate_window(parameters)
+    validate_non_overlapping_steps(parameters)
+    validate_num_steps_per_sweep(parameters)
+    validate_num_samples_per_step(parameters)
+    validate_sweep_interval(parameters)
     
     if api_retuning_latency is not None:
-        _validate_step_interval(parameters, api_retuning_latency)
-    
-
-@dataclass(frozen=True)
-class PValidators:
-    window                 = _validate_window
-    nyquist_criterion      = _validate_nyquist_criterion
-    step_interval          = _validate_step_interval
-    non_overlapping_steps  = _validate_non_overlapping_steps
-    num_steps_per_sweep    = _validate_num_steps_per_sweep
-    num_samples_per_step   = _validate_num_samples_per_step
-    sweep_interval         = _validate_sweep_interval
-    step_interval          = _validate_step_interval
-    fixed_center_frequency = _validate_fixed_center_frequency_parameters
-    swept_center_frequency = _validate_swept_center_frequency_parameters
+        validate_step_interval(parameters, api_retuning_latency)

spectre_core/config/__init__.py

@@ -2,19 +2,17 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+
+"""General `spectre` package configurations."""
+
 from ._paths import (
-    get_spectre_data_dir_path, get_chunks_dir_path, get_configs_dir_path, get_logs_dir_path
+    get_spectre_data_dir_path, get_batches_dir_path, get_configs_dir_path, get_logs_dir_path
 )
 from ._time_formats import (
-    TimeFormats
+    TimeFormat
 )
 
 __all__ = [
-    "get_spectre_data_dir_path",
-    "get_chunks_dir_path",
-    "get_configs_dir_path",
-    "get_logs_dir_path",
-    "DEFAULT_DATE_FORMAT",
-    "DEFAULT_TIME_FORMAT",
-    "DEFAULT_DATETIME_FORMAT"
+    "get_spectre_data_dir_path", "get_batches_dir_path", "get_configs_dir_path", "get_logs_dir_path",
+    "TimeFormat"
 ]

spectre_core/config/_paths.py

@@ -3,39 +3,57 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 """
-SPECTRE data paths.
+File system path definitions.
+
+`spectre` uses the required environment variable `SPECTRE_DATA_DIR_PATH`
+and creates three directories inside it:  
+
+- `batches`: To hold the batched data files.
+- `logs`: To hold log files generated at runtime.
+- `configs`: To hold the capture config files.
 """
 
 import os
+from typing import Optional
 
-_SPECTRE_DATA_DIR_PATH = os.environ.get("SPECTRE_DATA_DIR_PATH")
-if _SPECTRE_DATA_DIR_PATH is None:
-    raise ValueError("The environment variable SPECTRE_DATA_DIR_PATH has not been set")
-
-_CHUNKS_DIR_PATH = os.environ.get("SPECTRE_CHUNKS_DIR_PATH", 
-                                  os.path.join(_SPECTRE_DATA_DIR_PATH, 'chunks'))
-os.makedirs(_CHUNKS_DIR_PATH, 
-            exist_ok=True)
+_SPECTRE_DATA_DIR_PATH = os.environ.get("SPECTRE_DATA_DIR_PATH", "NOTSET")
+if _SPECTRE_DATA_DIR_PATH == "NOTSET":
+    raise ValueError("The environment variable `SPECTRE_DATA_DIR_PATH` must be set.")
 
-_LOGS_DIR_PATH = os.environ.get("SPECTRE_LOGS_DIR_PATH",
-                               os.path.join(_SPECTRE_DATA_DIR_PATH, 'logs'))
-os.makedirs(_LOGS_DIR_PATH, 
-            exist_ok=True)
+_BATCHES_DIR_PATH = os.path.join(_SPECTRE_DATA_DIR_PATH, 'batches')
+_LOGS_DIR_PATH    = os.path.join(_SPECTRE_DATA_DIR_PATH, 'logs')
+_CONFIGS_DIR_PATH = os.path.join(_SPECTRE_DATA_DIR_PATH, "configs")
 
-_CONFIGS_DIR_PATH = os.environ.get("SPECTRE_CONFIGS_DIR_PATH",
-                                  os.path.join(_SPECTRE_DATA_DIR_PATH, "configs"))
-os.makedirs(_CONFIGS_DIR_PATH, 
-            exist_ok=True)
+os.makedirs(_BATCHES_DIR_PATH, exist_ok=True)
+os.makedirs(_LOGS_DIR_PATH,    exist_ok=True)
+os.makedirs(_CONFIGS_DIR_PATH, exist_ok=True)
 
 
 def get_spectre_data_dir_path(
 ) -> str:
+    """The default ancestral path for all `spectre` file system data.
+
+    :return: The value stored by the `SPECTRE_DATA_DIR_PATH` environment variable.
+    """
     return _SPECTRE_DATA_DIR_PATH
 
 
-def _get_date_based_dir_path(base_dir: str, year: int = None, 
-                             month: int = None, day: int = None
+def _get_date_based_dir_path(
+    base_dir: str, 
+    year: Optional[int] = None, 
+    month: Optional[int] = None, 
+    day: Optional[int] = None
 ) -> str:
+    """Append a date-based directory onto the base directory.
+
+    :param base_dir: The base directory to have the date directory appended to.
+    :param year: Numeric year. Defaults to None.
+    :param month: Numeric month. Defaults to None.
+    :param day: Numeric day. Defaults to None.
+    :raises ValueError: If a day is specified without the year or month.
+    :raises ValueError: If a month is specified without the year.
+    :return: The base directory with optional year, month, and day subdirectories appended.
+    """
     if day and not (year and month):
         raise ValueError("A day requires both a month and a year")
     if month and not year:
@@ -52,20 +70,38 @@ def _get_date_based_dir_path(base_dir: str, year: int = None,
     return os.path.join(base_dir, *date_dir_components)
 
 
-def get_chunks_dir_path(year: int = None, 
-                        month: int = None, 
-                        day: int = None
+def get_batches_dir_path(
+    year: Optional[int] = None, 
+    month: Optional[int] = None, 
+    day: Optional[int] = None
 ) -> str:
-    return _get_date_based_dir_path(_CHUNKS_DIR_PATH, 
+    """The directory in the file system containing the batched data files. Optionally, append
+    a date-based directory to the end of the path.
+
+    :param year: The numeric year. Defaults to None.
+    :param month: The numeric month. Defaults to None.
+    :param day: The numeric day. Defaults to None.
+    :return: The directory path for batched data files, optionally with a date-based subdirectory.
+    """
+    return _get_date_based_dir_path(_BATCHES_DIR_PATH, 
                                     year, 
                                     month, 
                                     day)
 
 
-def get_logs_dir_path(year: int = None, 
-                      month: int = None, 
-                      day: int = None
+def get_logs_dir_path(
+    year: Optional[int] = None, 
+    month: Optional[int] = None, 
+    day: Optional[int] = None
 ) -> str:
+    """The directory in the file system containing the log files generated at runtime. Optionally, append
+    a date-based directory to the end of the path.
+
+    :param year: The numeric year. Defaults to None.
+    :param month: The numeric month. Defaults to None.
+    :param day: The numeric day. Defaults to None.
+    :return: The directory path for log files, optionally with a date-based subdirectory.
+    """
     return _get_date_based_dir_path(_LOGS_DIR_PATH, 
                                     year, 
                                     month, 
@@ -74,4 +110,8 @@ def get_logs_dir_path(year: int = None,
 
 def get_configs_dir_path(
 ) -> str:
+    """The directory in the file system containing the capture configs.
+
+    :return: The directory path for configuration files.
+    """
     return _CONFIGS_DIR_PATH

spectre_core/config/_time_formats.py

@@ -2,14 +2,21 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-"""
-Package-wide default datetime formats.
-"""
-
 from dataclasses import dataclass
 
+
 @dataclass(frozen=True)
-class TimeFormats:
-    TIME     = "%H:%M:%S"
-    DATE     = "%Y-%m-%d"
-    DATETIME = f"{DATE}T{TIME}"
+class TimeFormat:
+    """Package-wide datetime formats.
+
+    :ivar DATE: Format for dates (e.g., '2025-01-11').
+    :ivar TIME: Format for times (e.g., '23:59:59').
+    :ivar DATETIME: Combined date and time format (e.g., '2025-01-11T23:59:59').
+    :ivar PRECISE_TIME: Format for times with microseconds (e.g., '23:59:59.123456').
+    :ivar PRECISE_DATETIME: Combined date and precise time format (e.g., '2025-01-11T23:59:59.123456').
+    """
+    DATE              = "%Y-%m-%d"
+    TIME              = "%H:%M:%S"
+    DATETIME          = f"{DATE}T{TIME}"
+    PRECISE_TIME      = "%H:%M:%S.%f"
+    PRECISE_DATETIME  = f"{DATE}T{PRECISE_TIME}"

spectre_core/exceptions.py

@@ -3,12 +3,10 @@
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 """
-SPECTRE custom exceptions.
+`spectre` custom exceptions.
 """
 
-class ChunkNotFoundError(FileNotFoundError): ...
-class ChunkFileNotFoundError(FileNotFoundError): ...
-class SpectrogramNotFoundError(FileNotFoundError): ...
+class BatchNotFoundError(KeyError): ...
 class ModeNotFoundError(KeyError): ...
 class EventHandlerNotFoundError(KeyError): ...
 class ReceiverNotFoundError(KeyError): ...

spectre_core/jobs/__init__.py

@@ -0,0 +1,14 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""Manage `spectre` jobs and workers."""
+
+from ._jobs import Job, start_job
+from ._workers import (
+    Worker, make_worker, do_capture, do_post_processing
+)
+
+__all__ = [
+    "Job", "Worker", "make_worker", "start_job", "do_capture", "do_post_processing"
+]

spectre_core/jobs/_jobs.py

@@ -0,0 +1,111 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from logging import getLogger
+_LOGGER = getLogger(__name__)
+
+import time
+
+from ._workers import Worker
+
+class Job:
+    """Represents a collection of workers that run long-running tasks as 
+    multiprocessing processes.
+
+    A `Job` manages the lifecycle of its workers, including starting, 
+    monitoring, and terminating them.
+    """
+    def __init__(
+        self,
+        workers: list[Worker]
+    ) -> None:
+        """Initialise a `Job` with a list of workers.
+
+        :param workers: A list of `Worker` instances to manage as part of the job.
+        """
+        self._workers = workers
+
+
+    def start(
+        self,
+    ) -> None:
+        """Tell each worker to call their functions in the background as multiprocessing processes."""
+        for worker in self._workers:
+            worker.start()
+            
+            
+    def terminate(
+        self,
+    ) -> None:
+        """Tell each worker to terminate their processes, if the processes are still running."""
+        _LOGGER.info("Terminating workers...")
+        for worker in self._workers:
+            if worker.process.is_alive():
+                worker.process.terminate()
+                worker.process.join()
+        _LOGGER.info("All workers successfully terminated")
+        
+        
+    def monitor(
+        self,
+        total_runtime: float, 
+        force_restart: bool = False
+    ) -> None:
+        """
+        Monitor the workers during execution and handle unexpected exits.
+
+        Periodically checks worker processes within the specified runtime duration. 
+        If a worker exits unexpectedly:
+        - Restarts all workers if `force_restart` is True.
+        - Terminates all workers and raises an exception if `force_restart` is False.
+
+        :param total_runtime: Total time to monitor the workers, in seconds.
+        :param force_restart: Whether to restart all workers if one exits unexpectedly.
+        :raises RuntimeError: If a worker exits and `force_restart` is False.
+        """
+        _LOGGER.info("Monitoring workers...")
+        start_time = time.time()
+
+        try:
+            while time.time() - start_time < total_runtime:
+                for worker in self._workers:
+                    if not worker.process.is_alive():
+                        error_message = f"Worker with name `{worker.name}` unexpectedly exited."
+                        _LOGGER.error(error_message)
+                        if force_restart:
+                            # Restart all workers
+                            for worker in self._workers:
+                                worker.restart()
+                        else:
+                            self.terminate()
+                            raise RuntimeError(error_message)
+                time.sleep(1)  # Poll every second
+
+            _LOGGER.info("Session duration reached. Terminating workers...")
+            self.terminate()
+
+        except KeyboardInterrupt:
+            _LOGGER.info("Keyboard interrupt detected. Terminating workers...")
+            self.terminate()
+
+    
+def start_job(
+    workers: list[Worker],
+    total_runtime: float,
+    force_restart: bool = False
+) -> None:
+    """Create and run a job with the specified workers.
+
+    Starts the workers, monitors them for the specified runtime, and handles 
+    unexpected exits according to the `force_restart` policy.
+
+    :param workers: A list of `Worker` instances to include in the job.
+    :param total_runtime: Total time to monitor the job, in seconds.
+    :param force_restart: Whether to restart all workers if one exits unexpectedly.
+    Defaults to False.
+    """
+    job = Job(workers)
+    job.start()
+    job.monitor(total_runtime, force_restart)
+