Satellites#

Satellite classes are used to locate the position of a platform for a variety of orbits. They are derived from class PlatformLocation which allows them to be used as platform locators in class Platform when coupled with the from_platform positioning technique.

Example:

from skplatform import Platform

def make_geometry():
    kepler = SatelliteKepler('2020-09-24T12:00:00.000000', period_from_altitude = 600000.0, inclination_radians= radians(97.0), longitude_of_ascending_node_degrees = 82.0, eccentricity= 0.05)
    platform = Platform(platform_locator=kepler)
    utc  = ['2020-09-24T12:15:36.123456', '2020-09-24T12:15:37.456123', '2020-09-24T12:15:38.654321', '2020-09-24T12:15:39.654321']
    pointing_values = [(35000, 10, 0), (27000, 5, 0), (24000, 0, 0), (21000, -5, 0)]
    platform.add_measurement_set(utc, ('from_platform',), ('tangent_altitude', 'limb', pointing_values))

The satellite classes can also be used as stand-alone classes in which case the user would execute the following steps.

Create a specific instance of a satellite.
Update the satellite position to a given instant in time, see update_position
Get the satellite position using one of the available methods, see position, earth_location or lat_lon_height
Repeat steps 2 and 3.

for example:

dt = timedelta(minutes=1.0)                                         # step time of our simulation is one minute
numtimes = 1440                                                     # Simulate for 1 day = 1440 * one minute
platform_utc = datetime(2019,7,26, hour =20, minute=15, second=00)  # start time of our simulation
sat = SatelliteSunSync(platform_utc,                                # Create the satellite
                       orbittype='sgp4',
                       period_from_altitude=600000.0,
                       localtime_of_ascending_node_hours=18.25)

answers = np.zeros([3, numtimes])                                   # make an array to hold the latitude, longitude, altitude of each satellite at each simulation step
times = np.zeros([numtimes], dtype='datetime64[us]')                # make an array to hold the UTC time of each simulation step.
for i in range(numtimes):                                           # for each time step
    tnow = platform_utc + i * dt                                    # get the next time step
    times[i] = tnow                                                 # save the time of the step
    sat.update_position(tnow)                                       # Update the satellite position
    answers[:, i] = sat.lat_long_height                             # convert XYZ position and save

Users should be aware the satellite classes may internally implement numerical integration using Runge-Kutta algorithms and should avoid large time steps (e.g. multiple orbits) as this may result in long execution times in the best case and inaccuracy in the worst case.

Satellite Propagators#

SatelliteKepler#

Implements a classic Kepler orbit which generates elliptical orbits with the centre of the Earth located at one focus. This is quick and fast but keep in mind that it has no gravitational perturbations so it can never truly mimic sun-synchronous or other classes of orbit that depend up gravitional torques etc.

Example:

from skplatform.satellite  import SatelliteKepler

kepler  = SatelliteKepler ( platform_utc, period_from_altitude = 600000.0, inclination_radians= radians(97.0), longitude_of_ascending_node_degrees = 82.0, eccentricity= 0.05)
pos = kepler.update_position( tnew )

class SatelliteKepler(utc: datetime64 | datetime | float | str = None, period_from_seconds: float = None, period_from_altitude: float = None, period_from_semi_major_axis: float = None, inclination_radians: float = None, inclination_is_sun_sync: bool = False, mean_anomaly: float = 0.0, argument_of_perigee: float = 0.0, localtime_of_ascending_node_hours: float = None, longitude_of_ascending_node_degrees: float = None, right_ascension_ascending_node: float = None, eccentricity: float = 1e-07, orbitnumber: int = 0)[source]#

Attributes:

earth_location: Returns the current position of the platform as an Astropy EarthLocation.
lat_lon_height: Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters.
position: Returns the position of the satellite in meters in the geocentric geographic ECEF coordinate system.
time: Returns the UTC time of the current state vector
velocity: ECEFITRF/GEO coordinate system.

Methods

`eccentricity`()	Returns the eccentricity of the orbit ( 0.0 to 1.0)
`eciposition`()	The ECI cartesian position of the satellite in meters after the last call to `update_eci_position`.
`ecivelocity`()	The ECI cartesian velocity of the satellite in meters per second
`equator_crossing`(utc)	Determines the last equator crossing before or equal to Tnow.
`from_classical_orbital_elements`(utc, elements)	Update this Kepler object so its orbit follows the values given in the Classical Orbital Elements structure.
`from_elements`(autc[, period_from_seconds, ...])	Define the Kepler orbit from the classic 6 Keplerian ali_elements.
`from_state_vector`(utc, r, v[, orbitnumber])	Update the Kepler object so it follows the orbit defined by the position and velocity state vector.
`from_three_positions`(utc2, r1, r2, r3[, ...])	Determine the orbital ali_elements from three position vectors andUpdate the Kepler object so it follows the calculates orbits derived from the specified state vector
`make_two_line_elements`([first_derivative, ...])	Returns the current orbital ali_elements as two line ali_elements.
`orbit_number`(utc)	Calculates the orbit number at time Tnow and returns the start time
`period`()	Return the orbital period of this orbit.
`set_orbit_number_from_last_equator_crossing`(...)	Sets the orbit number and calculates the start time/ascending node of the orbit.
`sun_synchronous_inclination`(...)	Method that returns the inclination of a sun synchronous orbit given the semi-major axis.
`true_anomaly_to_mean_anomaly`(nu, e)	Converts True anomaly, \(\nu\), to mean anomaly, \(M\) by first calculating the eccentric anomaly, \(E\) using the formula,
`update_eci_position`(ut)	Updates the internal ECI position to the given time
`update_orientation`(utc)	Returns a platform orientation that has no modification.
`update_position`(utc)	Overloads the methods from `PlatformLocation`.
`update_velocity`(utc)	Overloads the method from `PlatformLocation`.

