| Name | sopp JSON |
| Version |
0.8.2
JSON |
| download |
| home_page | None |
| Summary | SOPP is an open-source tool for calculating satellite interference to radio astronomy observations. |
| upload_time | 2024-04-18 19:30:56 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | None |
| keywords |
astronomy
satellites
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# S.O.P.P. - Satellite Orbit Prediction Processor
## Quick Start Guide
Welcome to S.O.P.P., an open-source tool for calculating satellite interference in radio astronomy observations.
### Introduction
The SOPP package assists astronomers in optimizing observation scheduling to mitigate radio interference from satellite sources. This is achieved by computing the positions of satellites relative to the observation facility and determining which of these satellites cause interference with the main beam during the observation.
The primary functionality offered by the package is accessed through the `Sopp` class. This class implements two methods:
- `get_satellites_crossing_main_beam`
- `get_satellites_above_horizon`
### High-Level Overview
1. **Define Observation Characteristics:**
- Provide the necessary observation characteristics to the `ConfigurationBuilder` class:
- Facility Location
- Observation Time Window
- Antenna Frequency and Bandwidth
- Antenna observation path
- Satellite TLE data
- Satellite Filtering (optional)
- Runtime settings
2. **Determine Satellite Interference:**
- Create an instance of Sopp using the `Configuration` built by the `ConfigurationBuilder` class.
- Utilize the methods of the Sopp class to obtain position data of interfering satellites:
- `get_satellites_crossing_main_beam`: Returns satellites that cross the main beam during observation.
- `get_satellites_above_horizon`: Returns all satellites above the horizon during the observation.
### Define Observation Characteristics
#### `ConfigurationBuilder`
The observation characteristics must be provided to the `ConfigurationBuilder` class. The configuration builder will then construct a fully prepared `Configuration` object used to determine satellite interference.
An example using `ConfigurationBuilder`:
```python
from sopp.builder.configuration_builder import ConfigurationBuilder
configuration = (
ConfigurationBuilder()
.set_facility(
latitude=40.8178049,
longitude=-121.4695413,
elevation=986,
name='HCRO',
beamwidth=3,
)
.set_frequency_range(
bandwidth=10,
frequency=135
)
.set_time_window(
begin='2023-11-15T08:00:00.0',
end='2023-11-15T08:30:00.0'
)
.set_observation_target(
declination='7d24m25.426s',
right_ascension='5h55m10.3s'
)
.set_runtime_settings(
concurrency_level=8,
time_continuity_resolution=1,
min_altitude=5.0,
)
# Alternatively set all of the above settings from a config file
#.set_from_config_file(config_file='./supplements/config.json')
.set_satellites(tle_file='./supplements/satellites.tle')
.build()
)
```
The `ConfigurationBuilder` must call the following methods with the necessary arguments:
- `set_facility()`
- `set_frequency_range()`
- `set_time_window()`
- `set_observation_target()`
- `set_satellites()`
- `set_runtime_settings()`
#### `set_facility()`
The `set_facility()` method specifies the latitude, longitude, elevation (in meters), name, bandwidth, beamwidth and frequency:
```python
configuration.set_facility(
latitude=40.8178049,
longitude=-121.4695413,
elevation=986,
name='HCRO',
beamwidth=3,
bandwidth=10,
frequency=135
)
```
The `set_frequency_range()` method specifies bandwidth, and frequency of the observation:
```python
configuration.set_frequency_range(
bandwidth=10,
frequency=135
)
```
#### `set_time_window()`
The `set_time_window()` method defines the observation time window in UTC, specifying when the observation will take place. The date format follows the ISO 8601 datetime format: `Y-m-dTH:M:S.f`. The provided datetime string can include microseconds or not. It additionally accepts a time zone, for example, `2023-11-15T08:00:00-7:00`. Alternatively, `begin` and `end` can be provided as datetimes. All times are converted to UTC.
```python
configuration.set_time_window(
begin='2023-11-15T08:00:00.0',
end='2023-11-15T08:30:00.0'
)
```
#### `set_observation_target()`
The `set_observation_target()` method defines the target for observation. It has three options:
1. Specify a target by providing its declination and right ascension:
```python
configuration.set_observation_target(
declination='7d24m25.426s',
right_ascension='5h55m10.3s'
)
```
2. Specify a static location to observe by providing an azimuth and altitude:
```python
configuration.set_observation_target(
azimuth=24.2,
altitude=78.1
)
```
3. Provide a custom antenna direction path (how to construct a custom path is explained later):
```python
configuration.set_observation_target(
custom_path=custom_path
)
```
#### `set_satellites()`
The `set_satellites()` method takes the file path of the satellite TLE data and an optional frequency file. The frequency data can be utilized to filter out satellites whose downlink frequency does not overlap with the observation frequency.
```python
configuration.set_satellites(
tle_file='path/to/satellites.tle',
frequency_file='/path/to/frequency.csv' # optional
)
```
#### `set_satellites_filter()`
There is optionally the ability to filter the satellites list. To do this call the `set_satellites_filter()` method with a `Filterer` object. The `Filterer` object is explained in more detail in the 'Filtering Satellites' section.
```python
configuration.set_satellites_filter(
filterer=filterer
)
```
#### `add_filter()`
Alternatively to constructing a `Filterer` object you can simply call `add_filter()`
```python
configuration.add_filter(filter_frequency(FrequencyRange(10, 10)))
```
#### `set_runtime_settings()`
The `set_runtime_settings()` method:
- Specifies the time resolution for calculating satellite positions in seconds via the `time_continuity_resolution` parameter.
- Specifies the `concurrency_level` parameter determines the number of parallel jobs during satellite position calculation, optimizing runtime speeds. This value should be not exceed the number of cores on the machine.
- The `min_altitude` specifies the minimum altitude a satellite must be to be considered above the horizon. Useful for locations with obstructed horizons.
- Runtime settings are optional, the defaults are: concurrency_level = 1, time_continuity_resolution = 1 and min_altitude = 0.0.
```python
configuration.set_runtime_settings(
concurrency_level=8,
time_continuity_resolution=1,
min_altitude=0.0,
)
```
#### `build()`
Finally, once all the required methods have been called use the `build()` method to obtain the `Configuration` object:
```python
configuration = configuration.build()
```
#### `set_from_config_file()`
The `set_from_config_file()` method can be used to provide all of the observation characteristics via a JSON configuration file instead of being set programatically.
```python
configuration = (
ConfigurationBuilder()
.set_from_config_file(config_file='./supplements/config.json')
.set_satellites(tle_file='./supplements/satellites.tle')
.build()
)
```
The JSON config file follows the following format:
```
{
"facility": {
"beamwidth": 3,
"elevation": 986,
"latitude": 40.8178049,
"longitude": -121.4695413,
"name": "HCRO"
},
"frequencyRange": {
"bandwidth": 10,
"frequency": 135
},
"observationTarget": {
"declination": "-38d6m50.8s",
"rightAscension": "4h42m"
},
"reservationWindow": {
"startTimeUtc": "2023-09-27T12:00:00.000000",
"endTimeUtc": "2023-09-27T13:00:00.000000"
},
"runtimeSettings": {
"concurrency_level": 4,
"time_continuity_resolution": 1,
"min_altitude": 0.0
}
}
```
### Determine Satellite Interference
#### `Sopp`
The `Sopp` class utilizes the previously created configuration object to identify satellite interference. It is initialized with the `Configuration` obtained from `ConfigurationBuilder`.
```python
from sopp.sopp import Sopp
sopp = Sopp(configuration=configuration)
```
Finally, obtain the position data of interfering satellites, run either:
- `get_satellites_crossing_main_beam`: Returns satellites that cross the main beam during observation.
- `get_satellites_above_horizon`: Returns all satellites that are above the horizon during the observation.
```python
interference_events = sopp.get_satellites_crossing_main_beam()
```
The data is returned as a list of `OverheadWindow`, which is defined as:
```python
class OverheadWindow:
satellite: Satellite
positions: List[PositionTime]
```
The `Satellite` class, containins details about the satellite and a list of PositionTime objects. The `PositionTime` dataclass specifies the satellite's position in altitude, azimuth and distance in km at a discrete point in time. All times are in UTC.
### Filtering Satellites
The list of satellites can be filtered by using a `Filterer` object, adding filters to it and then passing the `Filterer` object to a `ConfigurationBuilder`. The user can define any filtering logic wanted, however a few built in filters are provided. If the filtering condition evaluates to `True` the Satellite will be included in the final list.
If `None` is passed to any of the filters, no filtering for that specific filter will be applied.
Alternatively to passing a `Filterer` object to the `ConfigurationBuilder` via `set_satellites_filter`, filters can simply be added with `add_filter(filter_name_contains('STARLINK'))`.
The provided filters accessible from `sopp.satellites_filter.filters` include:
#### `filter_frequency()`:
Parameters:
- observation_frequency (FrequencyRange): The observation frequency range.
returns `True` if a satellite's downlink transmission frequency
overlaps with the desired observation frequency. If there is no information
on the satellite frequency, it will return True to err on the side of caution
for potential interference. Requires a `FrequencyRange` object.
#### `filter_name_regex()`:
Parameters:
- regex (str): The regex to match for in the satellite names.
returns `True` if a given regex matches in the name of a Satellite.
Example: filter_name_regex('YAM|ZARYA') will return a list of satellites that
contain YAM or ZARYA within their name.
#### `filter_name_contains()`:
Parameters:
- substring (str): The substring to check for in the satellite names.
returns `True` if a given substring is present in the name of a Satellite.
#### `filter_name_does_not_contain`:
Parameters:
- substring (str): The substring to check for absence for in the satellite names.
returns `True` if a given substring is not present in the name of a Satellite.
#### `filter_name_is()`:
Parameters:
- substring (str): The substring to match for in the satellite names.
returns `True` if a given substring matches exactly the name of a Satellite.
#### `filter_orbit_is(orbit_type)`:
Parameters:
- orbit_type (str): The type of orbit ('leo', 'meo', or 'geo').
if orbit_type='leo' returns Low Earth Orbit (LEO) satellites based on their orbital period.
The filter checks if the satellite's orbits per day is >= 5.0
if orbit_type='meo' returns Medium Earth Orbit (MEO) satellites based on their orbital period.
The filter checks if the satellite's orbits per day is >= 1.5 and < 5.0
if orbit_type='geo' returns Geostationary Orbit (GEO) satellites based on their orbital period.
The filter checks if the satellite's orbits per day is >= 0.85 and < 1.5
For example, to find all Satellites that are not Starlink, but are in LEO and that have overlapping downlink transmission frequency:
```python
from sopp.satellites_filter.filterer import Filterer
from sopp.satellites_filter.filters import (
filter_name_does_not_contain,
filter_orbit_is,
filter_frequency,
filter_name_is,
)
filterer = (
Filterer()
.add_filter(filter_name_does_not_contain('STARLINK'))
.add_filter(filter_orbit_is(orbit_type='leo'))
.add_filter(filter_frequency())
.add_filter(filter_name_is(None)) # this filter will do nothing
)
```
User defined filters can be defined as well. The `add_filter` method takes a lambda. For example, if the user would prefer to define LEO satellites differently than the provided filtering function:
```python
filterer = (
Filterer()
.add_filter(lambda satellite: satellite.orbital_period <= 100.0)
)
```
### Using TleFetcher to Obtain TLE File
A TleFetcher class exists that will automatically fetch the latest TLEs from Celestrak or SpaceTrack:
```python
from sopp.tle_fetcher.tle_fetcher_celestrak import TleFetcherCelestrak
fetcher = TleFetcherCelestrak(tle_file_path='path/to/save/satellites.tle')
fetcher.fetch_tles()
```
SpaceTrack is called identically, however you must set the environment variable `IDENTITY` with your username and `PASSWORD` with your password:
```python
from sopp.tle_fetcher.tle_fetcher_spacetrack import TleFetcherSpacetrack
fetcher = TleFetcherSpacetrack(tle_file_path='path/to/save/satellites.tle')
fetcher.fetch_tles()
```
### Providing Custom Path for Observation
Instead of specifying an observation target or static observation with altitude and azimuth a custom path can be provided as a list of `PositionTime` objects.
```python
custom_path = [
PositionTime(
position=Position(altitude=.0, azimuth=.1),
time=datetime(year=2023, month=3, day=30, hour=10, minute=1, tzinfo=pytz.UTC)
),
PositionTime(
position=Position(altitude=.1, azimuth=.2),
time=datetime(year=2023, month=3, day=30, hour=10, minute=2, tzinfo=pytz.UTC)
),
PositionTime(
position=Position(altitude=.2, azimuth=.2),
time=datetime(year=2023, month=3, day=30, hour=10, minute=3, tzinfo=pytz.UTC)
),
]
```
### Example Code
```python
from sopp.sopp import Sopp
from sopp.builder.configuration_builder import ConfigurationBuilder
from sopp.satellites_filter.filters import (
filter_name_does_not_contain,
filter_orbit_is,
)
def main():
configuration = (
ConfigurationBuilder()
.set_facility(
latitude=40.8178049,
longitude=-121.4695413,
elevation=986,
name='HCRO',
beamwidth=3,
)
.set_frequency_range(
bandwidth=10,
frequency=135
)
.set_time_window(
begin='2024-01-18T08:00:00.0',
end='2024-01-18T08:30:00.0'
)
.set_observation_target(
declination='7d24m25.426s',
right_ascension='5h55m10.3s'
)
.set_runtime_settings(
concurrency_level=8,
time_continuity_resolution=1
)
# Alternatively set all of the above settings from a config file
#.set_from_config_file(config_file='./supplements/config.json')
.set_satellites(tle_file='./supplements/satellites.tle')
.add_filter(filter_name_does_not_contain('STARLINK'))
.add_filter(filter_orbit_is(orbit_type='leo'))
.build()
)
# Display configuration
print('\nFinding satellite interference events for:\n')
print(f'Facility: {configuration.reservation.facility.name}')
print(f'Location: {configuration.reservation.facility.coordinates} at elevation '
f'{configuration.reservation.facility.elevation}')
print(f'Reservation start time: {configuration.reservation.time.begin}')
print(f'Reservation end time: {configuration.reservation.time.end}')
print(f'Observation frequency: {configuration.reservation.frequency.frequency} MHz')
# Determine Satellite Interference
sopp = Sopp(configuration=configuration)
interference_events = sopp.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} '
f'Distance: {window.positions[0].position.distance_km:.2f} km')
print(f'Satellite leaves view: {window.overhead_time.end} at '
f'{window.positions[-1].position.azimuth:.2f} '
f'Distance: {window.positions[-1].position.distance_km:.2f} km')
print(f'Satellite maximum altitude: {max_alt.position.altitude:.2f}')
print('__________________________________________________\n')
if __name__ == '__main__':
main()
```
Raw data
{
"_id": null,
"home_page": null,
"name": "sopp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "astronomy, satellites",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/82/00/31d01051938ea630a465c81602fd16802912de67f0435dd6c6bf2e7b6d83/sopp-0.8.2.tar.gz",
"platform": null,
"description": "# S.O.P.P. - Satellite Orbit Prediction Processor\n\n## Quick Start Guide\n\nWelcome to S.O.P.P., an open-source tool for calculating satellite interference in radio astronomy observations.\n\n### Introduction\n\nThe SOPP package assists astronomers in optimizing observation scheduling to mitigate radio interference from satellite sources. This is achieved by computing the positions of satellites relative to the observation facility and determining which of these satellites cause interference with the main beam during the observation.\n\nThe primary functionality offered by the package is accessed through the `Sopp` class. This class implements two methods:\n\n- `get_satellites_crossing_main_beam`\n- `get_satellites_above_horizon`\n\n### High-Level Overview\n\n1. **Define Observation Characteristics:**\n - Provide the necessary observation characteristics to the `ConfigurationBuilder` class:\n - Facility Location\n - Observation Time Window\n - Antenna Frequency and Bandwidth\n - Antenna observation path\n - Satellite TLE data\n - Satellite Filtering (optional)\n - Runtime settings\n\n2. **Determine Satellite Interference:**\n - Create an instance of Sopp using the `Configuration` built by the `ConfigurationBuilder` class.\n - Utilize the methods of the Sopp class to obtain position data of interfering satellites:\n - `get_satellites_crossing_main_beam`: Returns satellites that cross the main beam during observation.\n - `get_satellites_above_horizon`: Returns all satellites above the horizon during the observation.\n\n### Define Observation Characteristics\n\n#### `ConfigurationBuilder`\n\nThe observation characteristics must be provided to the `ConfigurationBuilder` class. The configuration builder will then construct a fully prepared `Configuration` object used to determine satellite interference.\n\nAn example using `ConfigurationBuilder`:\n```python\nfrom sopp.builder.configuration_builder import ConfigurationBuilder\n\nconfiguration = (\n ConfigurationBuilder()\n .set_facility(\n latitude=40.8178049,\n longitude=-121.4695413,\n elevation=986,\n name='HCRO',\n beamwidth=3,\n )\n .set_frequency_range(\n bandwidth=10,\n frequency=135\n )\n .set_time_window(\n begin='2023-11-15T08:00:00.0',\n end='2023-11-15T08:30:00.0'\n )\n .set_observation_target(\n declination='7d24m25.426s',\n right_ascension='5h55m10.3s'\n )\n .set_runtime_settings(\n concurrency_level=8,\n time_continuity_resolution=1,\n min_altitude=5.0,\n )\n # Alternatively set all of the above settings from a config file\n #.set_from_config_file(config_file='./supplements/config.json')\n .set_satellites(tle_file='./supplements/satellites.tle')\n .build()\n)\n```\n\nThe `ConfigurationBuilder` must call the following methods with the necessary arguments:\n\n- `set_facility()`\n- `set_frequency_range()`\n- `set_time_window()`\n- `set_observation_target()`\n- `set_satellites()`\n- `set_runtime_settings()`\n\n#### `set_facility()`\n\nThe `set_facility()` method specifies the latitude, longitude, elevation (in meters), name, bandwidth, beamwidth and frequency:\n\n```python\nconfiguration.set_facility(\n latitude=40.8178049,\n longitude=-121.4695413,\n elevation=986,\n name='HCRO',\n beamwidth=3,\n bandwidth=10,\n frequency=135\n)\n```\n\nThe `set_frequency_range()` method specifies bandwidth, and frequency of the observation:\n\n```python\nconfiguration.set_frequency_range(\n bandwidth=10,\n frequency=135\n)\n```\n\n#### `set_time_window()`\n\nThe `set_time_window()` method defines the observation time window in UTC, specifying when the observation will take place. The date format follows the ISO 8601 datetime format: `Y-m-dTH:M:S.f`. The provided datetime string can include microseconds or not. It additionally accepts a time zone, for example, `2023-11-15T08:00:00-7:00`. Alternatively, `begin` and `end` can be provided as datetimes. All times are converted to UTC.\n\n```python\nconfiguration.set_time_window(\n begin='2023-11-15T08:00:00.0',\n end='2023-11-15T08:30:00.0'\n)\n```\n\n#### `set_observation_target()`\n\nThe `set_observation_target()` method defines the target for observation. It has three options:\n\n1. Specify a target by providing its declination and right ascension:\n\n```python\nconfiguration.set_observation_target(\n declination='7d24m25.426s',\n right_ascension='5h55m10.3s'\n)\n```\n\n2. Specify a static location to observe by providing an azimuth and altitude:\n\n```python\nconfiguration.set_observation_target(\n azimuth=24.2,\n altitude=78.1\n)\n```\n\n3. Provide a custom antenna direction path (how to construct a custom path is explained later):\n\n```python\nconfiguration.set_observation_target(\n custom_path=custom_path\n)\n```\n\n#### `set_satellites()`\n\nThe `set_satellites()` method takes the file path of the satellite TLE data and an optional frequency file. The frequency data can be utilized to filter out satellites whose downlink frequency does not overlap with the observation frequency.\n\n\n```python\nconfiguration.set_satellites(\n tle_file='path/to/satellites.tle',\n frequency_file='/path/to/frequency.csv' # optional\n)\n```\n\n#### `set_satellites_filter()`\n\nThere is optionally the ability to filter the satellites list. To do this call the `set_satellites_filter()` method with a `Filterer` object. The `Filterer` object is explained in more detail in the 'Filtering Satellites' section.\n\n```python\nconfiguration.set_satellites_filter(\n filterer=filterer\n)\n```\n\n#### `add_filter()`\n\nAlternatively to constructing a `Filterer` object you can simply call `add_filter()`\n\n```python\nconfiguration.add_filter(filter_frequency(FrequencyRange(10, 10)))\n```\n\n#### `set_runtime_settings()`\n\nThe `set_runtime_settings()` method:\n- Specifies the time resolution for calculating satellite positions in seconds via the `time_continuity_resolution` parameter.\n- Specifies the `concurrency_level` parameter determines the number of parallel jobs during satellite position calculation, optimizing runtime speeds. This value should be not exceed the number of cores on the machine.\n- The `min_altitude` specifies the minimum altitude a satellite must be to be considered above the horizon. Useful for locations with obstructed horizons.\n- Runtime settings are optional, the defaults are: concurrency_level = 1, time_continuity_resolution = 1 and min_altitude = 0.0.\n\n```python\nconfiguration.set_runtime_settings(\n concurrency_level=8,\n time_continuity_resolution=1,\n min_altitude=0.0,\n)\n```\n\n#### `build()`\n\nFinally, once all the required methods have been called use the `build()` method to obtain the `Configuration` object:\n\n```python\nconfiguration = configuration.build()\n```\n\n#### `set_from_config_file()`\n\nThe `set_from_config_file()` method can be used to provide all of the observation characteristics via a JSON configuration file instead of being set programatically.\n\n```python\nconfiguration = (\n ConfigurationBuilder()\n .set_from_config_file(config_file='./supplements/config.json')\n .set_satellites(tle_file='./supplements/satellites.tle')\n .build()\n)\n```\n\nThe JSON config file follows the following format:\n```\n{\n \"facility\": {\n \"beamwidth\": 3,\n \"elevation\": 986,\n \"latitude\": 40.8178049,\n \"longitude\": -121.4695413,\n \"name\": \"HCRO\"\n },\n \"frequencyRange\": {\n \"bandwidth\": 10,\n \"frequency\": 135\n },\n \"observationTarget\": {\n \"declination\": \"-38d6m50.8s\",\n \"rightAscension\": \"4h42m\"\n },\n \"reservationWindow\": {\n \"startTimeUtc\": \"2023-09-27T12:00:00.000000\",\n \"endTimeUtc\": \"2023-09-27T13:00:00.000000\"\n },\n \"runtimeSettings\": {\n \"concurrency_level\": 4,\n \"time_continuity_resolution\": 1,\n \"min_altitude\": 0.0\n }\n}\n```\n\n### Determine Satellite Interference\n\n#### `Sopp`\n\nThe `Sopp` class utilizes the previously created configuration object to identify satellite interference. It is initialized with the `Configuration` obtained from `ConfigurationBuilder`.\n\n```python\nfrom sopp.sopp import Sopp\n\nsopp = Sopp(configuration=configuration)\n```\n\nFinally, obtain the position data of interfering satellites, run either:\n\n- `get_satellites_crossing_main_beam`: Returns satellites that cross the main beam during observation.\n- `get_satellites_above_horizon`: Returns all satellites that are above the horizon during the observation.\n\n```python\ninterference_events = sopp.get_satellites_crossing_main_beam()\n```\n\nThe data is returned as a list of `OverheadWindow`, which is defined as:\n\n```python\nclass OverheadWindow:\n satellite: Satellite\n positions: List[PositionTime]\n```\nThe `Satellite` class, containins details about the satellite and a list of PositionTime objects. The `PositionTime` dataclass specifies the satellite's position in altitude, azimuth and distance in km at a discrete point in time. All times are in UTC.\n\n### Filtering Satellites\n\nThe list of satellites can be filtered by using a `Filterer` object, adding filters to it and then passing the `Filterer` object to a `ConfigurationBuilder`. The user can define any filtering logic wanted, however a few built in filters are provided. If the filtering condition evaluates to `True` the Satellite will be included in the final list.\nIf `None` is passed to any of the filters, no filtering for that specific filter will be applied.\nAlternatively to passing a `Filterer` object to the `ConfigurationBuilder` via `set_satellites_filter`, filters can simply be added with `add_filter(filter_name_contains('STARLINK'))`.\n\nThe provided filters accessible from `sopp.satellites_filter.filters` include:\n\n#### `filter_frequency()`:\n\nParameters:\n - observation_frequency (FrequencyRange): The observation frequency range.\n\nreturns `True` if a satellite's downlink transmission frequency\noverlaps with the desired observation frequency. If there is no information\non the satellite frequency, it will return True to err on the side of caution\nfor potential interference. Requires a `FrequencyRange` object.\n\n#### `filter_name_regex()`:\n\nParameters:\n - regex (str): The regex to match for in the satellite names.\n\nreturns `True` if a given regex matches in the name of a Satellite.\n\nExample: filter_name_regex('YAM|ZARYA') will return a list of satellites that\ncontain YAM or ZARYA within their name.\n\n#### `filter_name_contains()`:\n\nParameters:\n - substring (str): The substring to check for in the satellite names.\n\nreturns `True` if a given substring is present in the name of a Satellite.\n\n#### `filter_name_does_not_contain`:\n\nParameters:\n - substring (str): The substring to check for absence for in the satellite names.\n\nreturns `True` if a given substring is not present in the name of a Satellite.\n\n#### `filter_name_is()`:\n\nParameters:\n - substring (str): The substring to match for in the satellite names.\n\nreturns `True` if a given substring matches exactly the name of a Satellite.\n\n#### `filter_orbit_is(orbit_type)`:\n\nParameters:\n - orbit_type (str): The type of orbit ('leo', 'meo', or 'geo').\n\nif orbit_type='leo' returns Low Earth Orbit (LEO) satellites based on their orbital period.\nThe filter checks if the satellite's orbits per day is >= 5.0\n\nif orbit_type='meo' returns Medium Earth Orbit (MEO) satellites based on their orbital period.\nThe filter checks if the satellite's orbits per day is >= 1.5 and < 5.0\n\nif orbit_type='geo' returns Geostationary Orbit (GEO) satellites based on their orbital period.\nThe filter checks if the satellite's orbits per day is >= 0.85 and < 1.5\n\nFor example, to find all Satellites that are not Starlink, but are in LEO and that have overlapping downlink transmission frequency:\n\n```python\nfrom sopp.satellites_filter.filterer import Filterer\nfrom sopp.satellites_filter.filters import (\n filter_name_does_not_contain,\n filter_orbit_is,\n filter_frequency,\n filter_name_is,\n)\n\nfilterer = (\n Filterer()\n .add_filter(filter_name_does_not_contain('STARLINK'))\n .add_filter(filter_orbit_is(orbit_type='leo'))\n .add_filter(filter_frequency())\n .add_filter(filter_name_is(None)) # this filter will do nothing\n)\n```\n\nUser defined filters can be defined as well. The `add_filter` method takes a lambda. For example, if the user would prefer to define LEO satellites differently than the provided filtering function:\n\n```python\nfilterer = (\n Filterer()\n .add_filter(lambda satellite: satellite.orbital_period <= 100.0)\n)\n```\n\n### Using TleFetcher to Obtain TLE File\n\nA TleFetcher class exists that will automatically fetch the latest TLEs from Celestrak or SpaceTrack:\n\n```python\nfrom sopp.tle_fetcher.tle_fetcher_celestrak import TleFetcherCelestrak\n\nfetcher = TleFetcherCelestrak(tle_file_path='path/to/save/satellites.tle')\nfetcher.fetch_tles()\n```\n\nSpaceTrack is called identically, however you must set the environment variable `IDENTITY` with your username and `PASSWORD` with your password:\n\n```python\nfrom sopp.tle_fetcher.tle_fetcher_spacetrack import TleFetcherSpacetrack\n\nfetcher = TleFetcherSpacetrack(tle_file_path='path/to/save/satellites.tle')\nfetcher.fetch_tles()\n```\n\n### Providing Custom Path for Observation\n\nInstead of specifying an observation target or static observation with altitude and azimuth a custom path can be provided as a list of `PositionTime` objects.\n\n```python\ncustom_path = [\n PositionTime(\n position=Position(altitude=.0, azimuth=.1),\n time=datetime(year=2023, month=3, day=30, hour=10, minute=1, tzinfo=pytz.UTC)\n ),\n PositionTime(\n position=Position(altitude=.1, azimuth=.2),\n time=datetime(year=2023, month=3, day=30, hour=10, minute=2, tzinfo=pytz.UTC)\n ),\n PositionTime(\n position=Position(altitude=.2, azimuth=.2),\n time=datetime(year=2023, month=3, day=30, hour=10, minute=3, tzinfo=pytz.UTC)\n ),\n]\n```\n\n### Example Code\n\n```python\nfrom sopp.sopp import Sopp\nfrom sopp.builder.configuration_builder import ConfigurationBuilder\nfrom sopp.satellites_filter.filters import (\n filter_name_does_not_contain,\n filter_orbit_is,\n)\n\n\ndef main():\n configuration = (\n ConfigurationBuilder()\n .set_facility(\n latitude=40.8178049,\n longitude=-121.4695413,\n elevation=986,\n name='HCRO',\n beamwidth=3,\n )\n .set_frequency_range(\n bandwidth=10,\n frequency=135\n )\n .set_time_window(\n begin='2024-01-18T08:00:00.0',\n end='2024-01-18T08:30:00.0'\n )\n .set_observation_target(\n declination='7d24m25.426s',\n right_ascension='5h55m10.3s'\n )\n .set_runtime_settings(\n concurrency_level=8,\n time_continuity_resolution=1\n )\n # Alternatively set all of the above settings from a config file\n #.set_from_config_file(config_file='./supplements/config.json')\n .set_satellites(tle_file='./supplements/satellites.tle')\n .add_filter(filter_name_does_not_contain('STARLINK'))\n .add_filter(filter_orbit_is(orbit_type='leo'))\n .build()\n )\n\n # Display configuration\n print('\\nFinding satellite interference events for:\\n')\n print(f'Facility: {configuration.reservation.facility.name}')\n print(f'Location: {configuration.reservation.facility.coordinates} at elevation '\n f'{configuration.reservation.facility.elevation}')\n print(f'Reservation start time: {configuration.reservation.time.begin}')\n print(f'Reservation end time: {configuration.reservation.time.end}')\n print(f'Observation frequency: {configuration.reservation.frequency.frequency} MHz')\n\n # Determine Satellite Interference\n sopp = Sopp(configuration=configuration)\n interference_events = sopp.get_satellites_crossing_main_beam()\n\n print('\\n==============================================================\\n')\n print(f'There are {len(interference_events)} satellite interference\\n'\n f'events during the reservation\\n')\n print('==============================================================\\n')\n\n for i, window in enumerate(interference_events, start=1):\n max_alt = max(window.positions, key=lambda pt: pt.position.altitude)\n\n print(f'Satellite interference event #{i}:')\n print(f'Satellite: {window.satellite.name}')\n print(f'Satellite enters view: {window.overhead_time.begin} at '\n f'{window.positions[0].position.azimuth:.2f} '\n f'Distance: {window.positions[0].position.distance_km:.2f} km')\n print(f'Satellite leaves view: {window.overhead_time.end} at '\n f'{window.positions[-1].position.azimuth:.2f} '\n f'Distance: {window.positions[-1].position.distance_km:.2f} km')\n print(f'Satellite maximum altitude: {max_alt.position.altitude:.2f}')\n print('__________________________________________________\\n')\n\n\nif __name__ == '__main__':\n main()\n```\n",
"bugtrack_url": null,
"license": null,
"summary": "SOPP is an open-source tool for calculating satellite interference to radio astronomy observations.",
"version": "0.8.2",
"project_urls": {
"Bug Tracker": "https://github.com/NSF-Swift/satellite-overhead/issues",
"Repository": "https://github.com/NSF-Swift/satellite-overhead"
},
"split_keywords": [
"astronomy",
" satellites"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "c14a86735b391cda2022e332cc410552810df0656f4984c6a72342780ebfc924",
"md5": "7a278baf605d3efd9bfe576ef7347358",
"sha256": "937500cc91432cca781963a87e799179e4bf64b633d1b1b966b494b47cdc4236"
},
"downloads": -1,
"filename": "sopp-0.8.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "7a278baf605d3efd9bfe576ef7347358",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 56976,
"upload_time": "2024-04-18T19:30:55",
"upload_time_iso_8601": "2024-04-18T19:30:55.143519Z",
"url": "https://files.pythonhosted.org/packages/c1/4a/86735b391cda2022e332cc410552810df0656f4984c6a72342780ebfc924/sopp-0.8.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "820031d01051938ea630a465c81602fd16802912de67f0435dd6c6bf2e7b6d83",
"md5": "212089515bfa0d292231c974f0c967af",
"sha256": "88493dbe5be2a48d217c6be739e40949bee8c40ce93df6628ef584647ce12fc1"
},
"downloads": -1,
"filename": "sopp-0.8.2.tar.gz",
"has_sig": false,
"md5_digest": "212089515bfa0d292231c974f0c967af",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 36547,
"upload_time": "2024-04-18T19:30:56",
"upload_time_iso_8601": "2024-04-18T19:30:56.484266Z",
"url": "https://files.pythonhosted.org/packages/82/00/31d01051938ea630a465c81602fd16802912de67f0435dd6c6bf2e7b6d83/sopp-0.8.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-18 19:30:56",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "NSF-Swift",
"github_project": "satellite-overhead",
"github_not_found": true,
"lcname": "sopp"
}
