Propagation#

Overview#

If you would prefer to delegate propagation of ephemeris to Satcat, you can use the propagation features of the Satcat SDK. Satcat will generate a predictive ephemeris based on the epoch state produced by your Orbit Determination software using a high fidelity numerical propagator.

Note

Additional configuration options for propagation will be added in future releases of the Satcat SDK.

The Propagation Resource#

Similar to Screening, the SDK introduces the Propagation resource, which can be created using create_propagation. For example:

...
from satcat.sdk.propagation.models import PropagationConfiguration
config = PropagationConfiguration(target_duration=86400, timestep=60)
propagation = client.propagation.create_propagation(config)

Note

The config parameter of create_propagation is optional. If unspecified, a default configuration will be generated, with target_duration set to 5 days and timestep set to 60 seconds.

Much like screenings, propagations are also asynchronous jobs which are run on Satcat’s servers. They can be submitted using submit_propagation and awaited using await_propagation_completion. You can also use the submit parameter of create_propagation to automatically submit the propagation upon creation, if it has been fully configured using the other parameters of create_propagation.

CCSDS Orbit Parameter Message (OPM)#

The Satcat SDK supports configuring propagations using the CCSDS Orbit Parameter Message (OPM) file format. This file format allows you to specify your spacecraft’s state vector, covariance, physical quantities such as mass, and optionally any maneuvers that you wish to generate a predictive ephemeris from. For more information on the CCSDS OPM file format, see the CCSDS Orbit Data Messages Blue Book. The Satcat platform references the CCSDS 502.0-B-2 version of the CCSDS Blue Book document.

To create a propagation based on an OPM, you can use the opm_file parameter of create_propagation. For example:

propagation = client.propagation.create_propagation(opm_file="USER_OPM_FILE.txt")

Creating a propagation from an OPM file has the following implications:

  • The initial state of the propagation is set to the state vector supplied in the OPM.

  • If a covariance matrix is specified in the OPM, the initial covariance of the propagation is set to the covariance matrix supplied in the OPM.

  • If any maneuvers are specified in the OPM, the maneuvers are added to the propagation.

  • If the spacecraft parameters section is present in the OPM, this information is added to the propagation.

  • If the propagation does not already contain a value for start_time, the epoch of the state vector is set as the propagation’s start_time.

Warning

As per CCSDS 502.0-B-2 3.2.4.9, the spacecraft parameters section must be supplied if the OPM contains maneuvers. Additionally, as per sections 3.2.4.5 & 3.2.4.6, drag and solar radiation pressure forces are only taken into account if the values for drag and SRP coefficient supplied in the OPM are nonzero.

These settings have a large impact on the trajectory of a spacecraft, particularly in low earth orbit. To ensure the fidelity of the resulting predictive ephemeris, the Satcat SDK requires the Spacecraft Parameters section of the OPM, even if the file contains no maneuvers.

Please take care to supply the best possible estimates for the values in the Spacecraft Parameters section when supplying an OPM for propagation.

Screening using Propagations#

The Screening module of the SDK supports using Propagations to screen natively. To use a propagation in a screening, you can pass the Propagation object in either the primaries or secondaries list to create_screening. For example:

...
propagation = client.propagation.create_propagation(opm_file="USER_OPM_FILE.txt")
screening = client.screening.create_screening(
    primaries=[propagation],
    add_best_secondary_catalog=True,
    submit=True
)

Note

If a propagation is added as a primary or secondary to a screening, it is automatically submitted and processed when the screening is submitted. You do not need to manually submit or await a propagation that is attached to a screening as a primary or secondary; you may simply create the propagation, configure it, attach it to the screening, and submit the screening.

Satcat will automatically process all propagations on which the screening depends and use the resulting ephemerides during screening processing.

Downloading the Ephemeris Results of a Propagation#

You can also download the result content of a propagation as an ephemeris file using the ephemeris file download feature.

For example, to create and run a propagation using an OPM file and download the results as an OEM ephemeris file:

# Create the propagation, configure using an OPM file, and submit for processing
propagation = client.propagation.create_propagation(opm_file="USER_OPM_FILE.txt", submit=True)

# Await completion of the propagation
propagation = client.propagation.await_propagation_completion(propagation)

# Download the results of the propagation as an OEM-formatted ephemeris file
ephemeris_content = client.screening.download_ephemeris(propagation.ephemeris_id, file_format="OEM")

# Read the contents of the ephemeris file and print the content of the file to stdout
print(ephemeris_content.read())