__init__(utc: datetime64 | datetime | float | str = None, period_from_seconds: float = None, period_from_altitude: float = None, period_from_semi_major_axis: float = None, inclination_radians: float = None, inclination_is_sun_sync: bool = False, mean_anomaly: float = 0.0, argument_of_perigee: float = 0.0, localtime_of_ascending_node_hours: float = None, longitude_of_ascending_node_degrees: float = None, right_ascension_ascending_node: float = None, eccentricity: float = 1e-07, orbitnumber: int = 0)[source]#

Implements a simple Kepler orbit around the Earth. Multiple options are provided to describe the required orbit. A complete description of the various parameters is given in from_elements

Parameters:

utc – option identical to that described in from_elements
period_from_seconds – keyword option identical to that described in from_elements
period_from_altitude – keyword option identical to that described in from_elements
period_from_semi_major_axis – keyword option identical to that described in from_elements
inclination_radians – keyword option identical to that described in from_elements
inclination_is_sun_sync – keyword option identical to that described in from_elements
mean_anomaly – keyword option identical to that described in from_elements
true_anomaly – keyword option identical to that described in from_elements
argument_of_perigee – keyword option identical to that described in from_elements
localtime_of_ascending_node_hours – keyword option identical to that described in from_elements
longitude_of_ascending_node_degrees – keyword option identical to that described in from_elements
right_ascension_ascending_node – keyword option identical to that described in from_elements
eccentricity – keyword option identical to that described in from_elements
orbitnumber – keyword option identical to that described in from_elements

eccentricity() → float[source]#: Returns the eccentricity of the orbit ( 0.0 to 1.0)

from_classical_orbital_elements(utc: datetime | datetime64 | float | str, elements: ClassicalOrbitalElements, orbitnumber: int = 0)[source]#

Update this Kepler object so its orbit follows the values given in the Classical Orbital Elements structure.

Parameters:

utc: datetime, np.datetime64, float, str: The time of the ali_elements
elements: ClassicalOrbitalElements: The structure of classical orbital ali_elements
orbitnumber: int: Set the orbit number to this value, default 0.

from_elements(autc: datetime, period_from_seconds: float = None, period_from_altitude: float = None, period_from_semi_major_axis: float = None, inclination_radians: float = None, inclination_is_sun_sync: bool = False, mean_anomaly: float = 0.0, argument_of_perigee: float = 0.0, localtime_of_ascending_node_hours: float = None, longitude_of_ascending_node_degrees: float = None, right_ascension_ascending_node: float = None, eccentricity: float = 1e-07, orbitnumber: int = 0)[source]#

Define the Kepler orbit from the classic 6 Keplerian ali_elements.

period
inclination
eccentricity
mean anomaly
right ascension of ascending node
argument of perigee

Several of the orbital ali_elements can be specified in multiple ways. For example the orbital period can be defined directly with seconds or it can be defined using the altitude of the satellite. You must use only one of the options to specify a parameter otherwise exceptions will/should be raised.

The caller must ensure that they explictly set the following three orbital ali_elements,

period or altitude must be set.
inclination must be set.
right ascension of the ascending node must be set.

Leaving the remaining three ali_elements, (i) mean anomaly, (ii) argument of perigee and (iii) eccentricity as default values produces a circular orbit with the satellite initially placed at the location of the perigee (which for a circular orbit is somewhat undefined and arbitrary!).

Parameters:

