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

spectre_core/capture_configs/_capture_modes.py

@@ -4,19 +4,21 @@
 
 from enum import Enum
 
+
 class CaptureMode(Enum):
     """A default capture mode for `spectre`.
-    
-    Each `CaptureMode` has an associated base capture template, which can be fetched using: 
-    
+
+    Each `CaptureMode` has an associated base capture template, which can be fetched using:
+
     `get_base_capture_template`
-    
+
     All base capture templates must be registered by one of `CaptureMode`. To introduce a new
     base capture template, you need to create a new `CaptureMode` constant.
-    
+
     :ivar FIXED_CENTER_FREQUENCY: Indicates data capture at a fixed center frequency.
     :ivar SWEPT_CENTER_FREQUENCY: Indicates data capture where the center frequency is continually sweeping
     in fixed increments.
     """
+
     FIXED_CENTER_FREQUENCY = "fixed_center_frequency"
-    SWEPT_CENTER_FREQUENCY = "swept_center_frequency"
+    SWEPT_CENTER_FREQUENCY = "swept_center_frequency"

spectre_core/capture_configs/_capture_templates.py

@@ -11,41 +11,29 @@ from ._pconstraints import BasePConstraint
 from ._ptemplates import PTemplate, get_base_ptemplate
 from ._ptemplates import PName
 
+
 class CaptureTemplate:
     """A managed collection of parameter templates. Strictly defines what parameters are required
     in a capture config, and the values each parameter can take.
     """
-    def __init__(
-        self
-    ) -> None:
-        """Initialise a `CaptureTemplate` instance.
-        """
-        self._ptemplates: dict[PName, PTemplate] = {}
 
+    def __init__(self) -> None:
+        """Initialise a `CaptureTemplate` instance."""
+        self._ptemplates: dict[PName, PTemplate] = {}
 
     @property
-    def name_list(
-        self
-    ) -> list[PName]:
+    def name_list(self) -> list[PName]:
         """The names of all required parameters in the capture template."""
         return list(self._ptemplates.keys())
-    
 
-    def add_ptemplate(
-        self,
-        ptemplate: PTemplate
-    ) -> None:
+    def add_ptemplate(self, ptemplate: PTemplate) -> None:
         """Add a parameter template to the capture template.
 
         :param ptemplate: Describes a required parameter for this capture template.
         """
         self._ptemplates[ptemplate.name] = ptemplate
 
-
-    def get_ptemplate(
-        self,
-        parameter_name: PName
-    ) -> PTemplate:
+    def get_ptemplate(self, parameter_name: PName) -> PTemplate:
         """Get the parameter template corresponding to the parameter with the name `parameter_name`.
 
         :param parameter_name: The name of the parameter.
@@ -53,37 +41,27 @@ class CaptureTemplate:
         :raises ValueError: If the parameter name is not found in the template.
         """
         if parameter_name not in self._ptemplates:
-            raise ValueError(f"Parameter with name '{parameter_name}' is not found in the template. "
-                             f"Expected one of {self.name_list}")   
+            raise ValueError(
+                f"Parameter with name '{parameter_name}' is not found in the template. "
+                f"Expected one of {self.name_list}"
+            )
         return self._ptemplates[parameter_name]
-      
 
-    def __apply_parameter_template(
-        self,
-        parameter: Parameter
-    ) -> None:
+    def __apply_parameter_template(self, parameter: Parameter) -> None:
         """Apply the corresponding parameter template to the input parameter.
-        
+
         As a side effect, the value of the input parameter will be type cast
         according to the template.
         """
         ptemplate = self.get_ptemplate(parameter.name)
         parameter.value = ptemplate.apply_template(parameter.value)
 
-
-    def __apply_parameter_templates(
-        self,
-        parameters: Parameters
-    ) -> None:
+    def __apply_parameter_templates(self, parameters: Parameters) -> None:
         """Apply the corresponding parameter template to each of the input parameters."""
         for parameter in parameters:
             self.__apply_parameter_template(parameter)
 
-    
-    def __fill_missing_with_defaults(
-        self,
-        parameters: Parameters
-    ) -> None:
+    def __fill_missing_with_defaults(self, parameters: Parameters) -> None:
         """Add default parameters to `parameters` for any missing entries.
 
         Missing parameters are identified by comparing `parameters` against the
@@ -94,16 +72,11 @@ class CaptureTemplate:
             if ptemplate.name not in parameters.name_list:
                 # no args for `make_parameter` implies the parameter with the default value will be used.
                 parameter = ptemplate.make_parameter()
-                parameters.add_parameter(parameter.name, 
-                                         parameter.value)
-
+                parameters.add_parameter(parameter.name, parameter.value)
 
-    def apply_template(
-        self,
-        parameters: Parameters
-    ) -> Parameters:
+    def apply_template(self, parameters: Parameters) -> Parameters:
         """Apply the capture template to the input parameters. This involves:
