sopp 0.1.0__py3-none-any.whl

examples/example.py

@@ -0,0 +1,119 @@
+from sopp.utilities import read_datetime_string_as_utc
+from sopp.satellites_loader.satellites_loader_from_files import \
+    SatellitesLoaderFromFiles
+from sopp.event_finder.event_finder_rhodesmill.event_finder_rhodesmill import \
+    EventFinderRhodesmill
+from sopp.path_finder.observation_path_finder_rhodesmill import \
+    ObservationPathFinderRhodesmill
+from sopp.custom_dataclasses.observation_target import ObservationTarget
+from sopp.custom_dataclasses.facility import Facility
+from sopp.custom_dataclasses.coordinates import Coordinates
+from sopp.custom_dataclasses.time_window import TimeWindow
+from sopp.custom_dataclasses.reservation import Reservation
+from sopp.custom_dataclasses.runtime_settings import RuntimeSettings
+from sopp.custom_dataclasses.frequency_range.frequency_range import \
+    FrequencyRange
+from sopp.frequency_filter.frequency_filter import FrequencyFilter
+from datetime import timedelta
+
+
+def main():
+    # Facility
+    facility = Facility(
+        Coordinates(
+            latitude=40.8178049,
+            longitude=-121.4695413,
+        ),
+        elevation=986,  # meters
+        beamwidth=3,    # degrees
+        name='HCRO',
+    )
+
+    # Observation Window
+    time_window = TimeWindow(
+        begin=read_datetime_string_as_utc('2023-11-15T08:00:00.000000'),
+        end=read_datetime_string_as_utc('2023-11-15T08:30:00.000000'),
+    )
+
+    # Frequency Range
+    frequency_range = FrequencyRange(bandwidth=10, frequency=135)
+
+    # Reservation
+    reservation = Reservation(
+        facility=facility,
+        time=time_window,
+        frequency=frequency_range
+    )
+
+    # Specify Observation Target
+    observation_target = ObservationTarget(
+        declination='7d24m25.426s',
+        right_ascension='5h55m10.3s'
+    )
+
+    # Antenna Direction Path (going to do automatically)
+    antenna_direction_path = ObservationPathFinderRhodesmill(
+        facility,
+        observation_target,
+        time_window
+    ).calculate_path()
+
+    # Load Satellites
+    all_satellites = SatellitesLoaderFromFiles(
+        tle_file='./satellites.tle',
+    ).load_satellites()
+
+    # Filter satellites on frequency (optional, going to do automatically)
+    filtered_satellites = FrequencyFilter(
+        satellites=all_satellites,
+        observation_frequency=frequency_range
+    ).filter_frequencies()
+
+    # Runtime Settings
+    runtime_settings = RuntimeSettings(
+        concurrency_level=8,
+        time_continuity_resolution=timedelta(seconds=1)
+    )
+
+    # Display configuration
+    print('\nFinding satellite interference events for:\n')
+    print(f'Facility: {reservation.facility.name}')
+    print(f'Location: {reservation.facility.coordinates} at elevation '
+          f'{reservation.facility.elevation}')
+    print(f'Reservation start time: {reservation.time.begin}')
+    print(f'Reservation end time: {reservation.time.end}')
+    print(f'Observation frequency: {reservation.frequency.frequency} MHz')
+    print(f'Observing celestial object at: '
+          f'Declination: {observation_target.declination} '
+          f'Right Ascension:{observation_target.right_ascension}')
+
+    # Determine Satellite Interference
+    interference_events = EventFinderRhodesmill(
+        list_of_satellites=filtered_satellites,
+        reservation=reservation,
+        antenna_direction_path=antenna_direction_path,
+        runtime_settings=runtime_settings,
+    ).get_satellites_crossing_main_beam()
+
+    ########################################################################
+
+    print('\n==============================================================\n')
+    print(f'There are {len(interference_events)} satellite interference\n'
+          f'events during the reservation\n')
+    print('==============================================================\n')
+
+    for i, window in enumerate(interference_events, start=1):
+        max_alt = max(window.positions, key=lambda pt: pt.position.altitude)
+
+        print(f'Satellite interference event #{i}:')
+        print(f'Satellite: {window.satellite.name}')
+        print(f'Satellite enters view: {window.overhead_time.begin} at '
+              f'{window.positions[0].position.azimuth:.2f}')
+        print(f'Satellite leaves view: {window.overhead_time.end} at '
+              f'{window.positions[-1].position.azimuth:.2f}')
+        print(f'Satellite maximum altitude: {max_alt.position.altitude:.2f}')
+        print('__________________________________________________\n')
+
+
+if __name__ == '__main__':
+    main()

