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

spectre_core/capture_configs/_pconstraints.py

@@ -4,37 +4,63 @@
 
 from dataclasses import dataclass
 from abc import ABC, abstractmethod
-from typing import TypeVar, Optional, Any
-from numbers import Number
+from typing import TypeVar, Optional, Any, Generic
 
-T = TypeVar('T')
-
-class PConstraint(ABC):
-    """Abstract base class for parameter constraints."""
+# value type
+VT = TypeVar('VT')
 
+class BasePConstraint(ABC, Generic[VT]):
+    """An abstract base class for an arbitary parameter constraint."""
     @abstractmethod
-    def constrain(self, value: T) -> None:
-        """Apply a constraint to the input parameter."""
-        pass
-
-    def __format__(self, format_spec: str = "") -> str:
+    def constrain(
+        self, 
+        value: VT
+    ) -> None:
+        """Apply a constraint to the input parameter. Implementations must raise a `ValueError` for
+        if the input value fails the constraint.
+
+        :param value: The value to be constrained.
+        """
+        
+        
+    def __format__(
+        self, 
+        format_spec: str = ""
+    ) -> str:
         attrs = ", ".join(f"{key}={value!r}" for key, value in vars(self).items())
         return f"{self.__class__.__name__}({attrs})"
 
-class Bound(PConstraint):
-    """Constrain a parameter value to a specific range."""
 
-    def __init__(self,
-                 lower_bound: Optional[Number] = None,
-                 upper_bound: Optional[Number] = None,
-                 strict_lower: bool = False,
-                 strict_upper: bool = False):
+class Bound(BasePConstraint[float | int]):
+    """Bound a numeric parameter value to a some specified interval."""
+    def __init__(
+        self,
+        lower_bound: Optional[float | int] = None,
+        upper_bound: Optional[float | int] = None,
+        strict_lower: bool = False,
+        strict_upper: bool = False
+    ) -> None:
+        """Create an instance of `Bound`.
+
+        :param lower_bound: The value must be greater than `lower_bound`. Inclusive if `strict_lower` is False. Defaults to None.
+        :param upper_bound: The value must be less than `upper_bound`. Inclusive if `strict_upper` is False. Defaults to None.
+        :param strict_lower: If true, the value must be strictly greater than `lower_bound`. Defaults to False.
+        :param strict_upper: If true, the value must be strictly less than `upper_bound`. Defaults to False.
+        """
         self._lower_bound = lower_bound
         self._upper_bound = upper_bound
         self._strict_lower = strict_lower
         self._strict_upper = strict_upper
 
