spectre-core 0.0.25__tar.gz → 0.0.26__tar.gz

{spectre_core-0.0.25 → spectre_core-0.0.26}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spectre-core
-Version: 0.0.25
+Version: 0.0.26
 Summary: The core Python package used by the spectre program. 
 Maintainer-email: Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
 License:                     GNU GENERAL PUBLIC LICENSE

{spectre_core-0.0.25 → spectre_core-0.0.26}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "spectre-core"
-version = "0.0.25"
+version = "0.0.26"
 maintainers = [
   { name="Jimmy Fitzpatrick", email="jcfitzpatrick12@gmail.com" },
 ]

{spectre_core-0.0.25 → spectre_core-0.0.26}/src/spectre_core/__init__.py

@@ -2,4 +2,4 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-__version__ = "0.0.25"
+__version__ = "0.0.26"

{spectre_core-0.0.25 → spectre_core-0.0.26}/src/spectre_core/capture_configs/_capture_config.py

@@ -49,6 +49,8 @@ class CaptureConfig(JsonHandler):
 
         Some substrings are reserved for third-party spectrogram data.
         """
+        if "_" in tag:
+            raise ValueError("An underscore is not allowed in a capture config tag.")
         if "callisto" in tag:
             raise ValueError(
                 f"The substring `callisto` is reserved, and is not allowed in a capture config tag."

{spectre_core-0.0.25 → spectre_core-0.0.26}/src/spectre_core/plotting/_panel_stack.py

@@ -10,6 +10,7 @@ from matplotlib.figure import Figure
 from matplotlib.axes import Axes
 from matplotlib import use
 from datetime import datetime
+import gc
 
 from spectre_core.spectrograms import TimeType
 from spectre_core.config import TimeFormat, get_batches_dir_path
@@ -281,12 +282,19 @@ class PanelStack:
 
         self._overlay_superimposed_panels()
 
+    def _close(self) -> None:
+        """Prevent memory leaks once a figure has been created, and successfully visualised."""
+        self._get_fig().clear()
+        plt.close(self._fig)
+        # Garbage collection seems to be required to prevent the memory leak.
+        # See https://github.com/jcfitzpatrick12/spectre/issues/128
+        gc.collect()
+
     def show(self) -> None:
         """Display the panel stack figure."""
         self._make_figure()
         self._get_fig().show()
-        self._get_fig().clear()
-        plt.close(self._fig)
+        self._close()
 
     def save(
         self,
@@ -312,6 +320,5 @@ class PanelStack:
         # If the parent directory does not exist, create it.
         os.makedirs(os.path.dirname(batch_file_path), exist_ok=True)
         self._get_fig().savefig(batch_file_path)
-        self._get_fig().clear()
-        plt.close(self._fig)
+        self._close()
         return batch_file_path

{spectre_core-0.0.25 → spectre_core-0.0.26}/src/spectre_core/receivers/__init__.py

@@ -2,27 +2,30 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-"""A vendor-neutral interface for collecting data from SDRs."""
+"""A vendor-neutral interface for capturing data from SDRs."""
 
 from .plugins._receiver_names import ReceiverName
-from .plugins._test import Test
+from .plugins._signal_generator import SignalGenerator
 from .plugins._rsp1a import RSP1A
 from .plugins._rspduo import RSPduo
 from .plugins._b200mini import B200mini
 
-from ._base import BaseReceiver
+from ._receiver import Receiver, ReceiverComponents
+from ._specs import SpecName, Specs
 from ._factory import get_receiver
 from ._register import get_registered_receivers
-from ._spec_names import SpecName
 
 __all__ = [
-    "Test",
+    "Receiver",
+    "ReceiverComponents",
+    "Specs",
+    "SpecName",
+    "ReceiverName",
+    "SignalGenerator",
     "RSP1A",
     "RSPduo",
     "B200mini",
-    "BaseReceiver",
+    "Custom",
     "get_receiver",
     "get_registered_receivers",
-    "SpecName",
-    "ReceiverName",
 ]

{spectre_core-0.0.25 → spectre_core-0.0.26}/src/spectre_core/receivers/_factory.py

@@ -2,16 +2,23 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
-from typing import Optional, overload, Literal, TypeVar
+from typing import Optional, overload, Literal
 
 from spectre_core.exceptions import ReceiverNotFoundError
 from ._register import receivers
-from ._base import BaseReceiver
+from ._receiver import Receiver
 from .plugins._receiver_names import ReceiverName
+from .plugins._signal_generator import SignalGenerator
 from .plugins._rsp1a import RSP1A
 from .plugins._rspduo import RSPduo
-from .plugins._test import Test
 from .plugins._b200mini import B200mini
+from .plugins._custom import CustomReceiver
+
+
+@overload
+def get_receiver(
+    receiver_name: Literal[ReceiverName.SIGNAL_GENERATOR], mode: Optional[str] = None
+) -> SignalGenerator: ...
 
 
 @overload
@@ -28,25 +35,23 @@ def get_receiver(
 
 @overload
 def get_receiver(
-    receiver_name: Literal[ReceiverName.TEST], mode: Optional[str] = None
-) -> Test: ...
+    receiver_name: Literal[ReceiverName.B200MINI], mode: Optional[str] = None
+) -> B200mini: ...
 
 
 @overload
 def get_receiver(
-    receiver_name: Literal[ReceiverName.B200MINI], mode: Optional[str] = None
-) -> B200mini: ...
+    receiver_name: Literal[ReceiverName.CUSTOM], mode: Optional[str] = None
+) -> CustomReceiver: ...
 
 
 @overload
 def get_receiver(
     receiver_name: ReceiverName, mode: Optional[str] = None
-) -> BaseReceiver: ...
+) -> Receiver: ...
 
 
-def get_receiver(
-    receiver_name: ReceiverName, mode: Optional[str] = None
-) -> BaseReceiver:
+def get_receiver(receiver_name: ReceiverName, mode: Optional[str] = None) -> Receiver:
     """Get a registered receiver.
 
     :param receiver_name: The name of the receiver.