sopp/builder/configuration_builder.py

@@ -0,0 +1,119 @@
+from sopp.custom_dataclasses.observation_target import ObservationTarget
+from sopp.custom_dataclasses.facility import Facility
+from sopp.custom_dataclasses.coordinates import Coordinates
+from sopp.custom_dataclasses.time_window import TimeWindow
+from sopp.custom_dataclasses.reservation import Reservation
+from sopp.custom_dataclasses.runtime_settings import RuntimeSettings
+from sopp.custom_dataclasses.frequency_range.frequency_range import FrequencyRange
+from sopp.path_finder.observation_path_finder_rhodesmill import ObservationPathFinderRhodesmill
+from sopp.frequency_filter.frequency_filter import FrequencyFilter
+from sopp.satellites_loader.satellites_loader_from_files import SatellitesLoaderFromFiles
+from sopp.config_file.config_file_factory import get_config_file_object
+
+from typing import Optional
+from datetime import datetime, timedelta
+
+
+class ConfigurationBuilder:
+    def __init__(self):
+        self._facility = None
+        self._time_window = None
+        self._frequency_range = None
+        self._observation_target = None
+
+        self.antenna_direction_path = None
+        self.satellites = None
+        self.reservation = None
+        self.runtime_settings = RuntimeSettings()
+
+    def set_facility(self,
+            latitude: float,
+            longitude: float,
+            elevation: float,
+            name: str,
+            beamwidth: float,
+            bandwidth: float,
+            frequency: float,
+        ):
+        self._facility = Facility(
+            Coordinates(latitude=latitude, longitude=longitude),
+            elevation=elevation,
+            beamwidth=beamwidth,
+            name=name,
+        )
+        self._frequency_range = FrequencyRange(
+            bandwidth=bandwidth,
+            frequency=frequency,
+        )
+        return self
+
+    def set_time_window(self, begin: datetime, end: datetime):
+        self._time_window = TimeWindow(
+            begin=begin,
+            end=end,
+        )
+        return self
+
+    def set_observation_target(self, declination: str, right_ascension: str):
+        self._observation_target = ObservationTarget(
+            declination=declination,
+            right_ascension=right_ascension,
+        )
+        return self
+
+    def set_satellites(self, tle_file: str, frequency_file: Optional[str] = None):
+        self.satellites = SatellitesLoaderFromFiles(
+            tle_file=tle_file,
+            frequency_file=frequency_file,
+        ).load_satellites()
+        return self
+
+    def set_runtime_settings(self, concurrency_level: int, time_continuity_resolution: int):
+        self.runtime_settings = RuntimeSettings(
+            concurrency_level=concurrency_level,
+            time_continuity_resolution=time_continuity_resolution,
+        )
+        return self
+
+    def set_config_file(self, config_file: str):
+        config = get_config_file_object(config_filepath=config_file).configuration
+        self._frequency_range = config.reservation.frequency
+        self._facility = config.reservation.facility
+        self._time_window = config.reservation.time
+        self._observation_target = config.observation_target
+        self.runtime_settings = config.runtime_settings
+        return self
+
+    def _frequency_filter_satellites(self):
+        self.satellites = FrequencyFilter(
+            satellites=self.satellites,
+            observation_frequency=self._frequency_range
+        ).filter_frequencies()
+
+    def _build_reservation(self):
+        self.reservation = Reservation(
+            facility=self._facility,
+            time=self._time_window,
+            frequency=self._frequency_range
+        )
+
+    def _build_antenna_direction_path(self):
+        if self._observation_target is not None:
+            self.antenna_direction_path = ObservationPathFinderRhodesmill(
+                self._facility,
+                self._observation_target,
+                self._time_window
+            ).calculate_path()
+
+    def build(self):
+        if not all(
+            [self._facility, self._time_window, self._frequency_range,
+             self._observation_target, self.satellites]
+        ):
+            raise ValueError("Incomplete configuration. Please set all required parameters.")
+
+        self._frequency_filter_satellites()
+        self._build_antenna_direction_path()
+        self._build_reservation()
+
+        return self