platform_utc: datetime.datetime: The UTC time of the ali_elements
period_from_secondsfloat: specifies the orbital period in seconds. An alternative to specify the period is with the optional parameter period_from_altitude or period_from_semi_major_axis. One, but only one, of the three methods must be used.
period_from_altitudefloat: specifies the orbital period using the altitude of the satellite in meters. The altitude is nominal as we do not account for oblateness of the Earth etc. The radius of the Earth is internally assumed to be 6378000.0 meters. An alternative to specify the period is with the optional parameter period_from_seconds or period_from_semi_major_axis. One, but only one, of the three optional methods must be used.
period_from_semi_major_axisfloat: specifies the orbital period using the semi_major axis of the satellite in meters. An alternative method to specify the period is with the optional parameter period_from_seconds or period_from_altitude. One, but only one, of the three methods must be used.
inclination_radiansfloat: Specifes the inclination of the orbit in radians. An alternative method to specify the inclination is with the optional parameter inclination_is_sun_sync. One, but only one, of the two optional methods must be used.
inclination_is_sun_syncbool: Default False. If True then specify the inclination of the orbit so it is sun-synchronous. This only works for orbits below an altitude of ~5974 km,. An alternative is to specify the inclination with the optional parameter inclination_radians. One, but only one, of the two optional methods may be used. Note this only sets the inclination of the orbit as a Kepler orbit propagator does not have the oblate Earth model (J2) necessary to model sun synchronicity.
localtime_of_ascending_node_hours: float: Default: None. Specifies the nominal local time of the ascending node in hours (0-24). If set then its value represents the “hour” at which you want the ascending node for example a floating point value of 18.25 will set the node to 18:15 LT. This value is implemented by overwriting the “longitude_of_ascending_node_degrees” keyword used to initialize the kepler orbit. It also forces the satellite to be close to the ascending node at time platform_utc by changing the mean_anomaly value. Default is None.
longitude_of_ascending_node_degrees: float: Default None. Specifies the geographic longitude of the ascending node (-180 to 360)at time platform_utc. This is an alternative method to using parameters localtime_of_ascending_node_hours and right_ascension_ascending_node to specify the right ascension of the ascending node. One, but only one, of the 3 optional methods may be used, if neither option is used the RAAN is set to 0.0. If this option is used then the satellite is forced to be close to the ascending node at time platform_utc by changing the mean_anomaly value. Note that longitude is in degrees not radians.
right_ascension_ascending_node: float: Default None. Specifies the Right Ascension of the ascending node in radians (0 to 2.pi). This is an alternative method to parameter longitude_of_ascending_node_degrees to specify the right ascension of the ascending node. One, but only one, of the two optional methods must be used, if neither option is used the RAAN is set to 0.0.
mean_anomaly: float: The mean anomaly in radians at time mjd (0-2.pi). This value will be overidden if you use options localtime_of_ascending_node_hours or longitude_of_ascending_node_degrees.
argument_of_perigee: float: Default 0. The argument of perigree in radians (0 to 2.pi).
eccentricity: float: Default 0. The eccentricity of the orbit (0 to 1)
orbitnumber: int: Default 0. The orbit number at the epoch givern by mjd

from_state_vector(utc: datetime | datetime64 | float | str, r: ndarray, v: ndarray, orbitnumber: int = 0)[source]#

Update the Kepler object so it follows the orbit defined by the position and velocity state vector.

Parameters:

utc: datetime, np.datetime64, float, str: The coordinated universal time of the state vector.
r:np.ndarray [3]: The ECI position of the satellite in meters
v:np.ndarray[3]: The ECI velocity of the satellite in m/s
orbitnumber: int: The orbit number at the epoch, default 0

from_three_positions(utc2: datetime, r1: ndarray, r2: ndarray, r3: ndarray, orbitnumber: int = 0)[source]#

Determine the orbital ali_elements from three position vectors andUpdate the Kepler object so it follows the calculates orbits derived from the specified state vector

Parameters:

utc2: datetime, np.datetime64, float, str: The coordinated universal time of the second point.
r1:np.ndarray [3]: The fiirst ECI position of the satelite in meters
r2:np.ndarray [3]: ECI coordinates at epoch (in metres) eciposition of the satellite
r3:np.ndarray [3]: ECI coordinates at epoch (in metres) eciposition of the satellite
orbitnumber: int: The orbit number at the epoch

make_two_line_elements(first_derivative=0.0, second_derivative=0.0, bstar=0.0, satnum=1) → Tuple[str, str][source]#

Returns the current orbital ali_elements as two line ali_elements. This is handy if you want to initialize an SGP4 predictor from a Kepler “starter orbit” using two line ali_elements. The kepler orbit does not directly support drag terms, these have to be provided via the bstar parameter.

Parameters:

first_derivative: float: The first derivative term of the SGP4 two line ali_elements. This is usually not used and can be left as the default value of 0.0
second_derivative: float: The second derivative term of the SGP4 two line ali_elements. This is usually not used and can be left as the default value of 0.0
bstar: float: The drag term used by SGP4. It is usually entered from empirical measurements. A value of 0.0 should disable drag terms in the SGP4 propagator
satnum: int: The satellite number. This is provide for convenience

Returns:

Tuple(str,str): Returns the two lines of the ali_elements as a two element tuple of two strings

period() → timedelta[source]#

Return the orbital period of this orbit. Uses keplers third law.

Returns:

datetime.timedelta: The orbital period as a timedelta. Use timedelta method total_seconds() to get the period in seconds.

sun_synchronous_inclination(semi_major_axis_meters: float) → float[source]#

Method that returns the inclination of a sun synchronous orbit given the semi-major axis. For reference see Sun-Synchronous orbit

Parameters:

semi_major_axis_meters: float

Returns:

float: The required inclination of the orbit in radians

static true_anomaly_to_mean_anomaly(nu: float, e: float) → float[source]#

Converts True anomaly, \(\nu\), to mean anomaly, \(M\) by first calculating the eccentric anomaly, \(E\) using the formula,

