spectre-core 0.0.21__py3-none-any.whl → 0.0.23__py3-none-any.whl

spectre_core/receivers/_base.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# SPDX-FileCopyrightText: © 2024-2025 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -6,19 +6,15 @@ from abc import ABC, abstractmethod
 from typing import Callable, Optional, Literal, overload, Any
 
 from spectre_core.exceptions import ModeNotFoundError
-from spectre_core.capture_configs import (
-    CaptureTemplate, Parameters, CaptureConfig
-)
+from spectre_core.capture_configs import CaptureTemplate, Parameters, CaptureConfig
 from .plugins._receiver_names import ReceiverName
 from ._spec_names import SpecName
 
+
 class BaseReceiver(ABC):
     """Abstract base class for software-defined radio receivers."""
-    def __init__(
-        self, 
-        name: ReceiverName, 
-        mode: Optional[str] = None
-    ) -> None:
+
+    def __init__(self, name: ReceiverName, mode: Optional[str] = None) -> None:
         """Initialise an instance of `BaseReceiver`.
 
         :param name: The name of the receiver.
@@ -26,165 +22,126 @@ class BaseReceiver(ABC):
         """
         self._name = name
 
-        self._specs: dict[SpecName, float|int|list[float|int]] = {}
+        self._specs: dict[SpecName, float | int | list[float | int]] = {}
         self._add_specs()
-        
+
         self._capture_methods: dict[str, Callable[[str, Parameters], None]] = {}
         self._add_capture_methods()
-        
+
         self._capture_templates: dict[str, CaptureTemplate] = {}
         self._add_capture_templates()
-    
+
         self._pvalidators: dict[str, Callable[[Parameters], None]] = {}
         self._add_pvalidators()
 
-        self._mode = None
-        if mode is not None:
-            self.mode = mode
-
+        self._mode: Optional[str] = mode
 
     @abstractmethod
-    def _add_specs(
-        self
-    ) -> None:
+    def _add_specs(self) -> None:
         """Subclasses must use `add_spec` to add hardware specifications."""
-    
 
     @abstractmethod
-    def _add_capture_methods(
-        self
-    ) -> None:
-        """Subclasses must use `add_capture_method` to specify which method is called to capture 
+    def _add_capture_methods(self) -> None:
+        """Subclasses must use `add_capture_method` to specify which method is called to capture
         data, for each operating mode."""
-        
 
     @abstractmethod
-    def _add_capture_templates(
-        self
-    ) -> None:
+    def _add_capture_templates(self) -> None:
         """Subclasses must use `add_capture_template` to define a `CaptureTemplate` for each operating mode."""
 
-
     @abstractmethod
-    def _add_pvalidators(
-        self
-    ) -> None:
-        """Subclasses must use `add_pvalidator` to add a parameter validation function (pvalidator) 
+    def _add_pvalidators(self) -> None:
+        """Subclasses must use `add_pvalidator` to add a parameter validation function (pvalidator)
         for each operating mode."""
 
-    
     @property
-    def name(
-        self
-    ) -> ReceiverName:
+    def name(self) -> ReceiverName:
         """The name of the receiver."""
         return self._name
-    
 
     @property
-    def capture_methods(
-        self
-    ) -> dict[str, Callable[[str, Parameters], None]]:
+    def capture_methods(self) -> dict[str, Callable[[str, Parameters], None]]:
         """For each operating mode, the method which is called to capture data."""
         return self._capture_methods
-  
-  
+
     @property
-    def capture_templates(
-        self
-    ) -> dict[str, CaptureTemplate]:
+    def capture_templates(self) -> dict[str, CaptureTemplate]:
         """For each operating mode, the corresponding `CaptureTemplate`."""
-        return self._capture_templates  
-
+        return self._capture_templates
 
     @property
-    def pvalidators(
-        self
-    ) -> dict[str, Callable[[Parameters], None]]:
+    def pvalidators(self) -> dict[str, Callable[[Parameters], None]]:
         """For each operating mode, the corresponding parameter validation function (pvalidator)."""
         return self._pvalidators
 