sopp/config_file/config_file_factory.py

@@ -0,0 +1,13 @@
+from pathlib import Path
+from typing import Optional
+
+from sopp.config_file.support.config_file_base import ConfigFileBase
+from sopp.config_file.support.config_file_json import ConfigFileJson
+from sopp.utilities import get_default_config_file_filepath
+
+
+def get_config_file_object(config_filepath: Optional[Path] = None) -> ConfigFileBase:
+    config_filepath = config_filepath or get_default_config_file_filepath()
+    for config_class in [ConfigFileJson]:
+        if config_class.filename_extension() in str(config_filepath):
+            return config_class(filepath=config_filepath)

sopp/config_file/support/config_file_base.py

@@ -0,0 +1,20 @@
+from abc import ABC, abstractmethod
+from functools import cached_property
+from pathlib import Path
+
+from sopp.custom_dataclasses.configuration import Configuration
+
+
+class ConfigFileBase(ABC):
+    def __init__(self, filepath: Path):
+        self._filepath = filepath
+
+    @cached_property
+    @abstractmethod
+    def configuration(self) -> Configuration:
+        pass
+
+    @classmethod
+    @abstractmethod
+    def filename_extension(cls) -> str:
+        pass

sopp/config_file/support/config_file_json.py

@@ -0,0 +1,108 @@
+import json
+from functools import cached_property
+from typing import List
+
+from sopp.config_file.support.config_file_base import ConfigFileBase
+from sopp.custom_dataclasses.configuration import Configuration
+from sopp.custom_dataclasses.coordinates import Coordinates
+from sopp.custom_dataclasses.facility import Facility
+from sopp.custom_dataclasses.frequency_range.frequency_range import FrequencyRange
+from sopp.custom_dataclasses.observation_target import ObservationTarget
+from sopp.custom_dataclasses.position import Position
+from sopp.custom_dataclasses.position_time import PositionTime
+from sopp.custom_dataclasses.reservation import Reservation
+from sopp.custom_dataclasses.time_window import TimeWindow
+from sopp.custom_dataclasses.runtime_settings import RuntimeSettings
+from sopp.utilities import read_datetime_string_as_utc
+
+
+class ConfigFileJson(ConfigFileBase):
+    @cached_property
+    def configuration(self) -> Configuration:
+        return Configuration(
+            reservation=self._reservation,
+            runtime_settings=self._runtime_settings,
+            antenna_position_times=self._antenna_position_times,
+            observation_target=self._observation_target,
+            static_antenna_position=self._static_antenna_position
+        )
+
+    @cached_property
+    def _reservation(self) -> Reservation:
+        return Reservation(
+            facility=self._facility,
+            time=self._reservation_window,
+            frequency=self._frequency_range
+        )
+
+    @cached_property
+    def _facility(self) -> Facility:
+        configuration = self._config_object.get('facility')
+
+        return Facility(
+                coordinates=Coordinates(
+                    latitude=configuration['latitude'],
+                    longitude=configuration['longitude']
+                ),
+                name=configuration['name'],
+                elevation=configuration['elevation'],
+        )
+
+    @cached_property
+    def _reservation_window(self) -> TimeWindow:
+        configuration = self._config_object.get('reservationWindow')
+        start_datetime = read_datetime_string_as_utc(configuration['startTimeUtc'])
+        end_datetime_str = read_datetime_string_as_utc(configuration['endTimeUtc'])
+
+        return TimeWindow(begin=start_datetime, end=end_datetime_str)
+
+    @cached_property
+    def _frequency_range(self) -> FrequencyRange:
+        configuration = self._config_object.get('frequencyRange')
+
+        return FrequencyRange(
+            frequency=configuration['frequency'],
+            bandwidth=configuration['bandwidth']
+        )
+
+    @cached_property
+    def _runtime_settings(self) -> RuntimeSettings:
+        configuration = self._config_object.get('runtimeSettings')
+
+        return RuntimeSettings(
+            time_continuity_resolution=configuration['time_continuity_resolution'],
+            concurrency_level=configuration['concurrency_level']
+        ) if configuration else RuntimeSettings()
+
+    @cached_property
+    def _antenna_position_times(self) -> List[PositionTime]:
+        configuration = self._config_object.get('antennaPositionTimes')
+        return configuration and [PositionTime(position=Position(altitude=position_time['altitude'],
+                                                                 azimuth=position_time['azimuth']),
+                                               time=read_datetime_string_as_utc(string_value=position_time['time']))
+                                  for position_time in configuration]
+
+    @cached_property
+    def _observation_target(self) -> ObservationTarget:
+        configuration = self._config_object.get('observationTarget')
+        return configuration and ObservationTarget(
+            declination=configuration['declination'],
+            right_ascension=configuration['rightAscension']
+        )
+
+    @cached_property
+    def _static_antenna_position(self) -> Position:
+        configuration = self._config_object.get('staticAntennaPosition')
+        return configuration and Position(
+            altitude=configuration['altitude'],
+            azimuth=configuration['azimuth']
+        )
+
+    @cached_property
+    def _config_object(self) -> dict:
+        with open(self._filepath, 'r') as f:
+            return json.load(f)
+
+    @classmethod
+    def filename_extension(cls) -> str:
+        return '.json'