\[\tan \frac{\nu}{2} = \sqrt{\frac{1+e}{1-e}}\tan\frac{E}{2}\]

and then calculating the mean anomaly with

\[M = E -e\,\sin E\]

Parameters:

nufloat: True anomaly in radians
efloat: eccentricity

Returns:

float: Mean anomaly in radians

update_eci_position(ut: datetime64 | datetime)[source]#

Updates the internal ECI position to the given time

Parameters:

ut: datetime, np.datetime64, float, str: The time at which the new position is required.

SatelliteSGP4#

A satellite class that uses the SGP4 satellite propagation model implemented in python package sgp4. The classic usage is to initialize the code with two line elements that you have obtained from Space Trak or Celestrak or elsewhere. Example using two line elements:

platform_utc     = datetime(2019,7,26, hour =20, minute=15, second=00)

line1   = "1 26702U 01007A   19206.65122582  .00000348  00000-0  26798-4 0  9995"
line2   = "2 26702  97.5720 223.8268 0009640 316.2599  43.7864 15.07871693  7426"
sgp4    = SatelliteSGP4   ( twolines= [line1,line2] )

The class also provides the option to initialize the SGP4 propagator with the state vector and orbital parameters from a Kepler orbit. This feature is used to implement some of the other satellite classes (eg sun-sync) in skretrieval and provides a convenient way to use the gravitational perturbations in the SGP4 model without needing a set of two line elements.

class SatelliteSGP4(twolines: Tuple[str, str] = None)[source]#

Implements the SGP4 satellite propagator. This is just a shallow wrapper for the SGP4 python package from PyPi

Attributes:

earth_location: Returns the current position of the platform as an Astropy EarthLocation.
lat_lon_height: Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters.
position: Returns the position of the satellite in meters in the geocentric geographic ECEF coordinate system.
time: Returns the UTC time of the current state vector
velocity: ECEFITRF/GEO coordinate system.

Methods

`eccentricity`()	Purely abstract method that returns the eccentricty of the satellite orbit.
`eciposition`()	The ECI cartesian position of the satellite in meters after the last call to `update_eci_position`.
`ecivelocity`()	The ECI cartesian velocity of the satellite in meters per second
`equator_crossing`(utc)	Determines the last equator crossing before or equal to Tnow.
`from_kepler_orbit`(kepler[, bstar])	Initializes the sgp4 orbit predictor with two line ali_elements extracted from a kepler orbit.
`from_twoline_elements`(line1, line2)	Initializes the sgp4 orbit predictor with classic two line ali_elements.
`orbit_number`(utc)	Calculates the orbit number at time Tnow and returns the start time
`period`()	Return the orbital period of this orbit using the mean motion
`set_orbit_number_from_last_equator_crossing`(...)	Sets the orbit number and calculates the start time/ascending node of the orbit.
`update_eci_position`(autc)	All satellite classes must implement update_eci_position.
`update_orientation`(utc)	Returns a platform orientation that has no modification.
`update_position`(utc)	Overloads the methods from `PlatformLocation`.
`update_velocity`(utc)	Overloads the method from `PlatformLocation`.

__init__(twolines: Tuple[str, str] = None)[source]#

Creates and initializes the sgp4 orbit predictor using two line ali_elements provided by the user. The lines must be in the promper two line format. It is possible to leave the lines as None and initialize the predictor after creation.

Parameters:

twolines: Tuple( str, str ): Two strings that contain the two line ali_elements used to initialize the sgp4 orbit predictor. This paremeter may be None, in which case, the object can be configured by calling from_kepler_orbit or from_twoline_elements

eccentricity() → float[source]#

Purely abstract method that returns the eccentricty of the satellite orbit. This is used in the base class when locating the next crossing of teh ascending node and only requires moderate precision.

Returns:

float: The eccentricty of the satellite orbit in seconds

from_kepler_orbit(kepler: SatelliteKepler, bstar=0.0)[source]#

Initializes the sgp4 orbit predictor with two line ali_elements extracted from a kepler orbit. A simple algorithm that extracts two line ali_elements from a kepler orbit and feeds them into the SGP4 model. Note that the kepler orbit does not correct coordinates to the true equator mean equinox (TEME) coordinates used by sgp4 so there will be minor issues for people seeking precision. On the other hand it is a simple way to fire up the SGP4 from a Kepler orbit, which is quite useful when modelling simple classes of orbit for study work.

Parameters:

keplerSatelliteKepler: The Kepler ali_elements for the satellite. The two line ali_elements are generated for the current time and eciposition stored in the kep[ler satellite.
bstar:float: The B* drag term used by SGP4. This is not part of the Kepler ali_elements and must be manually included by the user. We recommend you leave this as default 0.0 unless you know what you are doing as the drag term used by SGP4 is tricky to get right (it can change by one or two orders of magnitude for example)

from_twoline_elements(line1: str, line2: str)[source]#

Initializes the sgp4 orbit predictor with classic two line ali_elements.

Parameters:

line1:str: The first line of the two line ali_elements
line2:str: The second line of the two line ali_elements

period() → timedelta[source]#

Return the orbital period of this orbit using the mean motion

Returns:

float: The orbital period in seconds

update_eci_position(autc: datetime)[source]#

All satellite classes must implement update_eci_position. This purely abstract method will update the internal attributes self._m_ecilocation, self._m_ecivelocity and self._m_time

Parameters:

utcdatetime: Updates the ECI eciposition and ECI ecivelocity of the satellite to this Coordinated Universal Time

SatelliteSunSync#

Create a satellite which is sun-synchronous. The class is intended for modelling/simulation work where a sun-synchronous orbit is required. The code simulates the sun-synchronous orbit by setting the initial orbit inclination, it is the underlying orbit propagator’s job to calculate the orbit precession. The ‘sgp4’ orbit propagator will precess the orbit properly at one degree per day. A simple ‘kepler’ orbit propagator can also be used but will not precess the orbit, this is satisfactory for short period simulations over a few hours but should not be used for multi-day or longer studies.

For example, the following code will create a sun-synchronous orbit at a nominal altitude of 600 kms awith an ascending node at 18:15LT:

sunsync = SatelliteSunSync( platform_utc, orbittype='sgp4',
                            period_from_altitude=600000.0,
                            localtime_of_ascending_node_hours=18.25)

Regardless of orbit propagator chosen, the sun synchronous orbit is kick-started with a state vector generated by a Kepler orbit with the appropriate sun-synchronous inclination. The state vector is fed to the orbit propagator which then calculates all future platform_ecef_positions of the satellite.

class SatelliteSunSync(utc: datetime64 | datetime | float | str, orbittype='sgp4', sgp4_bstar_drag=0.0, **kwargs)[source]#

Implements a sun-synchronous orbit. This model starts the chosen orbit propagator with appropriate initial conditions given by the user. The orbit inclination is chosen by the code so the orbit with the given period (or altitude) is sun-synchronous. The user can utilize a Keplerian or SGP4 orbit propagator. The kepler propagator is useful for short, one orbit, studies but will not actually precess the orbit. The SGP4 propagator is slower but will capture the sun-synchronous precession over a period of days and months.

Attributes:

earth_location: Returns the current position of the platform as an Astropy EarthLocation.
lat_lon_height: Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters.
position: Returns the position of the satellite in meters in the geocentric geographic ECEF coordinate system.
time: Returns the UTC time of the current state vector
velocity: ECEFITRF/GEO coordinate system.

Methods

`eccentricity`()	Purely abstract method that returns the eccentricty of the satellite orbit.
`eciposition`()	The ECI cartesian position of the satellite in meters after the last call to `update_eci_position`.
`ecivelocity`()	The ECI cartesian velocity of the satellite in meters per second
`equator_crossing`(utc)	Determines the last equator crossing before or equal to Tnow.
`orbit_number`(utc)	Calculates the orbit number at time Tnow and returns the start time
`period`()	Return the period of the satellite.
`set_orbit_number_from_last_equator_crossing`(...)	Sets the orbit number and calculates the start time/ascending node of the orbit.
`set_sun_sync_from_elements`(utc[, orbittype, ...])	Defines the sun-synchronous orbit using Keplerian orbital ali_elements.
`update_eci_position`(tnow)	Updates the eciposition and ecivelocity of the satellite at the given instant in time.
`update_orientation`(utc)	Returns a platform orientation that has no modification.
`update_position`(utc)	Overloads the methods from `PlatformLocation`.
`update_velocity`(utc)	Overloads the method from `PlatformLocation`.

__init__(utc: datetime64 | datetime | float | str, orbittype='sgp4', sgp4_bstar_drag=0.0, **kwargs)[source]#

Parameters:

utc: datetime.datetime: The UTC time of the ali_elements. This is set as the time of the ascending node of the selected orbit.
period_from_secondsfloat: Optional, specifies the orbital period in seconds. An alternative to specify the period is with the optional parameter period_from_altitude. One, but only one, of the two optional methods must be used.
period_from_altitudefloat: Optional, specifies the orbital period using the altitude of the satellite in meters. The altitude is nominal as we do not account for oblateness of the Earth etc. The radius of the Earth is internally assumed to be 6378000.0 meters. An alternative to specify the period is with the optional parameter period_from_seconds. One, but only one, of the two optional methods must be used.
orbittype: str: (default=’sgp4’). User can choose the orbit propagator. Currently accepted values are ‘kepler’ and ‘sgp4’.
sgp4_bstar_dragfloat: (default 0.0). Allows the user to add a drag term. This value is only used by the SGP4 predictor and must be compatible with the SGP4 predictor.
localtime_of_ascending_node_hours: float: Specifies the nominal local time of the ascending node in hours (0-24). If set then its value represents the “hour” at which you want the ascending node for example a floating point value of 18.25 will set the node to 18:15 LT. The current implementation may not be exact but will be close.
longitude_of_ascending_node_degrees: float: Specifies the geographic longitude of the ascending node (-180 to 360)at time platform_utc. This is an alternative method to using parameters localtime_of_ascending_node_hours and right_ascension_ascending_node to specify the right ascension of the ascending node. One, but only one, of the 3 optional methods may be used, if neither option is used the RAAN is set to 0.0.
right_ascension_ascending_node: float: Specifies the Right Ascension of the ascending node in radians (0 to \(2\pi\)). This is an alternative method to parameter longitude_of_ascending_node_degrees to specify the right ascension of the ascending node. One, but only one, of the two optional methods must be used, if neither option is used the RAAN is set to 0.0.
argument_of_perigee: float: Default 0. The argument of perigree in radians (0 to \(2\pi\)).
eccentricity: float: Default 0. The eccentricity of the orbit (0 to 1)
orbitnumber: int: Default 0. The orbit number at the epoch given by platform_utc

eccentricity() → float[source]#

Purely abstract method that returns the eccentricty of the satellite orbit. This is used in the base class when locating the next crossing of teh ascending node and only requires moderate precision.

Returns:

float: The eccentricty of the satellite orbit in seconds

period() → float[source]#

Return the period of the satellite. For low earth orbit spacecraft this is accurate to about 0.1 seconds.

Returns:

datetime.timedelta: The period of the satellite

set_sun_sync_from_elements(utc: datetime, orbittype: str = 'sgp4', sgp4_bstar_drag: float = 0.0, **kwargs)[source]#

Defines the sun-synchronous orbit using Keplerian orbital ali_elements. The sun-synchronous orbit is always kick-started using a Kepler based orbit and it can continue to use that kepler orbit to propagate the position and velocity or it can use the SGP4 model. This function is called by the class instance constructor and the user does not normally need to call this function directly.

Parameters:

utcdatetime.datetime: The universal time of the orbital ali_elements.
orbittype: str: Specifies the type of orbit predictor to be used to propagate the orbit. It can be either ‘kepler’ or ‘sgp4’. Default is ‘sgp4’
sgp4_bstar_drag: float: Optional argument that is only used if the sgp4 propagator is selected. This value is used as the bstar drag term in the SGP4 orbit predictor. The default value is 0.0 implying drag is ignored.
kwargs: extra key word arguments.: These keywords are from the keyword options in SatelliteKepler.from_elements. Note that parameter localtime_of_ascending_node will override, if set, the longitude_of_ascending_node_degrees setting in the keywords options.

update_eci_position(tnow: datetime)[source]#

Updates the eciposition and ecivelocity of the satellite at the given instant in time. The user does not usually call this function directly. It is usually called by the base class SatelliteBase

Parameters:

tnowdatetime: Updates the ECI eci-position and ECI eci-velocity of the satellite to this time

SatelliteMolniya#

Create a satellite which follows a Molniya orbit. The class is intended for modelling/simulation work and can use either a simple Kepler orbit or an SGP4 orbit. For example, the following code will create a molniya orbit:

molniya   = SatelliteMolniya(  self._utc,
                               orbittype='sgp4',
                               longitude_of_ascending_node_degrees=-124.0)

class SatelliteMolniya(utc: datetime | datetime64 | float | str, orbittype='kepler', period_from_seconds: float = 43080.0, inclination_user_defined: float = 1.106538745764405, argument_of_perigee: float = 4.71238898038469, eccentricity: float = 0.74, sgp4_bstar_drag: float = 0.0, **kwargs)[source]#

Implements a Molniya orbit. This model can internally utilize either a Keplerian or SGP4 orbit propagator. The SGP4 propagator will capture gravitational perturbations on the orbit but the Kepler will not. The user will typically initialize the molniya orbit in the constructor but this simply calls set_molniya_from_elements. A full desccription of the optional keyword arguments is given in that function. A sensible default Molniya orbit is provided in the defaults

Attributes:

earth_location: Returns the current position of the platform as an Astropy EarthLocation.
lat_lon_height: Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters.
position: Returns the position of the satellite in meters in the geocentric geographic ECEF coordinate system.
time: Returns the UTC time of the current state vector
velocity: ECEFITRF/GEO coordinate system.

Methods

`eccentricity`()	Purely abstract method that returns the eccentricty of the satellite orbit.
`eciposition`()	The ECI cartesian position of the satellite in meters after the last call to `update_eci_position`.
`ecivelocity`()	The ECI cartesian velocity of the satellite in meters per second
`equator_crossing`(utc)	Determines the last equator crossing before or equal to Tnow.
`orbit_number`(utc)	Calculates the orbit number at time Tnow and returns the start time
`period`()	Return the period of the satellite.
`set_molniya_from_elements`(utc[, orbittype, ...])	Defines the Molniya orbit using Keplerian orbital ali_elements.
`set_orbit_number_from_last_equator_crossing`(...)	Sets the orbit number and calculates the start time/ascending node of the orbit.
`update_eci_position`(tnow)	Updates the eciposition and ecivelocity of the satellite at the given instant in time.
`update_orientation`(utc)	Returns a platform orientation that has no modification.
`update_position`(utc)	Overloads the methods from `PlatformLocation`.
`update_velocity`(utc)	Overloads the method from `PlatformLocation`.

__init__(utc: datetime | datetime64 | float | str, orbittype='kepler', period_from_seconds: float = 43080.0, inclination_user_defined: float = 1.106538745764405, argument_of_perigee: float = 4.71238898038469, eccentricity: float = 0.74, sgp4_bstar_drag: float = 0.0, **kwargs)[source]#

eccentricity() → float[source]#

Purely abstract method that returns the eccentricty of the satellite orbit. This is used in the base class when locating the next crossing of teh ascending node and only requires moderate precision.

Returns:

float: The eccentricty of the satellite orbit in seconds

period() → float[source]#

Return the period of the satellite. For low earth orbit spacecraft this is accurate to about 0.1 seconds.

Returns:

datetime.timedelta: The period of the satellite

set_molniya_from_elements(utc: datetime, orbittype='kepler', period_from_seconds: float = 43080.0, inclination_user_defined: float = 1.106538745764405, argument_of_perigee: float = 4.71238898038469, eccentricity: float = 0.74, sgp4_bstar_drag: float = 0.0, **kwargs)[source]#

Defines the Molniya orbit using Keplerian orbital ali_elements. A default, standard Molniya orbit is provided via the default although the user must supply the right ascension of ascending node using one of the standard SatelliteKepler options (i) localtime_of_ascending_node_hours, (ii) longitude_of_ascending_node_degrees or (iii) right_ascension_ascending_node

The Molniya orbit is always kick-started using Keplerian orbital ali_elements. It can continue to use the keplerian orbit to propagate the position and velocity or it can switch to an SGP4 model orbit propagator.

Parameters:

utcdatetime.datetime: The universal time of the orbital ali_elements.
orbittype: str: Specifies the type of orbit predictor to be used to propagate the orbit. It can be either ‘kepler’ or ‘SGP4’. Default is ‘kepler’
sgp4_bstar_drag: float: Optional argument that is only used if the sgp4 propagator is selected. This value is used as the bstar drag term in the SGP4 orbit predictor. The default value is 0.0 implying drag is ignored.
kwargs: extra key word arguments.: These keywords are from the keyword options in SatelliteKepler.from_elements.

update_eci_position(tnow: datetime)[source]#

Updates the eciposition and ecivelocity of the satellite at the given instant in time.

Parameters:

tnowdatetime: Updates the ECI eciposition and ECI ecivelocity of the stellite to this time

SatelliteSimpleGeostationary#

Create a satellite which follows a Geostationary orbit. This model is a very simple, idealized geostationary orbit that stays fixed over a given geographic point. It is useful for modelling/simulation work. For example, the following code will create a geostationary orbit directly above -80 degree lonngitude:

geostat = SatelliteSimpleGeostationary( -80.0 )

class SatelliteSimpleGeostationary(longitude_degrees: float)[source]#

Implements a simple geostationary satellite that simply stays above a fixed location on the equator.

Attributes:

earth_location: Returns the current position of the platform as an Astropy EarthLocation.
lat_lon_height: Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters.
position: Returns the position of the satellite in meters in the geocentric geographic ECEF coordinate system.
time: Returns the UTC time of the current state vector
velocity: ECEFITRF/GEO coordinate system.

Methods

`eccentricity`()	Returns the eccentricity of the orbit.
`eciposition`()	The ECI cartesian position of the satellite in meters after the last call to `update_eci_position`.
`ecivelocity`()	The ECI cartesian velocity of the satellite in meters per second
`equator_crossing`(utc)	Determines the last equator crossing before or equal to Tnow.
`orbit_number`(utc)	Calculates the orbit number at time Tnow and returns the start time
`period`()	Returns the period of the geostationary orbit to be exactly one sidereal day.
`set_orbit_number_from_last_equator_crossing`(...)	Sets the orbit number and calculates the start time/ascending node of the orbit.
`update_eci_position`(utc)	Not usually used by users.
`update_orientation`(utc)	Returns a platform orientation that has no modification.
`update_position`(utc)	Overloads the methods from `PlatformLocation`.
`update_velocity`(utc)	Overloads the method from `PlatformLocation`.

__init__(longitude_degrees: float)[source]#

Create a geostationary orbit that remains fixed over the the given longitude.

Parameters:

longitude_degrees:: float: The geographic longitude of the geostationary orbit. expressed in degrees, +ve east.

eccentricity() → float[source]#: Returns the eccentricity of the orbit. It will always be zero.

period() → float[source]#

Returns the period of the geostationary orbit to be exactly one sidereal day.

Returns:

float: The period of the satellite in seconds

update_eci_position(utc: datetime)[source]#

Not usually used by users. Updates the ECI location of the satellite.

Parameters:

utcdatetime: Updates the ECI position and ECI velocity of the satellite to this Coordinated Universal Time

SatelliteBase#

The SatelliteBase is the base class that all satellites inherit from. Most users do not use this class.

class SatelliteBase[source]#

The SatelliteBase is a base class for artificial satellites orbiting the Earth. The class derives from PlatformLocation which allows the SatelliteBase class and its derivatives to be used by the skretrieval package to calculate the location of instruments mounted on satellites. The ECI-TEME coordinate system is used for storage of satellite position and velocity. There is some looseness in the definition of Earth Centered Inertial. We use the definition of ECI employed by the SGP4 orbital propagator code which is a Celestial Reference system using the true equator and mean equinox, TEME, i.e. precession is accounted for but nutation is not. This system is not the same as the GCRS system commonly used in astronomy applications today so care must be taken when transforming coordinate systems. The conversion to and from ECI-TEME is provided by the eci functions in package sktimeutils which have been checked to centimeter precision.

The SatelliteBase class overrides and implements the following three functions of parent class PlatformLocation

position
velocity
update_position

Note that the above three functions return answers in the geographic geocentric system and not the eci system.

Child classes that implement specific satellite orbit propagator methods and derive from SatelliteBase must implement the following abstract methods:

update_eci_position
period

Attributes:

earth_location: Returns the current position of the platform as an Astropy EarthLocation.
lat_lon_height: Returns the current platform location as a 3 element array of geodetic coordinates, latitude in degrees, longitude in degrees and height in meters.
position: Returns the position of the satellite in meters in the geocentric geographic ECEF coordinate system.
time: Returns the UTC time of the current state vector
velocity: ECEFITRF/GEO coordinate system.

Methods

`eccentricity`()	Purely abstract method that returns the eccentricty of the satellite orbit.
`eciposition`()	The ECI cartesian position of the satellite in meters after the last call to `update_eci_position`.
`ecivelocity`()	The ECI cartesian velocity of the satellite in meters per second
`equator_crossing`(utc)	Determines the last equator crossing before or equal to Tnow.
`orbit_number`(utc)	Calculates the orbit number at time Tnow and returns the start time
`period`()	Purely abstract method that returns the orbital period of the satellite in seconds.
`set_orbit_number_from_last_equator_crossing`(...)	Sets the orbit number and calculates the start time/ascending node of the orbit.
`update_eci_position`(utc)	All satellite classes must implement update_eci_position.
`update_orientation`(utc)	Returns a platform orientation that has no modification.
`update_position`(utc)	Overloads the methods from `PlatformLocation`.
`update_velocity`(utc)	Overloads the method from `PlatformLocation`.

Regular methods

eciposition() → ndarray[source]#

The ECI cartesian position of the satellite in meters after the last call to update_eci_position.

Returns:

np.ndarray[3]
The three element array specifying ECI location as (X,Y,Z) meters

ecivelocity() → ndarray[source]#

The ECI cartesian velocity of the satellite in meters per second

Returns:

np.ndarray[3]
The three element array specifying ECI velocity as (X,Y,Z) meters per second

equator_crossing(utc: datetime) → datetime[source]#

Determines the last equator crossing before or equal to Tnow.

Parameters:

Tnow: datetime.datetime
Find the equator crossing before (or at) this time

Returns:

datetime.datetime
The time at which this satellite object crosses the equator

set_orbit_number_from_last_equator_crossing(orbitnumber: int, utc: datetime)[source]#

Sets the orbit number and calculates the start time/ascending node of the orbit.

Parameters:

orbitnumber: int
The orbit number at time Tnow

Tnow: datetime.datetime
The current time.

orbit_number(utc: datetime) → Tuple[int, datetime][source]#

Calculates the orbit number at time Tnow and returns the start time of that orbit.

Parameters:

utcdatetime
The Coordinated Universal Time at which to calculate the orbit number

Returns:

(int,datetime)
Returns a two element tuple specifying the orbit number and the time of the last equator crossing

_set_current_state(ecipos: ndarray, ecivel: ndarray, t: datetime)[source]#

Sets the ECI position, ECI velocity and current time of the satellite. This is typically called by child satellite implementation classes at the end of a call to method update_eci_position

Parameters:

eciposnp.ndarray[3]
The three element (X,Y,Z) array specifying ECI position in meters .

ecivelnp.ndarray[3]
The three element (X,Y,Z) array specifying ECI velocity in meters/second

tdatetime.datetime
The current UTC time of the eciposition and ecivelocity.

Sun, Moon, Stars#

skplatform provides a small wrapper around astropy to support stars

star_unitvector_itrf(utc: datetime, body: str) → ndarray[source]#

Fetches the ITRF geocentric unit vector from the center of the Earth to the desired star at the requested time. This currently does not account for proper motion of the star.

Parameters:

utcdatetime, np.datetime64, str
The UTC time at which the position of the star is required

body: str
The name of the star, e.g. “Betelgeuse”

Returns:
np.ndarray(3): The geocentric unit vector toward the requested star as a 3 element column vector. Dimensionless Unit vector.

solsys_body_vector_itrf(utc: datetime, body: str) → ndarray[source]#

Fetches the ITRF geocentric vector from the center of the Earth to the solar system body at the requested time.

Parameters:

utcdatetime, np.datetime64, str
The UTC time at which the position of the body is required

body: str
The name of the solar system body, e.g. “moon”, “sun”

Returns:
np.ndarray(3): The geocentric positon of the requested body as a 3 element column vector. Expressed in meters.