spectre_core-0.0.26/src/spectre_core/receivers/_receiver.py

@@ -0,0 +1,246 @@
+# SPDX-FileCopyrightText: © 2024-2025 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Callable, Optional, TypeVar, Generic, Any
+
+from spectre_core.exceptions import ModeNotFoundError
+from spectre_core.capture_configs import CaptureTemplate, Parameters, CaptureConfig
+from .plugins._receiver_names import ReceiverName
+from ._specs import Specs, SpecName
+
+T = TypeVar("T")
+
+
+class ReceiverComponents(Generic[T]):
+    """Base class for managing receiver components per operating mode."""
+
+    def __init__(self) -> None:
+        """Initialise an instance of `ReceiverComponents`."""
+        self._components: dict[str, T] = {}
+
+    @property
+    def modes(self) -> list[str]:
+        """Get all the added operating modes."""
+        return list(self._components.keys())
+
+    def add(self, mode: str, component: T) -> None:
+        """Add a component for a particular operating mode.
+
+        :param mode: The operating mode for the receiver.
+        :param component: The component associated with this mode.
+        """
+        self._components[mode] = component
+
+    def get(self, mode: str) -> T:
+        """Retrieve the component for a particular operating mode.
+
+        :param mode: The operating mode for the receiver.
+        :return: The component associated with this mode.
+        :raises ModeNotFoundError: If the mode is not found.
+        """
+        if mode not in self._components:
+            raise ModeNotFoundError(
+                f"Mode `{mode}` not found. Expected one of {self._components}"
+            )
+        return self._components[mode]
+
+
+class CaptureMethods(ReceiverComponents[Callable[[str, Parameters], None]]):
+    """Per operating mode, define how the receiver captures data."""
+
+
+class CaptureTemplates(ReceiverComponents[CaptureTemplate]):
+    """Per operating mode, define what parameters are required in a capture config, and the values each parameter can take."""
+
+
+class PValidators(ReceiverComponents[Callable[[Parameters], None]]):
+    """Validate capture config parameters en groupe, per operating mode."""
+
+
+def default_pvalidator(parameters: Parameters) -> None:
+    """A noop parameter validator. Doesn't check anything at all."""
+
+
+class Receiver:
+    """An abstraction layer for software-defined radio receivers."""
+
+    def __init__(
+        self,
+        name: ReceiverName,
+        mode: Optional[str] = None,
+        specs: Optional[Specs] = None,
+        capture_methods: Optional[CaptureMethods] = None,
+        capture_templates: Optional[CaptureTemplates] = None,
+        pvalidators: Optional[PValidators] = None,
+    ) -> None:
+        """Initialise a receiver instance.
+
+        :param name: The name of the receiver.
+        :param capture_methods: Defines how the receiver captures data per mode.
+        :param capture_templates: Defines required parameters per mode.
+        :param pvalidators: Defines parameter validation functions per mode.
+        :param specs: Hardware specifications for the receiver.
+        :param mode: The initial active operating mode. Defaults to None.
+        """
+        self._name = name
+        self._mode = mode
+        self._specs = specs or Specs()
+        self._capture_methods = capture_methods or CaptureMethods()
+        self._capture_templates = capture_templates or CaptureTemplates()
+        self._pvalidators = pvalidators or PValidators()
+
+    @property
+    def name(self) -> ReceiverName:
+        """Retrieve the receiver's name."""
+        return self._name
+
+    @property
+    def mode(self) -> Optional[str]:
+        """Retrieve the operating mode."""
+        return self._mode
+
+    @mode.setter
+    def mode(self, value: str) -> None:
+        """Set the operating mode.
+
+        :param value: The new operating mode of the receiver. Use `None` to unset the mode.
+        """
+        if value not in self.modes:
+            raise ModeNotFoundError(
+                f"Mode `{value}` not found. Expected one of {self.modes}"
+            )
+        self._mode = value
+
+    @property
+    def modes(self) -> list[str]:
+        """The operating modes for the receiver.
+
+        :raises ValueError: If the modes are inconsistent.
+        """
+        if (
+            not self._capture_methods.modes
+            == self._pvalidators.modes
+            == self._capture_templates.modes
+        ):
+            raise ValueError(f"Modes are inconsistent for the receiver {self.name}.")
+        return self._capture_methods.modes
+
+    @property
+    def active_mode(self) -> str:
+        """Retrieve the active operating mode, raising an error if not set.
+
+        :raises ValueError: If no mode is currently set.
+        :return: The active operating mode.
+        """
+        if self._mode is None:
+            raise ValueError(
+                f"An active mode is not set for the receiver `{self.name.value}`. Currently, the mode is {self._mode}"
+            )
+        return self._mode
+
+    @property
+    def capture_method(self) -> Callable[[str, Parameters], None]:
+        """Retrieve the capture method for the active operating mode."""
+        return self._capture_methods.get(self.active_mode)
+
+    @property
+    def capture_template(self) -> CaptureTemplate:
+        """Retrieve the capture template for the active operating mode."""
+        return self._capture_templates.get(self.active_mode)
+
+    @property
+    def pvalidator(self) -> Callable[[Parameters], None]:
+        """Retrieve the parameter validator for the active operating mode."""
+        return self._pvalidators.get(self.active_mode)
+
+    @property
+    def specs(self) -> dict[SpecName, Any]:
+        """Retrieve all hardware specifications.
+
+        :return: A dictionary of all specifications.
+        """
+        return self._specs.all()
+
+    def start_capture(self, tag: str) -> None:
+        """Start capturing data using the active operating mode.
+
+        :param tag: The tag identifying the capture config.
+        :raises ValueError: If no mode is currently set.
+        """
+        self.capture_method(tag, self.load_parameters(tag))
+
+    def save_parameters(
+        self,
+        tag: str,
+        parameters: Parameters,
+        force: bool = False,
+        validate: bool = True,
+    ) -> None:
+        """Save parameters to a capture config.
+
+        :param tag: The tag identifying the capture config.
+        :param parameters: The parameters to save.
+        :param force: If True, overwrite existing configuration if it exists.
+        :param validate: If True, apply the capture template and pvalidator.
+        :raises ValueError: If no mode is currently set.
+        """
+        if validate:
+            parameters = self.capture_template.apply_template(parameters)
+            self.pvalidator(parameters)
+
+        capture_config = CaptureConfig(tag)
+        capture_config.save_parameters(
+            self.name.value, self.active_mode, parameters, force
+        )
+
+    def load_parameters(self, tag: str, validate: bool = True) -> Parameters:
+        """Load parameters from a capture config.
+
+        :param tag: The tag identifying the capture config.
+        :param validate: If True, apply the capture template and pvalidator.
+        :raises ValueError: If no mode is currently set.
+        :return: The validated parameters stored in the configuration.
+        """
+        capture_config = CaptureConfig(tag)
+
+        if validate:
+            parameters = self.capture_template.apply_template(capture_config.parameters)
+            self.pvalidator(parameters)
+            return parameters
+        else:
+            return capture_config.parameters
+
+    def add_mode(
+        self,
+        mode: str,
+        capture_method: Callable[[str, Parameters], None],
+        capture_template: CaptureTemplate,
+        pvalidator: Callable[[Parameters], None] = default_pvalidator,
+    ) -> None:
+        """Add a new mode to the receiver.
+
+        :param mode: The name of the new mode.
+        :param capture_method: Define how data is captured in this mode.
+        :param capture_template: Define what parameters are required in a capture config, and the values each parameter can take.
+        :param pvalidator: The function to validate parameters for this mode, as a group.
+        """
+        self._capture_methods.add(mode, capture_method)
+        self._capture_templates.add(mode, capture_template)
+        self._pvalidators.add(mode, pvalidator)
+
+    def add_spec(self, name: SpecName, value: Any) -> None:
+        """Add a hardware specification.
+
+        :param name: The specification's name.
+        :param value: The specification's value.
+        """
+        self._specs.add(name, value)
+
+    def get_spec(self, name: SpecName) -> Any:
+        """Retrieve a specific hardware specification.
+
+        :param name: The specification's name.
+        :return: The specification's value.
+        """
+        return self._specs.get(name)