sopp/config_file/support/utilities.py

@@ -0,0 +1 @@
+TIME_FORMAT = '%Y-%m-%dT%H:%M:%S.%f'

sopp/custom_dataclasses/configuration.py

@@ -0,0 +1,17 @@
+from dataclasses import dataclass
+from typing import List, Optional
+
+from sopp.custom_dataclasses.observation_target import ObservationTarget
+from sopp.custom_dataclasses.position import Position
+from sopp.custom_dataclasses.position_time import PositionTime
+from sopp.custom_dataclasses.reservation import Reservation
+from sopp.custom_dataclasses.runtime_settings import RuntimeSettings
+
+
+@dataclass
+class Configuration:
+    reservation: Reservation
+    runtime_settings: Optional[RuntimeSettings] = RuntimeSettings()
+    antenna_position_times: Optional[List[PositionTime]] = None
+    observation_target: Optional[ObservationTarget] = None
+    static_antenna_position: Optional[Position] = None

sopp/custom_dataclasses/coordinates.py

@@ -0,0 +1,20 @@
+from dataclasses import dataclass
+from enum import Enum
+
+
+class CoordinatesJsonKey(Enum):
+    latitude = 'latitude'
+    longitude = 'longitude'
+
+
+@dataclass
+class Coordinates:
+    latitude: float
+    longitude: float
+
+    @classmethod
+    def from_json(cls, info: dict) -> 'Coordinates':
+        return cls(
+            latitude=info[CoordinatesJsonKey.latitude.value],
+            longitude=info[CoordinatesJsonKey.longitude.value]
+        )

sopp/custom_dataclasses/facility.py

@@ -0,0 +1,26 @@
+from dataclasses import dataclass, field
+from sopp.custom_dataclasses.coordinates import Coordinates
+from typing import List, Optional
+
+from sopp.custom_dataclasses.position_time import PositionTime
+
+
+@dataclass
+class Facility:
+    '''
+    The Facility data class contains the observation parameters of the facility and the object it is tracking, including coordinates
+    of the RA telescope and its beamwidth, as well as the right ascension and declination values for its observation target:
+
+    -coordinates:       location of RA facility. Coordinates.
+    -beamwidth:         beamwidth of the telescope. float. Defaults to 3
+    -elevation:         ground elevation of the telescope in meters. float. Defaults to 0
+    -name:              name of the facility. String. Defaults to 'Unnamed Facility'
+    '''
+    coordinates: Coordinates
+    beamwidth: float = 3
+    elevation: float = 0
+    name: Optional[str] = 'Unnamed Facility'
+
+    @property
+    def half_beamwidth(self) -> float:
+        return self.beamwidth / 2

