spectre-core 0.0.8__py3-none-any.whl → 0.0.10__py3-none-any.whl

spectre_core/capture_configs/_ptemplates.py

@@ -0,0 +1,450 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from typing import Optional, TypeVar, Any
+from copy import deepcopy
+from textwrap import dedent
+from dataclasses import dataclass
+
+from ._pconstraints import PConstraint, PConstraints
+from ._parameters import Parameter
+
+T = TypeVar('T')
+
+class PTemplate:
+    """A parameter template. 
+    
+    Constrain the value and type that a parameter can take.
+    """
+    def __init__(self,
+                 name: str,
+                 ptype: T,
+                 default: Optional[T] = None,
+                 nullable: bool = False,
+                 enforce_default: Optional[bool] = False,
+                 help: Optional[str] = None,
+                 pconstraints: Optional[list[PConstraint]] = None):
+        if not callable(ptype):
+            raise TypeError("ptype must be callable.")
+
+        self._name = name
+        self._ptype = ptype
+        self._default = default
+        self._nullable = nullable
+        self._enforce_default = enforce_default
+        self._help = dedent(help).strip().replace("\n", " ") if help else "No help has been provided."
+        self._pconstraints: list[PConstraint] = pconstraints or []
+
+
+    @property
+    def name(self) -> str:
+        """The name of the parameter."""
+        return self._name
+    
+
+    @property
+    def ptype(self) -> T:
+        """The parameter type."""
+        return self._ptype
+    
+
+    @property
+    def default(self) -> Optional[T]:
+        """The value of the parameter, if the value is unspecified."""
+        return self._default
+    
+
+    @default.setter
+    def default(self, value: T) -> None:
+        """Update the default of a ptemplate"""
+        self._default = value
+
+
+    @property
+    def nullable(self) -> bool:
+        """Whether the value of the parameter is allowed to be of None type."""
+        return self._nullable
+    
+
+    @property
+    def enforce_default(self) -> bool:
+        """Whether the provided default value is enforced."""
+        return self._enforce_default
+    
+
+    @enforce_default.setter
+    def enforce_default(self, value: bool) -> None:
+        """Set whether the provided default value is enforced."""
+        self._enforce_default = value
+    
+
+    @property
+    def help(self) -> str:
+        """A description of what the parameter is, and the value it stores."""
+        return self._help
+    
+    
+    def add_pconstraint(self,
+                        pconstraint: PConstraint) -> None:
+        self._pconstraints.append(pconstraint)
+
+
+    def _cast(self, 
+              value: Any) -> T:
+        """Cast the input value to the ptype of this template"""
+        try:
+            return self._ptype(value)
+        except (TypeError, ValueError) as e:
+            raise ValueError(f"Could not cast '{value}' to '{self._ptype.__name__}': {e}")
+
+
+    def _constrain(self, 
+                   value: T) -> T:
+        """Constrain the input value according to constraints of the template."""
+
+        if self._enforce_default and value != self._default:
+            raise ValueError(f"The default value of '{self._default}' "
+                             f"is required for the parameter '{self._name}'.")
+
+        # apply existing pconstraints
+        for constraint in self._pconstraints:
+            try:
+                constraint.constrain(value)
+            except ValueError as e:
+                raise ValueError(f"PConstraint '{constraint.__class__.__name__}' failed for the parameter '{self._name}': {e}")
+            except Exception as e:
+                raise RuntimeError(f"An unexpected error occurred while applying the pconstraint '{constraint.__class__.__name__}' to "
+                                    f"'{self.name}': {e}")
+        return value
+
+
+    def apply_template(self, 
+                       value: Optional[Any]) -> T:
+        """Cast the value and constrain it according to this ptemplate."""
+        if value is None:
+            if self._default is not None:
+                value = self._default
+            elif not self._nullable:
+                raise ValueError(f"The parameter '{self._name}' is not nullable, "
+                                 f"but no value or default has been provided. "
+                                 f"Either provide a value, or provide a default.")
+            else:
+                return None
+        
+        value = self._cast(value)
+        value = self._constrain(value)
+        return value
+
+
+    def make_parameter(self, 
+                       value: Optional[Any] = None) -> Parameter:
+        value = self.apply_template(value)
+        return Parameter(self._name, value)
+
+
+    def to_dict(self) -> dict:
+        """Convert the template to a dictionary representation."""
+        return {
+            "name": self._name,
+            "type": str(self._ptype),
+            "default": self._default,
+            "enforce_default": self._enforce_default,
+            "help": self._help,
+            "constraints": [f"{constraint}" for constraint in self._pconstraints]
+        }
+    
+
+@dataclass(frozen=True)
+class PNames:
+    """A centralised store of default parameter template names"""
+    CENTER_FREQUENCY        : str = "center_frequency"
+    MIN_FREQUENCY           : str = "min_frequency"
+    MAX_FREQUENCY           : str = "max_frequency"
+    FREQUENCY_STEP          : str = "frequency_step"
+    FREQUENCY               : str = "frequency"
+    BANDWIDTH               : str = "bandwidth"
+    SAMPLE_RATE             : str = "sample_rate"
+    IF_GAIN                 : str = "if_gain"
+    RF_GAIN                 : str = "rf_gain"
+    AMPLITUDE               : str = "amplitude"
+    FREQUENCY               : str = "frequency"
+    TIME_RESOLUTION         : str = "time_resolution"
+    FREQUENCY_RESOLUTION    : str = "frequency_resolution"
+    TIME_RANGE              : str = "time_range"
+    BATCH_SIZE              : str = "batch_size"
+    WINDOW_TYPE             : str = "window_type"
+    WINDOW_HOP              : str = "window_hop"
+    WINDOW_SIZE             : str = "window_size"
+    EVENT_HANDLER_KEY       : str = "event_handler_key"
+    WATCH_EXTENSION         : str = "watch_extension"
+    CHUNK_KEY               : str = "chunk_key"
+    SAMPLES_PER_STEP        : str = "samples_per_step"
+    MIN_SAMPLES_PER_STEP    : str = "min_samples_per_step"
+    MAX_SAMPLES_PER_STEP    : str = "max_samples_per_step"
+    STEP_INCREMENT          : str = "step_increment"
+    ORIGIN                  : str = "origin"
+    TELESCOPE               : str = "telescope"
+    INSTRUMENT              : str = "instrument"
+    OBJECT                  : str = "object"
+    OBS_LAT                 : str = "obs_lat"
+    OBS_LON                 : str = "obs_lon"
+    OBS_ALT                 : str = "obs_alt"
+
+#
+# All stored base ptemplates
+#
+_base_ptemplates = {
+    PNames.CENTER_FREQUENCY:       PTemplate(PNames.CENTER_FREQUENCY,       
+                                             float, 
+                                             help = """
+                                                    The center frequency of the SDR in Hz.
+                                                    This value determines the midpoint of the frequency range
+                                                    being processed.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.MIN_FREQUENCY:          PTemplate(PNames.MIN_FREQUENCY,          
+                                             float, 
+                                             help = """
+                                                    The minimum center frequency, in Hz, for the frequency sweep.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.MAX_FREQUENCY:          PTemplate(PNames.MAX_FREQUENCY,          
+                                             float, 
+                                             help = """
+                                                    The maximum center frequency, in Hz, for the frequency sweep.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.FREQUENCY_STEP:         PTemplate(PNames.FREQUENCY_STEP,         
+                                             float, 
+                                             help = """
+                                                    The amount, in Hz, by which the center frequency is incremented
+                                                    for each step in the frequency sweep. 
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.BANDWIDTH:              PTemplate(PNames.BANDWIDTH,              
+                                             float, 
+                                             help = """
+                                                    The frequency range in Hz the signal will occupy without
+                                                    significant attenutation.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.SAMPLE_RATE:            PTemplate(PNames.SAMPLE_RATE,            
+                                             int,   
+                                             help = """
+                                                    The number of samples per second in Hz.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.IF_GAIN:                PTemplate(PNames.IF_GAIN,                
+                                             float, 
+                                             help = """
+                                                    The intermediate frequency gain, in dB.
+                                                    Negative value indicates attenuation.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_negative
+                                                 ]),
+    PNames.RF_GAIN:                PTemplate(PNames.RF_GAIN,                
+                                             float, 
+                                             help = """
+                                                    The radio frequency gain, in dB.
+                                                    Negative value indicates attenuation.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_non_positive
+                                                 ]),
+    PNames.EVENT_HANDLER_KEY:      PTemplate(PNames.EVENT_HANDLER_KEY,      
+                                             str,
+                                             help = """
+                                                    Identifies which post-processing functions to invoke
+                                                    on newly created files.
+                                                    """),
+    PNames.CHUNK_KEY:              PTemplate(PNames.CHUNK_KEY,              
+                                             str,
+                                             help = """
+                                                    Identifies the type of data is stored in each chunk.
+                                                    """,
+                                             ),
+    PNames.WINDOW_SIZE:            PTemplate(PNames.WINDOW_SIZE,            
+                                             int,  
+                                             help = """
+                                                    The size of the window, in samples, when performing the
+                                                    Short Time FFT.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive, 
+                                                 PConstraints.power_of_two
+                                                 ]),
+    PNames.WINDOW_HOP:             PTemplate(PNames.WINDOW_HOP,             
+                                             int,   
+                                             help = """
+                                                    How much the window is shifted, in samples, 
+                                                    when performing the Short Time FFT.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.WINDOW_TYPE:            PTemplate(PNames.WINDOW_TYPE,            
+                                             str,
+                                             help = """
+                                                    The type of window applied when performing the Short
+                                                    Time FFT.
+                                                    """,
+                                             ),
+    PNames.WATCH_EXTENSION:        PTemplate(PNames.WATCH_EXTENSION,        
+                                             str,
+                                             help = """
+                                                    Post-processing is triggered by newly created files with this extension.
+                                                    Extensions are specified without the '.' character.
+                                                    """,
+                                             ),
+    PNames.TIME_RESOLUTION:        PTemplate(PNames.TIME_RESOLUTION,        
+                                             float, 
+                                             nullable=True,
+                                             help = """
+                                                    Batched spectrograms are smoothed by averaging up to the time resolution,
+                                                    specified in seconds.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_non_negative
+                                                 ]),
+    PNames.FREQUENCY_RESOLUTION:   PTemplate(PNames.FREQUENCY_RESOLUTION,   
+                                             float, 
+                                             nullable=True,
+                                             help = """
+                                                    Batched spectrograms are smoothed by averaging up to the frequency resolution,
+                                                    specified in Hz.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_non_negative
+                                                 ]),
+    PNames.TIME_RANGE:             PTemplate(PNames.TIME_RANGE,             
+                                             float, 
+                                             nullable=True,
+                                             help = """
+                                                    Batched spectrograms are stitched together until
+                                                    the time range, in seconds, is surpassed.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_non_negative
+                                                 ]),
+    PNames.BATCH_SIZE:             PTemplate(PNames.BATCH_SIZE,             
+                                             int,   
+                                             help = """
+                                                    SDR data is collected in batches of this size, specified
+                                                    in seconds.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.SAMPLES_PER_STEP:       PTemplate(PNames.SAMPLES_PER_STEP,       
+                                             int,   
+                                             help = """
+                                                    The number of samples taken at each center frequency in the sweep.
+                                                    This may vary slightly from what is specified due to the nature of
+                                                    GNU Radio runtime.
+                                                    """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.ORIGIN:                 PTemplate(PNames.ORIGIN,
+                                             str,
+                                             nullable=True,
+                                             help="""
+                                                  Corresponds to the FITS keyword ORIGIN.
+                                                  """),
+    PNames.TELESCOPE:              PTemplate(PNames.TELESCOPE,
+                                             str,
+                                             nullable=True,
+                                             help="""
+                                                  Corresponds to the FITS keyword TELESCOP.
+                                                  """),
+    PNames.INSTRUMENT:             PTemplate(PNames.INSTRUMENT,
+                                             str,
+                                             nullable=True,
+                                             help="""
+                                                  Corresponds to the FITS keyword INSTRUME.
+                                                  """),
+    PNames.OBJECT:                 PTemplate(PNames.OBJECT,
+                                             str,
+                                             nullable=True,
+                                             help="""
+                                                  Corresponds to the FITS keyword OBJECT.
+                                                  """),
+    PNames.OBS_LAT:                PTemplate(PNames.OBS_LAT,
+                                             float,
+                                             nullable=True,
+                                             help="""
+                                                  Corresponds to the FITS keyword OBS_LAT.
+                                                  """),
+    PNames.OBS_LON:                PTemplate(PNames.OBS_LON,
+                                             float,
+                                             nullable=True,
+                                             help="""
+                                                  Corresponds to the FITS keyword OBS_LONG.
+                                                  """),
+    PNames.OBS_ALT:                PTemplate(PNames.OBS_ALT,
+                                             float,
+                                             nullable=True,
+                                             help="""
+                                                  Corresponds to the FITS keyword OBS_ALT.
+                                                  """),
+    PNames.AMPLITUDE:              PTemplate(PNames.AMPLITUDE,
+                                             float,
+                                             help="""
+                                                  The amplitude of the signal.
+                                                  """),
+    PNames.FREQUENCY:              PTemplate(PNames.FREQUENCY,
+                                             float,
+                                             help="""
+                                                  The frequency of the signal, in Hz.
+                                                  """),
+    PNames.MIN_SAMPLES_PER_STEP:   PTemplate(PNames.MIN_SAMPLES_PER_STEP,
+                                             int,
+                                             help="""
+                                                  The number of samples in the shortest step of the staircase.
+                                                  """,
+                                             pconstraints=[
+                                                 PConstraints.enforce_positive
+                                                 ]),
+    PNames.MAX_SAMPLES_PER_STEP:   PTemplate(PNames.MAX_SAMPLES_PER_STEP,
+                                             int,
+                                             help="""
+                                                  The number of samples in the longest step of the staircase.
+                                                  """,
+                                            pconstraints=[
+                                                  PConstraints.enforce_positive
+                                                  ]),
+    PNames.STEP_INCREMENT:         PTemplate(PNames.STEP_INCREMENT,
+                                             int,
+                                             help="""
+                                                  The length by which each step in the staircase is incremented.
+                                                  """,
+                                             pconstraints=[
+                                                  PConstraints.enforce_positive,
+                                              ])
+                                    
+                                           
+}
+
+T = TypeVar('T')
+def get_base_ptemplate(
+    parameter_name: str,
+) -> PTemplate:
+    """Create a fresh deep copy of a pre-defined ptemplate"""
+    if parameter_name not in _base_ptemplates:
+        raise KeyError(f"No ptemplate found for the parameter name '{parameter_name}'. "
+                       f"Expected one of {list(_base_ptemplates.keys())}")
+    return deepcopy( _base_ptemplates[parameter_name] )

spectre_core/capture_configs/_pvalidators.py

@@ -0,0 +1,173 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from logging import getLogger
+_LOGGER = getLogger(__name__)
+
+from dataclasses import dataclass
+from math import floor
+from scipy.signal import get_window
+from numbers import Number
+from warnings import warn
+from typing import Optional
+
+from ._parameters import Parameters
+from ._ptemplates import PNames
+
+
+def _validate_window(
+        parameters: Parameters
+) -> None:
+    window_size = parameters.get_parameter_value(PNames.WINDOW_SIZE)
+    window_type = parameters.get_parameter_value(PNames.WINDOW_TYPE)
+    sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+    batch_size  = parameters.get_parameter_value(PNames.BATCH_SIZE)
+    
+    window_interval = window_size*(1 / sample_rate)
+    if window_interval > batch_size:
+        raise ValueError((f"The windowing interval must be strictly less than the chunk size. "
+                          f"Computed the windowing interval to be {window_interval} [s], "
+                          f"but the chunk size is {batch_size} [s]"))
+    
+    try:
+        _ = get_window(window_type, window_size)
+    except Exception as e:
+        raise Exception((f"An error has occurred while validating the window. "
+                         f"Got {str(e)}"))
+    
+
+def _validate_nyquist_criterion(
+        parameters: Parameters
+) -> None:
+    sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+    bandwidth   = parameters.get_parameter_value(PNames.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,
+                                 samp_rate: int,
+                                 freq_step: float) -> int:
+     return floor((max_freq - min_freq + samp_rate/2) / freq_step)
+
+
+def _validate_num_steps_per_sweep(
+        parameters: Parameters
+) -> None:
+    min_freq    = parameters.get_parameter_value(PNames.MIN_FREQUENCY)
+    max_freq    = parameters.get_parameter_value(PNames.MAX_FREQUENCY)
+    sample_rate = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+    freq_step   = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
+
+    num_steps_per_sweep = _compute_num_steps_per_sweep(min_freq, 
+                                                       max_freq, 
+                                                       sample_rate, 
+                                                       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"))
+    
+
+def _validate_sweep_interval(
+        parameters: Parameters
+) -> None: 
+    min_freq         = parameters.get_parameter_value(PNames.MIN_FREQUENCY)
+    max_freq         = parameters.get_parameter_value(PNames.MAX_FREQUENCY)
+    sample_rate      = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+    freq_step        = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
+    samples_per_step = parameters.get_parameter_value(PNames.SAMPLES_PER_STEP)
+    batch_size       = parameters.get_parameter_value(PNames.BATCH_SIZE)
+
+    num_steps_per_sweep = _compute_num_steps_per_sweep(min_freq, 
+                                                       max_freq, 
+                                                       sample_rate, 
+                                                       freq_step)
+    num_samples_per_sweep = num_steps_per_sweep * samples_per_step
+    sweep_interval = num_samples_per_sweep * 1/sample_rate
+    if sweep_interval > batch_size:
+        raise ValueError((f"Sweep interval must be less than the chunk size. "
+                          f"The computed sweep interval is {sweep_interval} [s], "
+                          f"but the given chunk size is {batch_size} [s]"))
+    
+
+def _validate_num_samples_per_step(
+        parameters: Parameters
+) -> None:
+
+    window_size      = parameters.get_parameter_value(PNames.WINDOW_SIZE)
+    samples_per_step = parameters.get_parameter_value(PNames.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}"))
+    
+
+def _validate_non_overlapping_steps(
+        parameters: Parameters
+) -> None:
+    
+    freq_step = parameters.get_parameter_value(PNames.FREQUENCY_STEP)
+    sample_rate = parameters.get_parameter_value(PNames.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_latency: Number
+) -> None:
+    
+    samples_per_step = parameters.get_parameter_value(PNames.SAMPLES_PER_STEP)
+    sample_rate      = parameters.get_parameter_value(PNames.SAMPLE_RATE)
+
+    step_interval = samples_per_step * 1/ sample_rate # [s]
+    if step_interval < api_latency:
+        warning_message = (f"The computed step interval of {step_interval} [s] is of the order of empirically "
+                           f"derived api latency {api_latency} [s]; you may experience undefined behaviour!")
+        warn(warning_message)
+        _LOGGER.warning(warning_message)
+
+
+def _validate_fixed_center_frequency_parameters(
+    parameters: Parameters
+) -> None:
+    _validate_nyquist_criterion(parameters)
+    _validate_window(parameters)
+
+
+def _validate_swept_center_frequency_parameters(
+    parameters: Parameters,
+    api_retuning_latency: Optional[Number] = None,
+) -> None:
+    _validate_nyquist_criterion(parameters)
+    _validate_window(parameters)
+    _validate_non_overlapping_steps(parameters)
+    _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)
+    
+
+@dataclass(frozen=True)
+class PValidators:
+    window                 = _validate_window
+    nyquist_criterion      = _validate_nyquist_criterion
+    step_interval          = _validate_step_interval
+    non_overlapping_steps  = _validate_non_overlapping_steps
+    num_steps_per_sweep    = _validate_num_steps_per_sweep
+    num_samples_per_step   = _validate_num_samples_per_step
+    sweep_interval         = _validate_sweep_interval
+    step_interval          = _validate_step_interval
+    fixed_center_frequency = _validate_fixed_center_frequency_parameters
+    swept_center_frequency = _validate_swept_center_frequency_parameters