-        
+
         - Adding default parameters if they are missing with respect to this template.
         - Type casting the value of each input parameter according to the corresponding parameter template.
         - Validating the value of each input parameter against any corresponding pconstraints.
@@ -115,19 +88,11 @@ class CaptureTemplate:
         self.__apply_parameter_templates(parameters)
         return parameters
 
-
-    def __iter__(
-        self
-    ) -> Iterator[PTemplate]:
+    def __iter__(self) -> Iterator[PTemplate]:
         """Iterate over stored ptemplates."""
-        yield from self._ptemplates.values() 
+        yield from self._ptemplates.values()
 
-
-    def set_default(
-        self, 
-        parameter_name: PName, 
-        default: Any
-    ) -> None:
+    def set_default(self, parameter_name: PName, default: Any) -> None:
         """Set the default of an existing parameter template.
 
         :param parameter_name: The name of the parameter template to be updated.
@@ -135,34 +100,22 @@ class CaptureTemplate:
         """
         self.get_ptemplate(parameter_name).default = default
 
-
-    def set_defaults(
-        self, 
-        *ptuples: tuple[PName, Any]
-    ) -> None:
+    def set_defaults(self, *ptuples: tuple[PName, Any]) -> None:
         """Update the defaults of multiple parameter templates.
 
         :param ptuples: Tuples of the form (`parameter_name`, `new_default`) to update defaults.
         """
-        for (parameter_name, default) in ptuples:
+        for parameter_name, default in ptuples:
             self.set_default(parameter_name, default)
 
-
-    def enforce_default(
-        self,
-        parameter_name: PName
-    ) -> None:
+    def enforce_default(self, parameter_name: PName) -> None:
         """Set the `enforce_default` attribute of an existing parameter template to True.
 
         :param parameter_name: The name of the parameter template to enforce its default value.
         """
         self.get_ptemplate(parameter_name).enforce_default = True
 
-
-    def enforce_defaults(
-        self, 
-        *parameter_names: PName
-    ) -> None:
+    def enforce_defaults(self, *parameter_names: PName) -> None:
         """Set the `enforce_default` attribute of multiple existing parameter templates to True.
 
         :param parameter_names: The names of the parameter templates to enforce their default values.
@@ -170,11 +123,8 @@ class CaptureTemplate:
         for name in parameter_names:
             self.enforce_default(name)
 
-
     def add_pconstraint(
-        self,
-        parameter_name: PName,
-        pconstraints: list[BasePConstraint]
+        self, parameter_name: PName, pconstraints: list[BasePConstraint]
     ) -> None:
         """Add one or more `PConstraint` instances to an existing parameter template.
 
@@ -184,22 +134,16 @@ class CaptureTemplate:
         for pconstraint in pconstraints:
             self.get_ptemplate(parameter_name).add_pconstraint(pconstraint)
 
-
-    def to_dict(
-        self
-    ) -> dict[str, dict[str, str]]:
+    def to_dict(self) -> dict[str, dict[str, str]]:
         """Convert the current instance to a serialisable dictionary.
 
         :return: A dictionary representation of this capture template, where all values
         are formatted strings.
         """
         return {ptemplate.name.value: ptemplate.to_dict() for ptemplate in self}
-    
-    
 
-def make_base_capture_template(
-    *pnames: PName
-) -> CaptureTemplate:
+
+def make_base_capture_template(*pnames: PName) -> CaptureTemplate:
     """Make a capture template composed entirely of base `PTemplate` instances.
 
     :param pnames: The names of parameters to include in the capture template.
@@ -207,12 +151,11 @@ def make_base_capture_template(
     """
     capture_template = CaptureTemplate()
     for pname in pnames:
-        capture_template.add_ptemplate( get_base_ptemplate(pname) )
+        capture_template.add_ptemplate(get_base_ptemplate(pname))
     return capture_template
 
 
