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

spectre_core/__init__.py

@@ -1,3 +0,0 @@
-# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
-# This file is part of SPECTRE
-# SPDX-License-Identifier: GPL-3.0-or-later

spectre_core/_file_io/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Internal file handling.
+"""
+
+from .file_handlers import (
+    BaseFileHandler, JsonHandler, TextHandler,
+)
+
+__all__ = [ 
+    "BaseFileHandler", "JsonHandler", "TextHandler"
+]

spectre_core/_file_io/file_handlers.py

@@ -0,0 +1,128 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+import os
+import json
+from abc import ABC, abstractmethod
+from typing import Any, Optional
+
+
+class BaseFileHandler(ABC):
+    def __init__(self, 
+                 parent_path: str, 
+                 base_file_name: str, 
+                 extension: Optional[str] = None):
+        self._parent_path = parent_path
+        self._base_file_name = base_file_name
+        self._extension = extension
+
+        
+    @abstractmethod
+    def read(self) -> Any:
+        pass
+ 
+
+    @property
+    def parent_path(self) -> str:
+        return self._parent_path
+    
+
+    @property
+    def base_file_name(self) -> str:
+        return self._base_file_name
+    
+
+    @property
+    def extension(self) -> Optional[str]:
+        return self._extension
+    
+
+    @property
+    def file_name(self) -> str:
+        return self._base_file_name if (self._extension is None) else f"{self._base_file_name}.{self._extension}"
+    
+
+    @property
+    def file_path(self) -> str:
+        return os.path.join(self._parent_path, self.file_name)
+    
+    
+    @property
+    def exists(self) -> bool:
+        return os.path.exists(self.file_path) 
+
+
+    def make_parent_path(self) -> None:
+        os.makedirs(self.parent_path, exist_ok=True) 
+    
+
+    def delete(self,
+               ignore_if_missing: bool = False) -> None:
+        if not self.exists and not ignore_if_missing:
+            raise FileNotFoundError(f"{self.file_name} does not exist, and so cannot be deleted")
+        else:
+            os.remove(self.file_path)
+    
+
+    def cat(self) -> None:
+        print(self.read())
+
+
+class JsonHandler(BaseFileHandler):
+    def __init__(self, 
+                 parent_path: str, 
+                 base_file_name: str,
+                 extension: str = "json",
+                 **kwargs):
+        
+        self._dict = None # cache
+        super().__init__(parent_path, 
+                         base_file_name, 
+                         extension,
+                         **kwargs)
+    
+    
+    def read(self) -> dict[str, Any]:
+        with open(self.file_path, 'r') as f:
+            return json.load(f)
+        
+
+    def save(self, 
+             d: dict, 
+             force: bool = False) -> None:
+        self.make_parent_path()
+
+        if self.exists:
+            if force:
+                pass
+            else:
+                raise RuntimeError((f"{self.file_name} already exists, write has been abandoned. "
+                                    f"You can override this functionality with `force`"))
+
+        with open(self.file_path, 'w') as file:
+                json.dump(d, file, indent=4)
+
+
+    @property
+    def dict(self) -> dict[str, Any]:
+        if self._dict is None:
+            self._dict = self.read()
+        return self._dict
+    
+
+class TextHandler(BaseFileHandler):
+    def __init__(self, 
+                 parent_path: str,
+                 base_file_name: str, 
+                 extension: str = "txt",
+                 **kwargs):
+        super().__init__(parent_path,
+                         base_file_name,
+                         extension, 
+                         **kwargs)
+    
+
+    def read(self) -> dict:
+        with open(self.file_path, 'r') as f:
+            return f.read()

spectre_core/capture_configs/__init__.py

@@ -0,0 +1,29 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+"""
+Capture configuration files.
+"""
+
+from ._pvalidators  import PValidators
+from ._capture_config import CaptureConfig
+from ._parameters   import (
+    Parameter, Parameters, parse_string_parameters, make_parameters
+)
+from ._capture_templates import (
+    CaptureTemplate, CaptureModes, get_base_capture_template, make_base_capture_template
+)
+from ._pconstraints import (
+    PConstraint, PConstraints, Bound, OneOf
+)
+from ._ptemplates   import (
+    PTemplate, PNames, get_base_ptemplate, 
+)
+
+__all__ = [
+    "Parameter", "Parameters", "parse_string_parameters", "make_parameters",
+    "PConstraint", "PConstraints", "Bound", "OneOf", "PNames", "PTemplate",
+    "get_base_ptemplate", "PValidators", "CaptureConfig", "CaptureTemplate",
+    "CaptureModes",  "get_base_capture_template", "make_base_capture_template"
+]

spectre_core/capture_configs/_capture_config.py

@@ -0,0 +1,85 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from dataclasses import dataclass
+
+from spectre_core._file_io import JsonHandler
+from spectre_core.config import get_configs_dir_path
+from spectre_core.exceptions import InvalidTagError
+from ._parameters import (
+    Parameter, 
+    Parameters,
+    make_parameters
+)
+
+@dataclass
+class _CaptureConfigKeys:
+    RECEIVER_NAME = "receiver_name"
+    RECEIVER_MODE = "receiver_mode"
+    PARAMETERS    = "parameters"
+
+
+class CaptureConfig(JsonHandler):
+    def __init__(self,
+                 tag: str):
+        self._validate_tag(tag)
+        self._tag = tag
+        super().__init__(get_configs_dir_path(),
+                         f"capture_{tag}")
+        
+    @property
+    def tag(self) -> str:
+        """Unique identifier for the capture config."""
+        return self._tag
+
+
+    def _validate_tag(self, 
+                      tag: str) -> None:
+        if "_" in tag:
+            raise InvalidTagError(f"Tags cannot contain an underscore. Received {tag}")
+        if "callisto" in tag:
+            raise InvalidTagError(f'"callisto" cannot be a substring in a native tag. Received "{tag}"')
+    
+
+    @property
+    def receiver_name(self) -> str:
+        """The name of the receiver which created the capture config."""
+        return self.dict[_CaptureConfigKeys.RECEIVER_NAME]
+    
+
+    @property
+    def receiver_mode(self) -> str:
+        """The mode of the receiver which created the capture config."""
+        return self.dict[_CaptureConfigKeys.RECEIVER_MODE]
+    
+
+    @property
+    def parameters(self) -> Parameters:
+        """The parameters stored inside the capture config."""
+        return make_parameters( self.dict[_CaptureConfigKeys.PARAMETERS] )
+
+
+    def get_parameter(self, 
+                      name: str) -> Parameter:
+        return self.parameters.get_parameter(name)
+    
+
+    def get_parameter_value(self,
+                            name: str) -> Parameter:
+        return self.parameters.get_parameter_value(name)
+
+
+    def save_parameters(self,
+                        receiver_name: str,
+                        receiver_mode: str,
+                        parameters: Parameters,
+                        force: bool = False):
+        """Write the input parameters to file."""
+        d = {
+            _CaptureConfigKeys.RECEIVER_MODE: receiver_mode,
+            _CaptureConfigKeys.RECEIVER_NAME: receiver_name,
+            _CaptureConfigKeys.PARAMETERS   : parameters.to_dict()
+        }
+        self.save(d,
+                  force=force)

spectre_core/capture_configs/_capture_templates.py

@@ -0,0 +1,222 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from copy import deepcopy
+from typing import Any
+from dataclasses import dataclass
+
+from ._parameters import Parameter, Parameters
+from ._pconstraints import PConstraint
+from ._ptemplates import (
+    PTemplate, 
+    PNames,
+    get_base_ptemplate
+)
+
+class CaptureTemplate:
+    """A managed collection of PTemplates"""
+    def __init__(self):
+        self._ptemplates: dict[str, PTemplate] = {}
+
+
+    @property
+    def name_list(self) -> list[str]:
+        """List the names of all stored PTemplates."""
+        return list(self._ptemplates.keys())
+    
+
+    def add_ptemplate(self,
+                      ptemplate: PTemplate) -> None:
+        """Add a ptemplate to this capture template."""
+        self._ptemplates[ptemplate.name] = ptemplate
+
+
+    def get_ptemplate(self,
+                      parameter_name: str) -> PTemplate:
+        """Get the ptemplate corresponding with the parameter name."""
+        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}")   
+        return self._ptemplates[parameter_name]
+      
+
+    def __apply_parameter_template(self,
+                                   parameter: Parameter):
+        """Apply the corresponding parameter template to the input parameter"""
+        ptemplate = self.get_ptemplate(parameter.name)
+        parameter.value = ptemplate.apply_template(parameter.value)
+
+
+    def __apply_parameter_templates(self,
+                                    parameters: Parameters) -> None:
+        """Apply the corresponding parameter template to all explictly specified parameters"""
+        for parameter in parameters:
+            self.__apply_parameter_template(parameter)
+
+    
+    def __fill_missing_with_defaults(self,
+                                     parameters: Parameters) -> None:
+        """For any missing parameters (as per the capture template), use the corresponding default value."""
+        for ptemplate in self:
+            if ptemplate.name not in parameters.name_list:
+                parameter = ptemplate.make_parameter()
+                parameters.add_parameter(parameter.name, 
+                                         parameter.value)
+
+
+    def apply_template(self,
+                       parameters: Parameters) -> Parameters:
+        """Validate parameters, fill missing with defaults, and return anew."""
+        self.__apply_parameter_templates(parameters)
+        self.__fill_missing_with_defaults(parameters)
+        return parameters
+
+
+    def __iter__(self):
+        """Iterate over stored ptemplates"""
+        yield from self._ptemplates.values() 
+
+
+    def set_default(self, 
+                    parameter_name: str, 
+                    default: Any) -> None:
+        """Set the default of an existing ptemplate."""
+        self.get_ptemplate(parameter_name).default = default
+
+
+    def set_defaults(self, 
+                     *ptuples: tuple[str, Any]) -> None:
+        """Update defaults for multiple ptemplates."""
+        for (parameter_name, default) in ptuples:
+            self.set_default(parameter_name, default)
+
+
+    def enforce_default(self,
+                        parameter_name: str) -> None:
+        """Enforce the default of an existing ptemplate"""
+        self.get_ptemplate(parameter_name).enforce_default = True
+
+
+    def enforce_defaults(self, 
+                         *parameter_names: str) -> None:
+        """Enforce defaults for multiple parameter names."""
+        for name in parameter_names:
+            self.enforce_default(name)
+
+
+    def add_pconstraint(self,
+                        parameter_name: str,
+                        pconstraints: list[PConstraint]) -> None:
+        """Add a pconstraint to an existing ptemplate"""
+        for pconstraint in pconstraints:
+            self.get_ptemplate(parameter_name).add_pconstraint(pconstraint)
+
+
+    def to_dict(self) -> dict:
+        return {ptemplate.name: ptemplate.to_dict() for ptemplate in self}
+
+
+def make_base_capture_template(*parameter_names: str):
+    """Make a capture template, composed entirely of base ptemplates."""
+    capture_template = CaptureTemplate()
+    for name in parameter_names:
+        capture_template.add_ptemplate( get_base_ptemplate(name) )
+    return capture_template
+
+
+@dataclass(frozen=True)
+class CaptureModes:
+    """Pre-defined capture types"""
+    FIXED_CENTER_FREQUENCY: str = "fixed-center-frequency"
+    SWEPT_CENTER_FREQUENCY: str = "swept-center-frequency"
+
+
+def _make_fixed_frequency_capture_template(
+) -> CaptureTemplate:
+    """The absolute minimum required parameters for any fixed frequency capture template."""
+    capture_template = make_base_capture_template(
+        PNames.BATCH_SIZE,
+        PNames.CENTER_FREQUENCY,
+        PNames.CHUNK_KEY,
+        PNames.EVENT_HANDLER_KEY,
+        PNames.FREQUENCY_RESOLUTION,
+        PNames.INSTRUMENT,
+        PNames.OBS_ALT,
+        PNames.OBS_LAT,
+        PNames.OBS_LON,
+        PNames.OBJECT,
+        PNames.ORIGIN,
+        PNames.SAMPLE_RATE,
+        PNames.TELESCOPE,
+        PNames.TIME_RANGE,
+        PNames.TIME_RESOLUTION,
+        PNames.WATCH_EXTENSION,
+        PNames.WINDOW_HOP,
+        PNames.WINDOW_SIZE,
+        PNames.WINDOW_TYPE,
+    )
+    capture_template.set_defaults(
+            (PNames.EVENT_HANDLER_KEY,     CaptureModes.FIXED_CENTER_FREQUENCY),
+            (PNames.CHUNK_KEY,             CaptureModes.FIXED_CENTER_FREQUENCY),
+            (PNames.WATCH_EXTENSION,       "bin")
+    )
+    capture_template.enforce_defaults(
+        PNames.EVENT_HANDLER_KEY,
+        PNames.CHUNK_KEY,
+        PNames.WATCH_EXTENSION
+    )
+    return capture_template
+
+def _make_swept_frequency_capture_template(
+) -> CaptureTemplate:
+    """The absolute minimum required parameters for any swept frequency capture template."""
+    capture_template = make_base_capture_template(
+        PNames.BATCH_SIZE,
+        PNames.CHUNK_KEY,
+        PNames.EVENT_HANDLER_KEY,
+        PNames.FREQUENCY_RESOLUTION,
+        PNames.FREQUENCY_STEP,
+        PNames.INSTRUMENT,
+        PNames.MAX_FREQUENCY,
+        PNames.MIN_FREQUENCY,
+        PNames.OBS_ALT,
+        PNames.OBS_LAT,
+        PNames.OBS_LON,
+        PNames.OBJECT,
+        PNames.ORIGIN,
+        PNames.SAMPLE_RATE,
+        PNames.SAMPLES_PER_STEP,
+        PNames.TELESCOPE,
+        PNames.TIME_RANGE,
+        PNames.TIME_RESOLUTION,
+        PNames.WATCH_EXTENSION,
+        PNames.WINDOW_HOP,
+        PNames.WINDOW_SIZE,
+        PNames.WINDOW_TYPE)
+    capture_template.set_defaults(
+            (PNames.EVENT_HANDLER_KEY,     CaptureModes.SWEPT_CENTER_FREQUENCY),
+            (PNames.CHUNK_KEY,             CaptureModes.SWEPT_CENTER_FREQUENCY),
+            (PNames.WATCH_EXTENSION,       "bin")
+    )
+    capture_template.enforce_defaults(
+        PNames.EVENT_HANDLER_KEY,
+        PNames.CHUNK_KEY,
+        PNames.WATCH_EXTENSION
+    )
+    return capture_template
+
+
+_base_capture_templates = {
+    CaptureModes.FIXED_CENTER_FREQUENCY: _make_fixed_frequency_capture_template(),
+    CaptureModes.SWEPT_CENTER_FREQUENCY: _make_swept_frequency_capture_template()
+}
+
+def get_base_capture_template(
+       capture_mode: str
+) -> CaptureTemplate:
+    """Create a fresh deep copy of a pre-defined capture template"""
+    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] )

spectre_core/capture_configs/_parameters.py

@@ -0,0 +1,110 @@
+# 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 Any, Optional, TypeVar
+
+T = TypeVar('T')
+
+class Parameter:
+    """A named value."""
+    def __init__(self, 
+                 name: str,
+                 value: Optional[T] = None):
+        self._name = name
+        self._value: Optional[T] = value
+
+
+    @property
+    def name(self) -> str:
+        """The parameter name."""
+        return self._name
+    
+
+    @property
+    def value(self) -> Optional[T]:
+        """The parameter value."""
+        return self._value
+    
+    
+    @value.setter
+    def value(self, v: Optional[T]) -> None:
+        """Update the parameter value."""
+        self._value = v
+
+
+class Parameters:
+    """A collection of parameters."""
+    def __init__(self):
+        self._parameters: dict[str, Parameter] = {}
+    
+
+    @property
+    def name_list(self) -> list[str]:
+        """List the names of stored parameters."""
+        return list(self._parameters.keys())
+
+
+    def add_parameter(self, 
+                      name: str,
+                      value: Optional[T] = None,
+                      force: bool = False) -> None:
+        """Add a new parameter."""
+        if name in self._parameters and not force:
+            raise ValueError(f"Cannot add a parameter with name '{name}', "
+                             f"since a parameter already exists with that name. "
+                             f"You can overrride this functionality with 'force', "
+                             f"to overwrite the existing parameter.")
+        self._parameters[name] = Parameter(name, value)
+
+
+    def get_parameter(self, 
+                      name: str) -> Parameter:
+        """Get the parameter with the corresponding name."""
+        if name not in self._parameters:
+            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: str) -> Optional[T]:
+        """Get the value of the parameter with the corresponding name."""
+        return self.get_parameter(name).value
+    
+
+    def __iter__(self):
+        """Iterate over stored parameters"""
+        yield from self._parameters.values() 
+
+    
+    def to_dict(self) -> dict:
+        """Convert the class instance to an equivalent dictionary representation"""
+        return {p.name: p.value for p in self}
+    
+def _parse_string_parameter(string_parameter: str) -> list[str]:
+    """Parse string of the form 'a=b; into a list of the form [a, b]"""
+    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('='):
+        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]:
+    """Parses a list of strings of the form 'a=b'; into a dictionary mapping each 'a' to each 'b'"""
+    d = {}
+    for string_parameter in string_parameters:
+        k, v = _parse_string_parameter(string_parameter)
+        d[k] = v
+    return d
+    
+
+def make_parameters(d: dict[str, Any]):
+    """Make an instance of parameters based on the input dictionary"""
+    parameters = Parameters()
+    for k, v in d.items():
+        parameters.add_parameter(k, v)
+    return parameters