sopp/custom_dataclasses/frequency_range/frequency_range.py

@@ -0,0 +1,36 @@
+from dataclasses import dataclass
+from typing import Optional
+
+'''
+The FrequencyRange class is used for storing frequency ranges of both the RA telescopes observation and each satellite's downlink transmission
+frequency information. The frequency parameter represents the center frequency of the observation or downlink. The status parameter is only relevant
+to satellites and is used to store information from the satellite frequency database on whether an antenna is operational 'active' or not 'inactive'
+
+The overlaps function determines if two FrequencyRanges overlap with each other and is used to determine if any of the satellite downlink frequencies
+overlap with the observation frequency. Satellite frequency data is read from a csv file (as of May 15, 2023) using the GetFrequencyDataFromCsv class
+under the support folder.f
+
+'''
+
+DEFAULT_BANDWIDTH = 10
+
+@dataclass
+class FrequencyRange:
+    frequency: Optional[float] = None
+    bandwidth: Optional[float] = None
+    status: Optional[str] = None
+
+    def overlaps(self, satellite_frequency: 'FrequencyRange'):
+        half_bandwidth_res = self.bandwidth/2
+        if satellite_frequency.bandwidth is None:
+            low_in_mghz_sat = satellite_frequency.frequency - (DEFAULT_BANDWIDTH/2)
+            high_in_mghz_sat = satellite_frequency.frequency + (DEFAULT_BANDWIDTH/2)
+            low_in_mghz_res = self.frequency - half_bandwidth_res
+            high_in_mghz_res = self.frequency + half_bandwidth_res
+        else:
+            half_bandwidth_sat = satellite_frequency.bandwidth / 2
+            low_in_mghz_res = self.frequency - half_bandwidth_res
+            high_in_mghz_res = self.frequency + half_bandwidth_res
+            low_in_mghz_sat = satellite_frequency.frequency - half_bandwidth_sat
+            high_in_mghz_sat = satellite_frequency.frequency + half_bandwidth_sat
+        return low_in_mghz_sat < high_in_mghz_res and high_in_mghz_sat > low_in_mghz_res

sopp/custom_dataclasses/frequency_range/support/get_frequency_data_from_csv.py

@@ -0,0 +1,75 @@
+import csv
+from enum import Enum
+from pathlib import Path
+from typing import Dict, List
+from collections import defaultdict
+
+from sopp.custom_dataclasses.frequency_range.frequency_range import FrequencyRange
+
+
+class FrequencyCsvKeys(Enum):
+    LINENO = ''
+    ID = 'ID'
+    NAME = 'Name'
+    FREQUENCY = 'Frequency [MHz]'
+    BANDWIDTH = 'Bandwidth [kHz]/Baud'
+    STATUS = 'Status'
+    DESCRIPTION = 'Description'
+    SOURCE = 'Source'
+
+
+class GetFrequencyDataFromCsv:
+    '''
+    Reads frequency data from a supplied CSV. The CSV should be placed in the `supplements` folder under the name `satellite_frequencies.csv` and should be
+    formatted with the following columns:
+    ________________________________________________________________________________________________________
+    | LineNo |   ID   |   Name   |   Frequency   |   Bandwidth   |   Status   |   Description   |  Source  |
+
+    With all values in the frequency column of the same order of magnitude (typically MHz). The same goes for bandwidth. These columns should have the
+    integer value alone.
+
+
+    '''
+    def __init__(self, filepath: Path):
+        self._filepath = filepath
+
+    def get(self) -> Dict[int, List['FrequencyRange']]:
+        frequencies = defaultdict(list)
+        for line in self._data[1:]:
+            id_string = line[FrequencyCsvKeys.ID.value]
+            if not id_string or id_string == 'None' or id_string == "nan":
+                continue
+
+            frequency_range = FrequencyRange(frequency=self._get_frequency(line),
+                                             bandwidth=self._get_bandwidth(line),
+                                             status=self._get_status(line))
+            id_int = int(id_string)
+            frequencies[id_int].append(frequency_range)
+
+        return frequencies
+
+    @staticmethod
+    def _get_frequency(line: Dict[str, str]):
+        frequency = line[FrequencyCsvKeys.FREQUENCY.value]
+        try:
+            return float(frequency)
+        except (TypeError, ValueError):
+            return None
+
+    @staticmethod
+    def _get_bandwidth(line: Dict[str, str]):
+        bandwidth = line[FrequencyCsvKeys.BANDWIDTH.value]
+        try:
+            return float(bandwidth.split()[0])
+        except (TypeError, ValueError, IndexError):
+            return None
+
+    @staticmethod
+    def _get_status(line: Dict[str, str]):
+        status = line[FrequencyCsvKeys.STATUS.value].lower()
+        return status
+
+    @property
+    def _data(self) -> List[Dict[str, str]]:
+        with open(self._filepath, 'r') as file:
+            return list(csv.DictReader(file, fieldnames=[e.value for e in FrequencyCsvKeys]))

