Satellite Simulator - Connor-bett-swin/i54SatelliteSwarms GitHub Wiki

Documentation for Satellite Simulator (SatSim)

Overview

Using TLE (Two-Line Element set) data, the Satellite Simulator (SatSim) offers a framework for simulating satellite positions that may be handled in both CLI (Command Line Interface) and GUI (Graphical User Interface) modes. Using a given timeframe, Sat-sim generates adjacency matrices to analyse satellite configurations. It provides network graph PDF and csv or txt output formats for additional analysis.

Architecture

SatSim have several Python modules. Each module handle specific part that of the simulation process.

sat_sim_config.py

This file manages configuration settings for SatSim by reading and applying them from a JSON file, ensuring input validation (such as timestamps, timestep, and output file type).

Key Methods:

  • _convert_to_timestamp(): converts datetime strings into time objects compatible with Skyfield.
  • set_gui_enabled(): Enables/disables GUI mode.
  • read_options(): reads and verifies user parameters, including start time, end time, timestep, and output type, from a JSON file or input choices.
  • read_options_from_file(): reads and loads options from a JSON file.

How it works: Before sending the parameters to the main sat_sim.py logic, the configurations verifies the start and end times, timestep, and other settings.

sat_sim_handler.py

This handler file uses the processed TLE data into the main logic of the simulation by handling it from files or direct inputs.

Key Methods:

• parse_file(): sends TLE data to the SatSim module after reading it from a file and making sure it hasn't been loaded before.

• parse_data(): Handles direct input of TLE data (rather than reading from a file) and sends it to SatSim.

• send_data(): ensures that the SatSim instance has been initialized before sending the processed TLE data there.

• run_module(): Run() function from SatSim module is executed.

• read_tle_file():checks that each satellite has precisely three lines of data—the name, line 1, and line 2—by reading the real TLE data from a file.

sat_sim_output.py

The output of the simulation results is handled by this file, which writes adjacency matrices to CSV or text files.

Key Methods:

• write_to_file(): Writes matrices to a text file. It includes a timestamp for each matrix and skips writing empty matrices. The numpy.savetxt() function is used to save the matrix contents.

• write_to_csv(): writes matrices to a CSV file along with the timestamps that correspond to them. It contains the matrix itself, the timestamp, and the size of the matrix. Additionally, this method makes sure that matrix sizes are consistent and that empty matrices are skipped.

• set_fl_input() and get_result():Potentially utilized for interactivity with other modules (e.g., Federated Learning), placeholder ways for setting and receiving results.

sat_sim_gui.py

The sat_sim_gui.py file introduces a graphical user interface (GUI) for the Satellite Simulator using PyQt5, VTK for 3D visualization, matplotlib for adjacency matrix visualization, and networkx for network graph plotting.

Key Methods:

  1. Initialization (init):

  • Sets up the GUI, loading initial values from the sat_sim_instance.

  • Verifies that the TLE data is loaded and initializes the visual components.

  1. UI Setup (initUI):

o Creates and lays out the visual elements:

  • VTK widget for 3D satellite visualization.

  • Labels for displaying satellite positions and distances.

  • Matplotlib to display adjacency matrices and network graphs.

  • QLineEdit for user inputs (start time, end time, and timestep).

  • QSlider to control the simulation time between the start and end times.

  • QPushButton for updating orbits and saving data.

  1. Update Functions:

  • update_orbit():Updates adjacency matrices and distances after receiving updated satellite positions.

  • update_visualization(time): based on the current time, updates the adjacency matrix, network graph, satellite positions, and distances.

  • plot_orbits(): Uses VTK to render satellites in 3D as spheres.

  • update_positions() and update_distances(): Update the position and distance labels based on the current satellite positions.

  • update_graphs(): Plots the adjacency matrix and network graph using matplotlib and networkx.

Saving Functions:

  • save_adj_matrix_for_specified_timeframe():saves the network graphs and adjacency matrix to a text file and a PDF file for a user-specified period of time.

sat_sim.py