spectre_core/capture_configs/_pconstraints.py

@@ -0,0 +1,82 @@
+# SPDX-FileCopyrightText: © 2024 Jimmy Fitzpatrick <jcfitzpatrick12@gmail.com>
+# This file is part of SPECTRE
+# SPDX-License-Identifier: GPL-3.0-or-later
+
+from dataclasses import dataclass
+from abc import ABC, abstractmethod
+from typing import TypeVar, Optional, Any
+from numbers import Number
+
+T = TypeVar('T')
+
+class PConstraint(ABC):
+    """Abstract base class for parameter constraints."""
+
+    @abstractmethod
+    def constrain(self, value: T) -> None:
+        """Apply a constraint to the input parameter."""
+        pass
+
+    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):
+        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:
+        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}. "
+                                 f"Got {value}.")
+            if not self._strict_lower and value < self._lower_bound:
+                raise ValueError(f"Value must be greater than or equal to {self._lower_bound}. "
+                                 f"Got {value}.")
+
+        if self._upper_bound is not None:
+            if self._strict_upper and value >= self._upper_bound:
+                raise ValueError(f"Value must be strictly less than {self._upper_bound}. "
+                                 f"Got {value}.")
+            if not self._strict_upper and value > self._upper_bound:
+                raise ValueError(f"Value must be less than or equal to {self._upper_bound}. "
+                                 f"Got {value}.")
+
+
+class OneOf(PConstraint):
+    """Constrain a parameter to one of a set of defined options."""
+
+    def __init__(self, options: list[Any] = None):
+        self._options = options
+
+
+    def constrain(self, value: Any) -> None:
+        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:
+        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)