-
     @property
-    def specs(
-        self
-    ) -> dict[SpecName, float|int|list[float|int]]:
+    def specs(self) -> dict[SpecName, float | int | list[float | int]]:
         """The hardware specifications."""
         return self._specs
 
-
     @property
-    def modes(
-        self
-    ) -> list[str]:
+    def modes(self) -> list[str]:
         """The operating modes for the receiver.
 
         :raises ValueError: If the modes are inconsistent between `capture_methods`,
         `pvalidators` and `capture_templates`.
         """
-        capture_method_modes    = list(self.capture_methods.keys())
-        pvalidator_modes        = list(self.pvalidators.keys())
-        capture_template_modes  = list(self.capture_templates.keys())
-        
+        capture_method_modes = list(self.capture_methods.keys())
+        pvalidator_modes = list(self.pvalidators.keys())
+        capture_template_modes = list(self.capture_templates.keys())
+
         if not capture_method_modes == pvalidator_modes == capture_template_modes:
             raise ValueError(f"Mode mismatch for the receiver {self.name}.")
         return capture_method_modes
 
-
     @property
-    def mode(
-        self
-    ) -> str:
-        """The active operating mode for the receiver."""
-        if self._mode is None:
-            raise ValueError(f"The operating mode for the receiver `{self.name.value}` is not set.")
+    def mode(self) -> Optional[str]:
+        """The active operating mode for the receiver, if set."""
         return self._mode
 
-
     @mode.setter
-    def mode(
-        self, 
-        value: str,
-    ) -> None:
+    def mode(self, value: str) -> None:
         """Set the active operating mode.
 
         :param value: The new operating mode to activate.
         :raises ModeNotFoundError: If the specified mode is not defined in `modes`.
         """
-        if (value not in self.modes):
-            raise ModeNotFoundError((f"{value} is not a defined mode for the receiver {self.name}. "
-                                     f"Expected one of {self.modes}"))
+        if value not in self.modes:
+            raise ModeNotFoundError(
+                f"{value} is not a defined mode for the receiver {self.name}. "
+                f"Expected one of {self.modes}"
+            )
         self._mode = value
 
+    def _get_active_mode(self) -> str:
+        """Get the current mode, raising an error if none is set.
+
+        :raises ValueError: If no mode is currently set
+        :return: The current mode
+        """
+        if self._mode is None:
+            raise ValueError(
+                f"This operation requires an active mode for receiver `{self.name.value}`"
+            )
+        return self._mode
 
     @property
-    def capture_method(
-        self
-    ) -> Callable[[str, Parameters], None]:
+    def capture_method(self) -> Callable[[str, Parameters], None]:
         """Start capturing data under the active operating mode."""
-        return self.capture_methods[self.mode]
-
+        return self.capture_methods[self._get_active_mode()]
 
     @property
-    def pvalidator(
-        self
-    ) -> Callable[[Parameters], None]:
+    def pvalidator(self) -> Callable[[Parameters], None]:
         """The parameter validation function for the active operating mode."""
-        return self.pvalidators[self.mode]
-
+        return self.pvalidators[self._get_active_mode()]
 
     @property
-    def capture_template(
-        self
-    ) -> CaptureTemplate:
+    def capture_template(self) -> CaptureTemplate:
         """The `CaptureTemplate` for the active operating mode."""
-        return self._capture_templates[self.mode]
-
+        return self._capture_templates[self._get_active_mode()]
 
     def add_capture_method(
-        self,
-        mode: str,
-        capture_method: Callable[[str, Parameters], None]
+        self, mode: str, capture_method: Callable[[str, Parameters], None]
     ) -> None:
         """
         Add a capture method for a specific operating mode.
@@ -194,11 +151,8 @@ class BaseReceiver(ABC):
         """
         self._capture_methods[mode] = capture_method
 