This core module coordinates the simulation process. Using TLE data, it calculates satellite positions with the Skyfield library, which models satellite trajectories in geocentric coordinates. The module periodically steps through the simulation timeframe, generating adjacency matrices by calculating the pairwise distances between satellites. It determines which satellites are within a specified threshold distance, marking connections in the matrix. The primary methods involved are get_satellite_positions(), which interfaces with Skyfield’s EarthSatellite class, and generate_adjacency_matrix(), which computes distance-based relationships.

Key Components:

  1. Initialization (init):
  • Initializes the SatSim instance with optional parameters such as start and end times, timestep, output file type, and GUI mode. It ensures that the times are valid and handles TLE data loading.
  1. Simulation Setup Methods:

  • set_gui_enabled(): Enables or disables GUI mode.

  • set_tle_data(): Sets the TLE data for the simulation.

  • set_timestep(): Adjusts the timestep between simulation frames.

  • set_start_end_times(): Defines the start and end times of the simulation.

  • set_output_file_type(): Specifies the output format (either CSV or text).

  1. Running the Simulation:

  • run_gui(): Launches the satellite simulation in GUI mode using PyQt5. It invokes the GUI created in sat_sim_gui.py.

  • run_with_adj_matrix(): Executes the simulation in CLI mode. It calculates satellite positions over the defined timeframe, generates adjacency matrices, and saves the results to a file (either CSV or text). This function loops through the timespan using the specified timestep.

  1. Satellite Position Calculation:
  • get_satellite_positions(): Retrieves the positions of satellites at a given time by parsing the TLE data using Skyfield. It returns the calculated positions in kilometers.
  1. Distance Calculation:
  • calculate_distance(): calculates the Euclidean distance in space between two satellite positions.
  1. Adjacency Matrix Generation:
  • generate_adjacency_matrix(): compares the distances between satellite positions to generate an adjacency matrix. In the adjacency matrix, a connection is established if the distance between two satellites is less than a predetermined threshold, which is 10,000 km by default.
  1. File Writing:
  • run_with_adj_matrix(): This method uses the SatSimOutput class to write the results to a text file or CSV file after generating the adjacency matrices.
  1. Main run() Function:
  • Depending on the mode (GUI or CLI), this function runs the appropriate simulation. In GUI mode, it launches the interactive interface, while in CLI mode, it runs the matrix generation and saves results to files.

Input/Output (I/O)

Inputs:

  • TLE data files with satellite details specified

  • Configuration parameters, such as simulation start time, end time, timestep can be entered directly by the user or using JSON files.

Outputs:

  • Text or CSV files containing timestamps and adjacency matrices.

  • The GUI mode shows real-time satellite positions, adjacency matrices, and the distance between each satellite

  • The network graph pdf and visualization are available in GUI form for the specified period of time.

CSV Output: The CSV output will contain timestamps and the corresponding adjacency matrices. Each row represents the distance-based connection between satellites, with 1 indicating a connection and 0 indicating no connection.

TXT Output: In the text output format, each adjacency matrix is printed in a human-readable format, with timestamps before each matrix.

Caveats and Constraints

TLE File Format:

  • The TLE file must follow the standard NASA format, which consists of three lines per satellite:

  • Satellite name (optional but expected to be the first line).

  • Line 1: The first line of orbital elements, containing satellite data such as epoch, inclination, and RAAN.

  • Line 2: The second line of orbital elements, containing elements like eccentricity, argument of perigee, mean anomaly, etc. Any deviation from this format (e.g., missing lines or incorrect field lengths) will result in parsing errors. Ensure that all satellites in the file have both orbital element lines.

Time Inputs: Start and end times must be provided in UTC (YYYY-MM-DD HH:MM ) format. The timestep should be specified in minutes. Ground Station: Optionally, users can specify a ground station location with latitude and longitude in decimal degrees.

Simulation Logic

SatSim calculates satellite positions using Skyfield, which processes TLE data (orbital elements) and converts it into geocentric coordinates. The simulation progresses in discrete timesteps, where satellite positions are recalculated at each interval. Each timestep represents the time interval (in minutes) between successive satellite position calculations, allowing the system to model satellite movement dynamically over time.