sopp/custom_dataclasses/observation_target.py

@@ -0,0 +1,7 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class ObservationTarget:
+    declination: str
+    right_ascension: str

sopp/custom_dataclasses/overhead_window.py

@@ -0,0 +1,31 @@
+from dataclasses import dataclass, field
+from operator import attrgetter
+from typing import List
+from sopp.custom_dataclasses.satellite.satellite import Satellite
+from sopp.custom_dataclasses.time_window import TimeWindow
+from sopp.custom_dataclasses.position_time import PositionTime
+
+'''
+OverheadWindow class is designed to store the time windows that a given satellite is overhead and includes the Satellite object,
+as well as a TimeWindow object that contains the interference start and end times.
+
+  + satellite:      the Satellite that is overhead during the time window.
+  + positions:      a list of PositionTimes of the satellite while within the main beam
+  + overhead_time:  a property TimeWindow representing the time the satellite enters and exits view.
+'''
+
+@dataclass
+class OverheadWindow:
+    satellite: Satellite
+    positions: List[PositionTime] = field(default_factory=list)
+
+    def __post_init__(self):
+        self.positions.sort(key=attrgetter('time'))
+
+    @property
+    def overhead_time(self):
+        if not self.positions:
+            return None
+        begin = self.positions[0].time
+        end = self.positions[-1].time
+        return TimeWindow(begin=begin, end=end)

sopp/custom_dataclasses/position.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class Position:
+    """
+    + altitude: degrees above the horizon
+    + azimuth: degrees east along the horizon from geographic north (so 0 degrees means north, 90 is east, 180
+        is south, and 270 is west).
+    """
+    altitude: float
+    azimuth: float

sopp/custom_dataclasses/position_time.py

@@ -0,0 +1,10 @@
+from dataclasses import dataclass
+from datetime import datetime
+
+from sopp.custom_dataclasses.position import Position
+
+
+@dataclass
+class PositionTime:
+    position: Position
+    time: datetime

sopp/custom_dataclasses/reservation.py

@@ -0,0 +1,19 @@
+from dataclasses import dataclass, field
+
+from sopp.custom_dataclasses.facility import Facility
+from sopp.custom_dataclasses.frequency_range.frequency_range import FrequencyRange
+from sopp.custom_dataclasses.time_window import TimeWindow
+
+'''
+The Reservation class stores the Facility, as well as some additional reservation-specific information, such as reservation start and end times.
+  + facility:   Facility object with RA facility and observation parameters
+  + time:       TimeWindow that represents the start and end time of the ideal reservation.
+  + frequency:  FrequencyRange of the requested observation. This is the frequency that the RA telescope wants to observe at.
+'''
+
+
+@dataclass
+class Reservation:
+    facility: Facility
+    time: TimeWindow
+    frequency: FrequencyRange = field(default_factory=FrequencyRange)