SOPP - Satellite Orbit Prediction Processor

CI/CD
Docs
Package

SOPP is a high-performance Python library and CLI tool designed to predict satellite interference for radio astronomy observations.

It uses vectorized orbital mechanics (via Skyfield/SGP4) to simulate thousands of satellites against observation schedules, identifying when a satellite crosses a telescope's main beam or rises above the horizon.

Installation

Install via pip:

# Core library only
pip install sopp

# With CLI tools
pip install "sopp[cli]"

CLI Usage

SOPP provides a command-line interface for running simulations and managing data.

1. Download Data

First, download the latest satellite orbital data. By default, this pulls active satellites from Celestrak in OMM CSV format.

sopp download-tles

Other formats are available with --format (csv, json, xml, tle). Note that the legacy TLE format cannot represent NORAD IDs above 99999, so it omits every satellite cataloged since July 2026 (see Celestrak's GP data formats page).

2. Run a Simulation

Run a simulation using a configuration file (see below).

sopp run --config my_config.json

3. Ad-Hoc Analysis

You can override configuration parameters directly from the CLI without editing the file.

# Check for Starlink interference in the next 30 minutes
sopp run --config my_config.json \
    --search STARLINK \
    --orbit leo \
    --start 2025-01-01T12:00:00 \
    --duration 30

Common Options:

• --mode [all|horizon|interference]: Choose what to calculate.
• --limit 10: Only show the first 10 results.
• --local-time: Display timestamps in your system's local timezone.
• --format json: Output machine-readable JSON.

Configuration

SOPP uses a JSON configuration file to define the observation parameters.

Example config.json

{
  "facility": {
    "name": "HCRO",
    "latitude": 40.8178049,
    "longitude": -121.4695413,
    "elevation": 986,
    "beamwidth": 3.0
  },
  "frequencyRange": {
    "frequency": 135.0,
    "bandwidth": 10.0
  },
  "reservationWindow": {
    "startTimeUtc": "2026-01-13T12:00:00",
    "endTimeUtc": "2026-01-13T13:00:00"
  },
  "observationTarget": {
    "declination": "-38d6m50.8s",
    "rightAscension": "4h42m"
  },
  "runtimeSettings": {
    "concurrency_level": 4,
    "time_resolution_seconds": 1.0,
    "min_altitude": 0.0
  }
}

Configuration Sections

Antenna Pointing Modes

You must provide one of the following sections to define where the antenna is pointing:

1. observationTarget: Tracks a celestial object (RA/Dec).

   "observationTarget": { "declination": "...", "rightAscension": "..." }
   

2. staticAntennaPosition: Points at a fixed Azimuth/Elevation.

   "staticAntennaPosition": { "azimuth": 180.0, "altitude": 45.0 }
   

3. antennaPositionTimes: A custom trajectory (list of time/az/el points).

Python Library Usage

SOPP is designed to be imported and used directly in Python scripts/projects.

from sopp.config.builder import ConfigurationBuilder
from sopp.filtering.presets import filter_name_does_not_contain
from sopp.models.ground.receiver import Receiver
from sopp.sopp import Sopp

# Build Configuration
config = (
    ConfigurationBuilder()
    .set_facility(
        latitude=40.8,
        longitude=-121.4,
        elevation=986,
        name="HCRO",
        receiver=Receiver(beamwidth=3),
    )
    .set_runtime_settings(concurrency_level=4)
    .set_time_window(begin="2026-01-13T19:00:00", end="2026-01-13T20:00:00")
    .set_frequency_range(bandwidth=10, frequency=135)
    # Cygnus A
    .set_observation_target(declination="40d44m", right_ascension="19h59m")
    .load_satellites(tle_file="satellites.csv")
    .add_filter(filter_name_does_not_contain("STARLINK"))
    .build()
)

print(f"Running interference simulation for {len(config.satellites)} satellites:")

# Run Engine
engine = Sopp(config)
interference_events = engine.get_satellites_crossing_main_beam()

# Analyze Results
print(f"Found {len(interference_events)} interference events:")

for event in interference_events:
    print(f"--- {event.satellite.name} ---")
    print(f"  Window:   {event.overhead_time.begin} -> {event.overhead_time.end}")
    print(f"  Duration: {event.duration_seconds:.1f} seconds")
    print(f"  Peak Elev: {event.peak_elevation:.1f} deg")

Data Sources

• Orbital Data: OMM (csv/json/xml) or TLE, sourced from Celestrak (public) or Space-Track.org (requires account/env vars).
• Frequency Data: Optional CSV file to populate satellite transmission frequency. SSDB Format: ID, Name, Frequency, Bandwidth.