At each timestep:

  • Satellite positions are recalculated using the Skyfield EarthSatellite class based on the current timestamp. Skyfield converts TLE data into satellite objects. At each timestep, Skyfield is used to compute the satellite’s position in Earth-centered inertial coordinates.

  • The system generates an adjacency matrix, which records the distance between each pair of satellites. If the distance is below a predefined threshold (e.g., 10,000 km), the satellites are considered connected, and the matrix is updated to reflect this.

  • Adjacency Matrix Calculation: The adjacency matrix represents the distance between each pair of satellites. A value of 1 in the matrix means the satellites are close enough to be considered connected (within a predefined distance threshold).

  • Timesteps are defined in the configuration file and can be adjusted depending on the required precision and the duration of the simulation.

Platform Limitations:

Operating System: While the system is cross-platform, the GUI implementation relies on PyQt5, which may require specific setup on different operating systems. It is recommended to use Python 3.8 or higher and ensure all dependencies (PyQt5, Skyfield, VTK, etc.) are installed via the requirements.txt file.

Example Installation Command:

pip install -r requirements.txt

User Input Arguments

The simulator can receive arguments via GUI interactions or command-line interfaces:

GUI Inputs:

  • Selecting a TLE file via the file dialog.

  • Input of the start time, end time, and timestep via interactive fields

  • Buttons to update orbits, Save Adjacency Matrix & Network Graphs for Specified Timeframe

CLI Arguments:

  • --sat-sim-only: Runs the satellite simulation standalone without engaging other system components.
  • --gui: Forces the simulator to start in GUI mode, overriding JSON settings if necessary.
  • TLE file path: Path to the TLE data file used for simulation.

Command to run the sat-sim standalone:

python main.py flomps TLE file path --sat-sim-only

The cli version is executed when gui enable is set to false, and the gui version is executed when it is set to true.

However, this command, python main.py, flomps the TLE file path --sat-sim-only –gui, sets the trigger to be true if it was false, and launches the gui version.

Example Scenario:

To run a simulation using the CLI mode:

  1. Provide the TLE file (e.g., example.tle) formatted according to the NASA TLE standard.

  2. Set the start time to 2024-01-01 00:00:00 and end time to 2024-01-01 02:00:00 in the JSON configuration or command line.

  3. Set the timestep to 10 minutes.

  4. Run the command: python main.py flomps TLE file path --sat-sim-only

  5. The system will output a CSV file with adjacency matrices for each 10-minute interval.

An adjacency matrix will be generated for each of the ten minutes that a satellite position is calculated, assuming a timestep of ten minutes. With a 10-minute timestep, a simulation that starts at 00:00 UTC and ends at 02:00 UTC will trigger the system to calculate positions and produce matrices for 00:00, 00:10, 00:20, and on and on, up to 02:00.

Customization and Extension

• Configuration Adjustments:

o Users can set simulation parameters such as start time, end time, timestep, and output preferences directly in the options.json file or in command line or through GUI interface.

• Module Customization:To extend the functionality of the system, developers can modify or add output formats in sat_sim_output.py. For example, to include JSON as an output option, you would:

o Navigate to the write_to_file() method in sat_sim_output.py.

o Add a conditional block that checks if the selected output format is JSON.

o Use Python’s built-in json library to format the adjacency matrices and timestamps as a JSON object and write it to a file.

o Additionally, to support a new data source such as a custom satellite catalog, modify the read_tle_file() method in sat_sim_handler.py to parse a different file format.

Maintenance Guide

  • Code Structure: Keep the separation of functions as defined: output file handles the output, sat_sim_config.py handles configuration management, and sat_sim_handler.py handles data handling. gives access to a Core module and graphical user interface for controlling the simulation.

  • Updating Dependencies: To reduce security risks and guarantee compatibility, update the dependencies specified in the requirements file on a regular basis.

  • Testing: Conduct integration tests for the simulation's end-to-end testing and unit tests for each module to verify its specific functionality.