-    def constrain(self, value: Number) -> None:
+    def constrain(
+        self, 
+        value: float | int
+    ) -> None:
+        """Bound the parameter value to a specified interval.
+
+        :param value: The value to be constrained.
+        :raises ValueError: If the value is outside the specified interval.
+        """
         if self._lower_bound is not None:
             if self._strict_lower and value <= self._lower_bound:
                 raise ValueError(f"Value must be strictly greater than {self._lower_bound}. "
@@ -51,32 +77,57 @@ class Bound(PConstraint):
                 raise ValueError(f"Value must be less than or equal to {self._upper_bound}. "
                                  f"Got {value}.")
 
+# option type
+OT = TypeVar('OT')
+class OneOf(BasePConstraint[OT]):
+    """Constrain a parameter value to be one of a pre-defined list of options."""
+    def __init__(
+        self, 
+        options: Optional[list[OT]] = None
+    ) -> None:
+        """Initialise an instance of `OneOf`.
 
-class OneOf(PConstraint):
-    """Constrain a parameter to one of a set of defined options."""
+        :param options: Input values are required to be one of `options`. If no options are provided,
+        it is assumed to be an empty list. Defaults to None.
+        """
+        self._options = options or []
 
-    def __init__(self, options: list[Any] = None):
-        self._options = options
 
+    def constrain(self, value: OT) -> None:
+        """Constrain the input value to be one of a list of pre-defined options.
 
-    def constrain(self, value: Any) -> None:
+        :param value: The value to be constrained.
+        :raises ValueError: If the input value is not one of the pre-defined options.
+        """
         if value not in self._options:
             raise ValueError(f"Value must be one of {self._options}. Got {value}.")
         
 
-class _PowerOfTwo(PConstraint):
-    """Constrain a parameter value to be a power of two."""
-
-    def constrain(self, value: Number) -> None:
+class PowerOfTwo(BasePConstraint[int]):
+    """Constrain a numeric parameter value to be a power of two."""
+    def constrain(
+        self, 
+        value: int
+    ) -> None:
+        """Constrain the input value to be a power of two.
+
+        :param value: The input value to be constrained.
+        :raises ValueError: If the input value is not exactly some power of two.
+        """
         if value <= 0 or (value & (value - 1)) != 0:
             raise ValueError(f"Value must be a power of two. Got {value}.")
 
 
 @dataclass(frozen=True)
-class PConstraints:
-    """Ready-made pconstraint instances for frequent use-cases."""
-    power_of_two           = _PowerOfTwo()
-    enforce_positive       = Bound(lower_bound=0, strict_lower=True)
-    enforce_negative       = Bound(upper_bound=0, strict_upper=True)
-    enforce_non_negative   = Bound(lower_bound=0, strict_lower=False)
-    enforce_non_positive   = Bound(upper_bound=0, strict_upper=False)
+class EnforceSign:
+    """Enforce the sign of some value.
+    
+    :ivar positive: Enforce the value to be strictly positive.
+    :ivar negative: Enforce the value to be strictly negative.
+    :ivar non_negative: Enforce the value to be zero or positive.
+    :ivar non_positive: Enforce the value to be zero or negative.
+    """
+    positive       = Bound(lower_bound=0, strict_lower=True)
+    negative       = Bound(upper_bound=0, strict_upper=True)
+    non_negative   = Bound(lower_bound=0, strict_lower=False)
+    non_positive   = Bound(upper_bound=0, strict_upper=False)

spectre_core/capture_configs/_pnames.py

@@ -0,0 +1,49 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from enum import Enum
+
+class PName(Enum):
+    """A `spectre` capture config parameter name.
+    
+    Each `PName` has an associated base parameter template which can be fetched
+    using:
+    
+    `get_base_ptemplate`
+    
+    All parameters and parameter templates must take on some name in `PName`.
+    To introduce a new parameter/parameter template, you need to create a new `PName`
+    constant.
+    """
+    CENTER_FREQUENCY     = "center_frequency"
+    MIN_FREQUENCY        = "min_frequency"
+    MAX_FREQUENCY        = "max_frequency"
+    FREQUENCY_STEP       = "frequency_step"
+    FREQUENCY            = "frequency"
+    BANDWIDTH            = "bandwidth"
+    SAMPLE_RATE          = "sample_rate"
+    IF_GAIN              = "if_gain"
+    RF_GAIN              = "rf_gain"
+    AMPLITUDE            = "amplitude"
+    TIME_RESOLUTION      = "time_resolution"
+    FREQUENCY_RESOLUTION = "frequency_resolution"
+    TIME_RANGE           = "time_range"
+    BATCH_SIZE           = "batch_size"
+    WINDOW_TYPE          = "window_type"
+    WINDOW_HOP           = "window_hop"
+    WINDOW_SIZE          = "window_size"
+    EVENT_HANDLER_KEY    = "event_handler_key"
+    WATCH_EXTENSION      = "watch_extension"
+    BATCH_KEY            = "batch_key"
+    SAMPLES_PER_STEP     = "samples_per_step"
+    MIN_SAMPLES_PER_STEP = "min_samples_per_step"
+    MAX_SAMPLES_PER_STEP = "max_samples_per_step"
+    STEP_INCREMENT       = "step_increment"
+    ORIGIN               = "origin"
+    TELESCOPE            = "telescope"
+    INSTRUMENT           = "instrument"
+    OBJECT               = "object"
+    OBS_LAT              = "obs_lat"
+    OBS_LON              = "obs_lon"
+    OBS_ALT              = "obs_alt"