-
     def add_pvalidator(
-        self,
-        mode: str,
-        pvalidator: Callable[[Parameters], None]
+        self, mode: str, pvalidator: Callable[[Parameters], None]
     ) -> None:
         """
         Add a parameter validation function for a specific operating mode.
@@ -208,11 +162,8 @@ class BaseReceiver(ABC):
         """
         self._pvalidators[mode] = pvalidator
 
-
     def add_capture_template(
-        self,
-        mode: str,
-        capture_template: CaptureTemplate
+        self, mode: str, capture_template: CaptureTemplate
     ) -> None:
         """
         Add a `CaptureTemplate` for a specific operating mode.
@@ -222,12 +173,7 @@ class BaseReceiver(ABC):
         """
         self._capture_templates[mode] = capture_template
 
-
-    def add_spec(
-        self,
-        name: SpecName,
-        value: Any 
-    ) -> None:
+    def add_spec(self, name: SpecName, value: Any) -> None:
         """
         Add a hardware specification.
 
@@ -236,11 +182,7 @@ class BaseReceiver(ABC):
         """
         self.specs[name] = value
 
-    
-    def get_spec(
-        self, 
-        spec_name: SpecName
-    ) -> Any:
+    def get_spec(self, spec_name: SpecName) -> Any:
         """
         Retrieve a hardware specification.
 
@@ -249,60 +191,52 @@ class BaseReceiver(ABC):
         :return: The specification's value.
         """
         if spec_name not in self.specs:
-            raise KeyError(f"Spec not found with name '{spec_name}' "
-                           f"for the receiver '{self.name}'")
+            raise KeyError(
+                f"Spec not found with name '{spec_name}' "
+                f"for the receiver '{self.name}'"
+            )
         return self.specs[spec_name]
 
-
-    def start_capture(
-        self, 
-        tag: str
-    ) -> None:
+    def start_capture(self, tag: str) -> None:
         """Start capturing data in the active operating mode.
 
         :param tag: The tag of the capture config to load.
+        :raises ValueError: If no mode is currently set
         """
-        self.capture_method( tag, self.load_parameters(tag) )
-
+        active_mode = self._get_active_mode()
+        self.capture_methods[active_mode](tag, self.load_parameters(tag))
 
     def save_parameters(
-        self,
-        tag: str,
-        parameters: Parameters,
-        force: bool = False
+        self, tag: str, parameters: Parameters, force: bool = False
     ) -> None:
-        """Create a capture config according to the active operating mode and save the 
+        """Create a capture config according to the active operating mode and save the
         input parameters.
 
-        The input parameters are validated before being written to file.
-        
         :param tag: The tag identifying the capture config.
         :param parameters: The parameters to save in the capture config.
-        :param force: If True, overwrites the existing file if it already exists. Defaults to False.
+        :param force: If True, overwrites existing file if it exists.
+        :raises ValueError: If no mode is currently set
         """
-        parameters = self.capture_template.apply_template(parameters)
-        self.pvalidator(parameters)
+        active_mode = self._get_active_mode()
+        parameters = self.capture_templates[active_mode].apply_template(parameters)
+        self.pvalidators[active_mode](parameters)
 
         capture_config = CaptureConfig(tag)
-        capture_config.save_parameters(self.name.value,
-                                       self.mode,
-                                       parameters,
-                                       force)
-
-    def load_parameters(
-        self,
-        tag: str
-    ) -> Parameters:
-        """Load a capture config, and return the parameters it stores.
+        capture_config.save_parameters(self.name.value, active_mode, parameters, force)
 
-        The parameters are validated before being returned.
+    def load_parameters(self, tag: str) -> Parameters:
+        """Load a capture config, and return the parameters it stores.
 
         :param tag: The tag identifying the capture config.
+        :raises ValueError: If no mode is currently set
         :return: The validated parameters stored in the capture config.
         """
+        active_mode = self._get_active_mode()
         capture_config = CaptureConfig(tag)
 
-        parameters = self.capture_template.apply_template(capture_config.parameters)
-        self.pvalidator(parameters)
-        
+        parameters = self.capture_templates[active_mode].apply_template(
+            capture_config.parameters
+        )
+        self.pvalidators[active_mode](parameters)
+
         return parameters

