spectre-core 0.0.22__py3-none-any.whl → 0.0.24__py3-none-any.whl

spectre_core/capture_configs/_pvalidators.py

@@ -10,69 +10,63 @@ from scipy.signal import get_window
 from ._parameters import Parameters
 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(
-        parameters: Parameters
-) -> None:
+
+def validate_window(parameters: Parameters) -> None:
     """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 
+    :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))
+    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)
+
+    window_interval = window_size * (1 / sample_rate)
     if window_interval > batch_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 batch size is {batch_size} [s]"))
-    
+        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 batch size is {batch_size} [s]"
+            )
+        )
+
     try:
         _ = get_window(window_type, window_size)
     except Exception as e:
-        raise ValueError((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(
-        parameters: Parameters
-) -> None:
+
+def validate_nyquist_criterion(parameters: Parameters) -> None:
     """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))
+    bandwidth = cast(float, parameters.get_parameter_value(PName.BANDWIDTH))
 
     if sample_rate < bandwidth:
-        raise ValueError((f"Nyquist criterion has not been satisfied. "
-                          f"Sample rate must be greater than or equal to the bandwidth. "
-                          f"Got sample rate {sample_rate} [Hz], and bandwidth {bandwidth} [Hz]"))
-    
-
-def _compute_num_steps_per_sweep(min_freq: float, 
-                                 max_freq: float,
-                                 freq_step: float) -> int:
+        raise ValueError(
+            (
+                f"Nyquist criterion has not been satisfied. "
+                f"Sample rate must be greater than or equal to the bandwidth. "
+                f"Got sample rate {sample_rate} [Hz], and bandwidth {bandwidth} [Hz]"
+            )
+        )
+
+
+def _compute_num_steps_per_sweep(
+    min_freq: float, max_freq: float, freq_step: float
+) -> int:
     """Compute the number of steps in one frequency sweep.
 
-    The center frequency starts at `min_freq` and increments in steps of `freq_step` 
+    The center frequency starts at `min_freq` and increments in steps of `freq_step`
     until the next step would exceed `max_freq`.
 
     :param min_freq: The minimum frequency of the sweep.
@@ -83,92 +77,91 @@ def _compute_num_steps_per_sweep(min_freq: float,
     return floor((max_freq - min_freq) / freq_step)
 
 
-def validate_num_steps_per_sweep(
-        parameters: Parameters
-) -> None:
+def validate_num_steps_per_sweep(parameters: Parameters) -> None:
     """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))
+    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, 
-                                                       freq_step)
+    num_steps_per_sweep = _compute_num_steps_per_sweep(min_freq, max_freq, 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"))
-    
+        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(
-        parameters: Parameters
-) -> None: 
+def validate_sweep_interval(parameters: Parameters) -> None:
     """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))
+    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))
+    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, 
-                                                       freq_step)
+    num_steps_per_sweep = _compute_num_steps_per_sweep(min_freq, max_freq, freq_step)
     num_samples_per_sweep = num_steps_per_sweep * samples_per_step
-    sweep_interval = num_samples_per_sweep * 1/sample_rate
+    sweep_interval = num_samples_per_sweep * 1 / sample_rate
     if sweep_interval > batch_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 batch size is {batch_size} [s]"))
-    
+        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 batch size is {batch_size} [s]"
+            )
+        )
 
-def validate_num_samples_per_step(
-        parameters: Parameters
-) -> None:
+
+def validate_num_samples_per_step(parameters: Parameters) -> None:
     """Ensure that the number of samples per step is greater than the window size.
 
     :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))
+    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. "
-                          f"Got window size {window_size} [samples], which is more than or equal "
-                          f"to the number of samples per step {samples_per_step}"))
-    
+        raise ValueError(
+            (
+                f"Window size must be strictly less than the number of samples per step. "
+                f"Got window size {window_size} [samples], which is more than or equal "
+                f"to the number of samples per step {samples_per_step}"
+            )
+        )
 
-def validate_non_overlapping_steps(
-        parameters: Parameters
-) -> None:
+
+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   = cast(float, parameters.get_parameter_value(PName.FREQUENCY_STEP))
+
+    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. "
-                                  f"Got frequency step {freq_step * 1e-6} [MHz] which is less than the sample "
-                                  f"rate {sample_rate * 1e-6} [MHz]")
-    
-
-def validate_step_interval(
-        parameters: Parameters,
-        api_retuning_latency: float
-) -> None:
-    """Ensure that the time elapsed collecting samples at a fixed frequency is greater 
+        raise NotImplementedError(
+            f"SPECTRE does not yet support spectral steps overlapping in frequency. "
+            f"Got frequency step {freq_step * 1e-6} [MHz] which is less than the sample "
+            f"rate {sample_rate * 1e-6} [MHz]"
+        )
+
+
+def validate_step_interval(parameters: Parameters, api_retuning_latency: float) -> None:
+    """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.
@@ -176,12 +169,14 @@ def validate_step_interval(
     :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))