-def _make_fixed_frequency_capture_template(
-) -> CaptureTemplate:
+def _make_fixed_frequency_capture_template() -> CaptureTemplate:
     """The absolute minimum required parameters for any fixed frequency capture template."""
     capture_template = make_base_capture_template(
         PName.BATCH_SIZE,
@@ -236,19 +179,17 @@ def _make_fixed_frequency_capture_template(
         PName.WINDOW_TYPE,
     )
     capture_template.set_defaults(
-            (PName.EVENT_HANDLER_KEY,     "fixed_center_frequency"),
-            (PName.BATCH_KEY,             "iq_stream"),
-            (PName.WATCH_EXTENSION,       "bin")
+        (PName.EVENT_HANDLER_KEY, "fixed_center_frequency"),
+        (PName.BATCH_KEY, "iq_stream"),
+        (PName.WATCH_EXTENSION, "bin"),
     )
     capture_template.enforce_defaults(
-        PName.EVENT_HANDLER_KEY,
-        PName.BATCH_KEY,
-        PName.WATCH_EXTENSION
+        PName.EVENT_HANDLER_KEY, PName.BATCH_KEY, PName.WATCH_EXTENSION
     )
     return capture_template
 
-def _make_swept_frequency_capture_template(
-) -> CaptureTemplate:
+
+def _make_swept_frequency_capture_template() -> CaptureTemplate:
     """The absolute minimum required parameters for any swept frequency capture template."""
     capture_template = make_base_capture_template(
         PName.BATCH_SIZE,
@@ -272,29 +213,26 @@ def _make_swept_frequency_capture_template(
         PName.WATCH_EXTENSION,
         PName.WINDOW_HOP,
         PName.WINDOW_SIZE,
-        PName.WINDOW_TYPE)
+        PName.WINDOW_TYPE,
+    )
     capture_template.set_defaults(
-            (PName.EVENT_HANDLER_KEY,     "swept_center_frequency"),
-            (PName.BATCH_KEY,             "iq_stream"),
-            (PName.WATCH_EXTENSION,       "bin")
+        (PName.EVENT_HANDLER_KEY, "swept_center_frequency"),
+        (PName.BATCH_KEY, "iq_stream"),
+        (PName.WATCH_EXTENSION, "bin"),
     )
     capture_template.enforce_defaults(
-        PName.EVENT_HANDLER_KEY,
-        PName.BATCH_KEY,
-        PName.WATCH_EXTENSION
+        PName.EVENT_HANDLER_KEY, PName.BATCH_KEY, PName.WATCH_EXTENSION
     )
     return capture_template
 
 
 _base_capture_templates: dict[CaptureMode, CaptureTemplate] = {
     CaptureMode.FIXED_CENTER_FREQUENCY: _make_fixed_frequency_capture_template(),
-    CaptureMode.SWEPT_CENTER_FREQUENCY: _make_swept_frequency_capture_template()
+    CaptureMode.SWEPT_CENTER_FREQUENCY: _make_swept_frequency_capture_template(),
 }
 
 
-def get_base_capture_template(
-    capture_mode: CaptureMode
-) -> CaptureTemplate:
+def get_base_capture_template(capture_mode: CaptureMode) -> CaptureTemplate:
     """Get a pre-defined capture template, to be configured according to the specific use-case.
 
     :param capture_mode: The mode used to retrieve the capture template.
@@ -302,6 +240,8 @@ def get_base_capture_template(
     :raises KeyError: If no capture template is found for the given mode.
     """
     if capture_mode not in _base_capture_templates:
-        raise KeyError(f"No capture template found for the capture mode '{capture_mode}'. "
-                       f"Expected one of {list(_base_capture_templates.keys())}")
-    return deepcopy( _base_capture_templates[capture_mode] )
+        raise KeyError(
+            f"No capture template found for the capture mode '{capture_mode}'. "
+            f"Expected one of {list(_base_capture_templates.keys())}"
+        )
+    return deepcopy(_base_capture_templates[capture_mode])

spectre_core/capture_configs/_parameters.py

@@ -7,15 +7,13 @@ from typing import Any, Optional, TypeVar, Generic, Iterator, overload, cast
 from ._pnames import PName
 
 # value type
-VT = TypeVar('VT')
+VT = TypeVar("VT")
+
 
 class Parameter(Generic[VT]):
     """A simple container for a named value."""
-    def __init__(
-        self, 
-        name: PName,
-        value: Optional[VT] = None
-    ) -> None:
+
+    def __init__(self, name: PName, value: Optional[VT] = None) -> None:
         """Initialise a `Parameter` instance.
 
         :param name: The name of the parameter.
@@ -24,28 +22,18 @@ class Parameter(Generic[VT]):
         self._name = name
         self._value: Optional[VT] = value
 
-
     @property
-    def name(
-        self
-    ) -> PName:
+    def name(self) -> PName:
         """The parameter name."""
         return self._name
-    
 
     @property
-    def value(
-        self
-    ) -> Optional[VT]:
+    def value(self) -> Optional[VT]:
         """The parameter value."""
         return self._value
-    
-    
+
     @value.setter
-    def value(
-        self, 
-        v: Optional[VT]
-    ) -> None:
+    def value(self, v: Optional[VT]) -> None:
         """Update the parameter value.
 
         :param v: The new value to set for the parameter.
@@ -55,26 +43,17 @@ class Parameter(Generic[VT]):
 
 class Parameters:
     """A managed collection of parameters."""
-    def __init__(
-        self
-    ) -> None:
+
+    def __init__(self) -> None:
         """Initialise a `Parameters` instance."""
         self._parameters: dict[PName, Parameter] = {}
-    
-    
+
     @property
-    def name_list(
-        self
-    ) -> list[PName]:
+    def name_list(self) -> list[PName]:
         """List the names of stored parameters."""
         return list(self._parameters.keys())
 
-
-    def add_parameter(
-        self, 
-        name: PName,
-        value: Optional[VT]
-    ) -> None:
+    def add_parameter(self, name: PName, value: Optional[VT]) -> None:
         """Add a `Parameter` instance to this `Parameters` instance with the input name and value.
 
         :param name: The name of the parameter.
@@ -82,15 +61,13 @@ class Parameters:
         :raises KeyError: If a parameter already exists under the input name.
         """
         if name in self._parameters:
-            raise KeyError(f"Cannot add a parameter with name '{name}', "
-                           f"since a parameter already exists with that name. ")
+            raise KeyError(
+                f"Cannot add a parameter with name '{name}', "
+                f"since a parameter already exists with that name. "
+            )
         self._parameters[name] = Parameter(name, value)
 
-
-    def get_parameter(
-        self, 
-        name: PName
-    ) -> Parameter:
+    def get_parameter(self, name: PName) -> Parameter:
         """Get the stored `Parameter` instance corresponding to the input name.
 
         :param name: The name of the parameter.
@@ -98,43 +75,33 @@ class Parameters:
         :return: A `Parameter` instance with the input name, if it exists.
         """
         if name not in self._parameters:
-            raise KeyError(f"Parameter with name '{name}' does not exist. "
-                           f"Expected one of {self.name_list}")      
+            raise KeyError(
+                f"Parameter with name '{name}' does not exist. "
+                f"Expected one of {self.name_list}"
+            )
         return self._parameters[name]
 
-
-    def get_parameter_value(
-        self,
-        name: PName
-    ) -> Optional[VT]:
+    def get_parameter_value(self, name: PName) -> Optional[VT]:
         """Get the value of the parameter with the corresponding name.
 
         :param name: The name of the parameter.
         :return: The value of the parameter with the input name.
         """
         return self.get_parameter(name).value
-    
 
-    def __iter__(
-        self
-    ) -> Iterator[Parameter]:
+    def __iter__(self) -> Iterator[Parameter]:
         """Iterate over stored parameters."""
-        yield from self._parameters.values() 
+        yield from self._parameters.values()
 
-    
-    def to_dict(
-        self
-    ) -> dict[str, Optional[Any]]:
+    def to_dict(self) -> dict[str, Optional[Any]]:
         """Convert the `Parameters` instance to a serialisable dictionary.
 
         :return: A dictionary representation of the stored parameters.
         """
         return {p.name.value: p.value for p in self}
-    
 
-def _parse_string_parameter(
-    string_parameter: str
-) -> list[str]:
+
+def _parse_string_parameter(string_parameter: str) -> list[str]:
     """Parse string of the form `a=b` into a list of the form `[a, b]`.
 
     :param string_parameter: A string representation of a capture config parameter.
@@ -142,18 +109,16 @@ def _parse_string_parameter(
     :return: The parsed components of the input string parameter, using the `=` character as a separator.
     The return list will always contain two elements.
     """
-    if not string_parameter or '=' not in string_parameter:
+    if not string_parameter or "=" not in string_parameter:
         raise ValueError(f"Invalid format: '{string_parameter}'. Expected 'KEY=VALUE'.")
-    if string_parameter.startswith('=') or string_parameter.endswith('='):
+    if string_parameter.startswith("=") or string_parameter.endswith("="):
         raise ValueError(f"Invalid format: '{string_parameter}'. Expected 'KEY=VALUE'.")
     # remove leading and trailing whitespace.
     string_parameter = string_parameter.strip()
-    return string_parameter.split('=', 1)
-    
-    
-def parse_string_parameters(
-    string_parameters: list[str]
-) -> dict[str, str]:
+    return string_parameter.split("=", 1)
+
+
+def parse_string_parameters(string_parameters: list[str]) -> dict[str, str]:
     """Parses a list of strings of the form `a=b` into a dictionary mapping each `a` to each `b`.
 
     :param string_parameters: A list of strings, where each element is of the form `a=b`.
@@ -164,11 +129,9 @@ def parse_string_parameters(
         k, v = _parse_string_parameter(string_parameter)
         d[k] = v
     return d
-    
 
-def make_parameters(
-    d: dict[str, Any]
-) -> Parameters:
+
+def make_parameters(d: dict[str, Any]) -> Parameters:
     """Create a `Parameters` instance from the given dictionary. Each key is interpreted as a valid `PName`.
 
     :param d: A dictionary where keys represent parameter names and values represent their corresponding values.
@@ -177,4 +140,4 @@ def make_parameters(
     parameters = Parameters()
     for k, v in d.items():
         parameters.add_parameter(PName(k), v)
-    return parameters
+    return parameters