spectre_core/receivers/_factory.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# SPDX-FileCopyrightText: © 2024-2025 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -16,47 +16,36 @@ from .plugins._b200mini import B200mini
 
 @overload
 def get_receiver(
-    receiver_name: Literal[ReceiverName.RSP1A],
-    mode: Optional[str] = None
-) -> RSP1A:
-    ...
-    
-    
+    receiver_name: Literal[ReceiverName.RSP1A], mode: Optional[str] = None
+) -> RSP1A: ...
+
+
 @overload
 def get_receiver(
-    receiver_name: Literal[ReceiverName.RSPDUO],
-    mode: Optional[str] = None
-) -> RSPduo:
-    ...
-    
-    
+    receiver_name: Literal[ReceiverName.RSPDUO], mode: Optional[str] = None
+) -> RSPduo: ...
+
+
 @overload
 def get_receiver(
-    receiver_name: Literal[ReceiverName.TEST],
-    mode: Optional[str] = None
-) -> Test:
-    ...
+    receiver_name: Literal[ReceiverName.TEST], mode: Optional[str] = None
+) -> Test: ...
 
 
 @overload
 def get_receiver(
-    receiver_name: Literal[ReceiverName.B200MINI],
-    mode: Optional[str] = None
-) -> B200mini:
-    ...
+    receiver_name: Literal[ReceiverName.B200MINI], mode: Optional[str] = None
+) -> B200mini: ...
 
 
 @overload
 def get_receiver(
-    receiver_name: ReceiverName,
-    mode: Optional[str] = None
-) -> BaseReceiver:
-    ...
+    receiver_name: ReceiverName, mode: Optional[str] = None
+) -> BaseReceiver: ...
 
 
 def get_receiver(
-    receiver_name: ReceiverName, 
-    mode: Optional[str] = None
+    receiver_name: ReceiverName, mode: Optional[str] = None
 ) -> BaseReceiver:
     """Get a registered receiver.
 
@@ -68,7 +57,8 @@ def get_receiver(
     receiver_cls = receivers.get(receiver_name)
     if receiver_cls is None:
         valid_receivers = list(receivers.keys())
-        raise ReceiverNotFoundError(f"No class found for the receiver: {receiver_name}. "
-                                    f"Please specify one of the following receivers {valid_receivers}")
-    return receiver_cls(receiver_name, 
-                        mode = mode)
+        raise ReceiverNotFoundError(
+            f"No class found for the receiver: {receiver_name}. "
+            f"Please specify one of the following receivers {valid_receivers}"
+        )
+    return receiver_cls(receiver_name, mode=mode)

spectre_core/receivers/_register.py

@@ -1,4 +1,4 @@
-# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# SPDX-FileCopyrightText: © 2024-2025 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
@@ -10,7 +10,9 @@ from ._base import BaseReceiver
 # map populated at runtime via the `register_receiver` decorator.
 receivers: dict[ReceiverName, Type[BaseReceiver]] = {}
 
-T = TypeVar('T', bound=BaseReceiver)
+T = TypeVar("T", bound=BaseReceiver)
+
+
 def register_receiver(
     receiver_name: ReceiverName,
 ) -> Callable[[Type[T]], Type[T]]:
@@ -20,24 +22,19 @@ def register_receiver(
     :raises ValueError: If the provided `receiver_name` is already registered.
     :return: A decorator that registers the `BaseReceiver` subclass under the given `receiver_name`.
     """
-    def decorator(
-        cls: Type[T]
-    ) -> Type[T]:
+
+    def decorator(cls: Type[T]) -> Type[T]:
         if receiver_name in receivers:
             raise ValueError(f"The receiver '{receiver_name}' is already registered!")
         receivers[receiver_name] = cls
         return cls
+
     return decorator
 
 
-def get_registered_receivers(
-) -> list[str]:
+def get_registered_receivers() -> list[str]:
     """List all registered receivers.
 
     :return: The string values of all registered `ReceiverName` enum keys.
     """
     return [k.value for k in receivers.keys()]