+    sample_rate = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
 
-    step_interval = samples_per_step * 1/ sample_rate # [s]
+    step_interval = samples_per_step * 1 / sample_rate  # [s]
     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_retuning_latency} [s]; you may experience undefined behaviour!")
+        raise ValueError(
+            f"The computed step interval of {step_interval} [s] is of the order of empirically "
+            f"derived api latency {api_retuning_latency} [s]; you may experience undefined behaviour!"
+        )
 
 
 def validate_sample_rate_with_master_clock_rate(
@@ -192,17 +187,19 @@ def validate_sample_rate_with_master_clock_rate(
     :param parameters: The parameters to be validated.
     :raises ValueError: If the master clock rate is not an integer multiple of the sample rate
     """
-    master_clock_rate = cast(int, parameters.get_parameter_value(PName.MASTER_CLOCK_RATE))
-    sample_rate       = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
+    master_clock_rate = cast(
+        int, parameters.get_parameter_value(PName.MASTER_CLOCK_RATE)
+    )
+    sample_rate = cast(int, parameters.get_parameter_value(PName.SAMPLE_RATE))
 
     if master_clock_rate % sample_rate != 0:
-        raise ValueError(f"The master clock rate of {master_clock_rate} [Hz] is not an integer "
-                         f"multiple of the sample rate {sample_rate} [Hz].")
+        raise ValueError(
+            f"The master clock rate of {master_clock_rate} [Hz] is not an integer "
+            f"multiple of the sample rate {sample_rate} [Hz]."
+        )
 
 
-def validate_fixed_center_frequency(
-    parameters: Parameters
-) -> None:
+def validate_fixed_center_frequency(parameters: Parameters) -> None:
     """Apply validators for capture config parameters describing fixed center frequency capture.
 
     :param parameters: The parameters to be validated.
@@ -226,6 +223,6 @@ def validate_swept_center_frequency(
     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)

spectre_core/config/__init__.py

@@ -5,15 +5,26 @@
 
 """General `spectre` package configurations."""
 
+import os
+
 from ._paths import (
-    get_spectre_data_dir_path, get_batches_dir_path, get_configs_dir_path, 
-    get_logs_dir_path, trim_spectre_data_dir_path
-)
-from ._time_formats import (
-    TimeFormat
+    get_spectre_data_dir_path,
+    get_batches_dir_path,
+    get_configs_dir_path,
+    get_logs_dir_path,
+    trim_spectre_data_dir_path,
 )
+from ._time_formats import TimeFormat
+
+os.makedirs(get_batches_dir_path(), exist_ok=True)
+os.makedirs(get_logs_dir_path(), exist_ok=True)
+os.makedirs(get_configs_dir_path(), exist_ok=True)
 
 __all__ = [
-    "get_spectre_data_dir_path", "get_batches_dir_path", "get_configs_dir_path", "get_logs_dir_path",
-    "TimeFormat", "trim_spectre_data_dir_path"
-]
+    "get_spectre_data_dir_path",
+    "get_batches_dir_path",
+    "get_configs_dir_path",
+    "get_logs_dir_path",
+    "TimeFormat",
+    "trim_spectre_data_dir_path",
+]

spectre_core/config/_paths.py

@@ -6,7 +6,7 @@
 File system path definitions.
 
 `spectre` uses the required environment variable `SPECTRE_DATA_DIR_PATH`
-and creates three directories inside it:  
+and creates three directories inside it:
 
 - `batches`: To hold the batched data files.
 - `logs`: To hold log files generated at runtime.
@@ -16,33 +16,25 @@ and creates three directories inside it:
 import os
 from typing import Optional
 
-_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.")
 
-_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")
-
-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:
+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.
     """
+    _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."
+        )
     return _SPECTRE_DATA_DIR_PATH
 
 
 def _get_date_based_dir_path(
-    base_dir: str, 
-    year: Optional[int] = None, 
-    month: Optional[int] = None, 
-    day: Optional[int] = None
+    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.
 
@@ -58,7 +50,7 @@ def _get_date_based_dir_path(
         raise ValueError("A day requires both a month and a year")
     if month and not year:
         raise ValueError("A month requires a year")
-    
+
     date_dir_components = []
     if year:
         date_dir_components.append(f"{year:04}")
@@ -66,14 +58,12 @@ def _get_date_based_dir_path(
         date_dir_components.append(f"{month:02}")
     if day:
         date_dir_components.append(f"{day:02}")
-    
+
     return os.path.join(base_dir, *date_dir_components)
 
 
 def get_batches_dir_path(
-    year: Optional[int] = None, 
-    month: Optional[int] = None, 
-    day: Optional[int] = None
+    year: Optional[int] = None, month: Optional[int] = None, day: Optional[int] = None
 ) -> str:
     """The directory in the file system containing the batched data files. Optionally, append
     a date-based directory to the end of the path.
@@ -83,16 +73,12 @@ def get_batches_dir_path(
     :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)
+    batches_dir_path = os.path.join(get_spectre_data_dir_path(), "batches")
+    return _get_date_based_dir_path(batches_dir_path, year, month, day)
 
 
 def get_logs_dir_path(
-    year: Optional[int] = None, 
-    month: Optional[int] = None, 
-    day: Optional[int] = None
+    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.
@@ -102,24 +88,19 @@ def get_logs_dir_path(
     :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, 
-                                    day)
+    logs_dir_path = os.path.join(get_spectre_data_dir_path(), "logs")
+    return _get_date_based_dir_path(logs_dir_path, year, month, day)
 
 
-def get_configs_dir_path(
-) -> str:
+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
+    return os.path.join(get_spectre_data_dir_path(), "configs")
 
 
-def trim_spectre_data_dir_path(
-    full_path: str
-) -> str:
+def trim_spectre_data_dir_path(full_path: str) -> str:
     """Remove the `SPECTRE_DATA_DIR_PATH` prefix from a full file path.
 
     This function returns the relative path of `full_path` with respect to
@@ -130,12 +111,10 @@ def trim_spectre_data_dir_path(
     :param full_path: The full file path to be trimmed.
     :return: The relative path with `SPECTRE_DATA_DIR_PATH` removed.
     """
-    return os.path.relpath(full_path, _SPECTRE_DATA_DIR_PATH)
+    return os.path.relpath(full_path, get_spectre_data_dir_path())
 
 
-def add_spectre_data_dir_path(
-    rel_path: str
-) -> str:
+def add_spectre_data_dir_path(rel_path: str) -> str:
     """Prepend the `SPECTRE_DATA_DIR_PATH` prefix to a relative file path.
 
     This function constructs an absolute path by joining the given relative
@@ -145,5 +124,4 @@ def add_spectre_data_dir_path(
     :param rel_path: The relative file path to be appended.
     :return: The full file path prefixed with `SPECTRE_DATA_DIR_PATH`.
     """
-    return os.path.join(_SPECTRE_DATA_DIR_PATH, rel_path)
-
+    return os.path.join(get_spectre_data_dir_path(), rel_path)

spectre_core/config/_time_formats.py

@@ -15,8 +15,9 @@ class TimeFormat:
     :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}"
+
+    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

@@ -6,9 +6,47 @@
 `spectre` custom exceptions.
 """
 
+import warnings
+from functools import wraps
+from typing import TypeVar, Callable, Any, cast
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def deprecated(message: str) -> Callable[[F], F]:
+    """A decorator to mark functions as deprecated.
+
+    :param message: Warning message explaining what to use instead
+    """
+
+    def decorator(func: F) -> F:
+        @wraps(func)
+        def wrapper(*args: Any, **kwargs: Any) -> Any:
+            warnings.warn(
+                f"{func.__name__} is deprecated. {message}",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            return func(*args, **kwargs)
+
+        return cast(F, wrapper)
+
+    return decorator
+
+
 class BatchNotFoundError(KeyError): ...
+
+
 class ModeNotFoundError(KeyError): ...
+
+
 class EventHandlerNotFoundError(KeyError): ...
+
+
 class ReceiverNotFoundError(KeyError): ...
+
+
 class InvalidTagError(ValueError): ...
+
+
 class InvalidSweepMetadataError(ValueError): ...

spectre_core/jobs/__init__.py

@@ -5,10 +5,7 @@
 """Manage `spectre` jobs and workers."""
 
 from ._jobs import Job, start_job
-from ._workers import (
-    Worker, make_worker, do_capture, do_post_processing
-)
+from ._workers import Worker, make_worker
+from ._duration import Duration
 
-__all__ = [
-    "Job", "Worker", "make_worker", "start_job", "do_capture", "do_post_processing"
-]
+__all__ = ["Job", "Worker", "make_worker", "start_job", "Duration"]

spectre_core/jobs/_duration.py

@@ -0,0 +1,12 @@
+# SPDX-FileCopyrightText: © 2024-2025 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+
+class Duration:
+    """A selection of set durations, in seconds."""
+
+    ONE_CENTISECOND = 0.01
+    ONE_DECISECOND = 0.1
+    ONE_SECOND = 1.0
+    TEN_SECONDS = 10.0