{spectre_core-0.0.25 → spectre_core-0.0.26}/src/spectre_core/receivers/_register.py

@@ -5,12 +5,12 @@
 from typing import TypeVar, Callable, Type
 
 from .plugins._receiver_names import ReceiverName
-from ._base import BaseReceiver
+from ._receiver import Receiver
 
 # map populated at runtime via the `register_receiver` decorator.
-receivers: dict[ReceiverName, Type[BaseReceiver]] = {}
+receivers: dict[ReceiverName, Type[Receiver]] = {}
 
-T = TypeVar("T", bound=BaseReceiver)
+T = TypeVar("T", bound=Receiver)
 
 
 def register_receiver(

spectre_core-0.0.25/src/spectre_core/receivers/_spec_names.py → spectre_core-0.0.26/src/spectre_core/receivers/_specs.py

@@ -2,11 +2,12 @@
 # This file is part of SPECTRE
 # SPDX-License-Identifier: GPL-3.0-or-later
 
+from typing import Any
 from enum import Enum
 
 
 class SpecName(Enum):
-    """A hardware specification name.
+    """Hardware specification names for SDR receivers.
 
     :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.
@@ -16,15 +17,14 @@ class SpecName(Enum):
     :ivar BANDWIDTH_UPPER_BOUND: The upper bound for the bandwidth, in Hz.
     :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 IF_GAIN_LOWER_BOUND: The lower bound for the intermediate frequency gain, in dB.
     :ivar RF_GAIN_UPPER_BOUND: The upper bound for the radio frequency gain, in dB.
-    Negative values indicate attenuation.
+    :ivar RF_GAIN_LOWER_BOUND: The lower bound for the radio frequency gain, in dB.
     :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.
+    :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: Estimated delay between issuing a retune command and the actual center frequency update.
     """
 
     FREQUENCY_LOWER_BOUND = "frequency_lower_bound"
@@ -35,9 +35,44 @@ class SpecName(Enum):
     BANDWIDTH_UPPER_BOUND = "bandwidth_upper_bound"
     BANDWIDTH_OPTIONS = "bandwidth_options"
     IF_GAIN_UPPER_BOUND = "if_gain_upper_bound"
+    IF_GAIN_LOWER_BOUND = "if_gain_lower_bound"
     RF_GAIN_UPPER_BOUND = "rf_gain_upper_bound"
+    RF_GAIN_LOWER_BOUND = "rf_gain_lower_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"
+
+
+class Specs:
+    """Define hardware specifications."""
+
+    def __init__(self) -> None:
+        """Initialise an instance of `Specs`."""
+        self._specs: dict[SpecName, Any] = {}
+
+    def add(self, name: SpecName, value: Any) -> None:
+        """Add a hardware specification.
+
+        :param name: The specification's name.
+        :param value: The specification's value.
+        """
+        self._specs[name] = value
+
+    def get(self, name: SpecName) -> Any:
+        """Get a hardware specification.
+
+        :param name: The specification's name.
+        :return: The specification's value.
+        :raises KeyError: If the specification is not found.
+        """
+        if name not in self._specs:
+            raise KeyError(
+                f"Specification `{name}` not found. Expected one of {list(self._specs.keys())}"
+            )
+        return self._specs[name]
+
+    def all(self) -> dict[SpecName, Any]:
+        """Retrieve all hardware specifications."""
+        return self._specs