-
-
-
-

spectre_core/receivers/_spec_names.py

@@ -1,12 +1,13 @@
-# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# SPDX-FileCopyrightText: © 2024-2025 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
 from enum import Enum
 
+
 class SpecName(Enum):
     """A hardware specification name.
-    
+
     :ivar FREQUENCY_LOWER_BOUND: The lower bound for the center frequency, in Hz.
     :ivar FREQUENCY_UPPER_BOUND: The upper bound for the center frequency, in Hz.
     :ivar SAMPLE_RATE_LOWER_BOUND: The lower bound for the sampling rate, in Hz.
@@ -16,26 +17,27 @@ class SpecName(Enum):
     :ivar BANDWIDTH_OPTIONS: The permitted bandwidths for the receiver, in Hz.
     :ivar IF_GAIN_UPPER_BOUND: The upper bound for the intermediate frequency gain, in dB.
     Negative values indicate attenuation.
-    :ivar RF_GAIN_UPPER_BOUND: The upper bound for the radio frequency gain, in dB. 
+    :ivar RF_GAIN_UPPER_BOUND: The upper bound for the radio frequency gain, in dB.
     Negative values indicate attenuation.
     :ivar GAIN_UPPER_BOUND: The upper bound for the gain, in dB.
     :ivar WIRE_FORMATS: Supported data types transferred over the bus/network.
     :ivar MASTER_CLOCK_RATE_LOWER_BOUND:  The lower bound for the SDR reference clock rate, in Hz.
     :ivar MASTER_CLOCK_RATE_UPPER_BOUND:  The upper bound for the SDR reference clock rate, in Hz.
     :ivar API_RETUNING_LATENCY: An empirical estimate of the delay between issuing a command
-    for a receiver to retune its center frequency and the actual physical update of the center frequency. 
+    for a receiver to retune its center frequency and the actual physical update of the center frequency.
     """
-    FREQUENCY_LOWER_BOUND         = "frequency_lower_bound"
-    FREQUENCY_UPPER_BOUND         = "frequency_upper_bound"
-    SAMPLE_RATE_LOWER_BOUND       = "sample_rate_lower_bound"
-    SAMPLE_RATE_UPPER_BOUND       = "sample_rate_upper_bound"
-    BANDWIDTH_LOWER_BOUND         = "bandwidth_lower_bound"
-    BANDWIDTH_UPPER_BOUND         = "bandwidth_upper_bound"
-    BANDWIDTH_OPTIONS             = "bandwidth_options"
-    IF_GAIN_UPPER_BOUND           = "if_gain_upper_bound"
-    RF_GAIN_UPPER_BOUND           = "rf_gain_upper_bound"
-    GAIN_UPPER_BOUND              = "gain_upper_bound"
-    WIRE_FORMATS                  = "wire_formats"
+
+    FREQUENCY_LOWER_BOUND = "frequency_lower_bound"
+    FREQUENCY_UPPER_BOUND = "frequency_upper_bound"
+    SAMPLE_RATE_LOWER_BOUND = "sample_rate_lower_bound"
+    SAMPLE_RATE_UPPER_BOUND = "sample_rate_upper_bound"
+    BANDWIDTH_LOWER_BOUND = "bandwidth_lower_bound"
+    BANDWIDTH_UPPER_BOUND = "bandwidth_upper_bound"
+    BANDWIDTH_OPTIONS = "bandwidth_options"
+    IF_GAIN_UPPER_BOUND = "if_gain_upper_bound"
+    RF_GAIN_UPPER_BOUND = "rf_gain_upper_bound"
+    GAIN_UPPER_BOUND = "gain_upper_bound"
+    WIRE_FORMATS = "wire_formats"
     MASTER_CLOCK_RATE_LOWER_BOUND = "master_clock_rate_lower_bound"
     MASTER_CLOCK_RATE_UPPER_BOUND = "master_clock_rate_upper_bound"
-    API_RETUNING_LATENCY          = "api_retuning_latency"
+    API_RETUNING_LATENCY = "api_retuning_latency"