Satellite Classes

Satellite classes are used to locate the position of a platform. They are derived from class PlatformLocator.

SatelliteBase

class skimpy.satellite.SatelliteBase

The SatelliteBase is a base class for artificial satellites orbiting the Earth. The class derives from PlatformLocator which allows the SatelliteBase class and its derivatives to be used by the skimpy package to calculate the location of instruments mounted on satellites. The ECI coordinate system is used for storage of satellite position and velocity and 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, 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 SatelliteBase class overrides and implements the following three functions of parent class PlatformLocator #. 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()

Platform Locator methods These are methods required to support PlatformLocator

update_position(utc: datetime.datetime) → numpy.ndarray

Updates the geographic geocentric location of the platform at the given coordinated universal time and returns the new position. This is an abstract method and must be implemented in derived child classes.

Parameters:utc (datetime) – The time at which to update the location of the platform
Returns:The three element X,Y,Z geographic geocentric location of the platform
Return type:np.ndarray, Array[3]
position() → numpy.ndarray

Returns the position of the satellite in meters in the geocentric geographic GEO coordinate system

Returns:The three element array specifying (X,Y,Z) in meters
Return type:np.ndarray[3]
velocity() → numpy.ndarray

Returns the velocity of the satellite in meters/second in the geographic GEO coordinate system

Returns:The three element array specifying (X,Y,Z) in meters
Return type:np.ndarray[3]

Satellite Abstract methods

update_eci_position(utc: datetime.datetime)

Purely abstract method which are implemented in derivative classes to update the internal attributes self._m_ecilocation, self._m_ecivelocity and self._m_time

Parameters:utc (datetime) – Updates the ECI eciposition and ECI ecivelocity of the satellite to this Coordinated Universal Time
period() → datetime.timedelta

Purely abstract method that returns the orbital period of the satellite in seconds. For low earth orbit spacecraft this only needs to be accurate to ~0.1 seconds.

Returns:The period of the satellite in seconds
Return type:timedelta

Regular methods

time() → datetime.datetime

Returns the UTC time of the current state vector

Returns:The time of the current state vector
Return type:datetime.datetime
eciposition() → numpy.ndarray

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

Returns:The three element array specifying ECI location as (X,Y,Z) meters
Return type:np.ndarray[3]
ecivelocity() → numpy.ndarray

The ECI cartesian velocity of the satellite in meters per second

Returns:The three element array specifying ECI velocity as (X,Y,Z) meters per second
Return type:np.ndarray[3]
equator_crossing(utc: datetime.datetime) → datetime.datetime

Determines the last equator crossing before or equal to Tnow.

Parameters:Tnow (datetime.datetime) – Find the equator crossing before (or at) this time
Returns:The time at which this satellite object crosses the equator
Return type:datetime.datetime
set_orbit_number_from_last_equator_crossing(orbitnumber: int, utc: datetime.datetime)

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.datetime) → Tuple[int, datetime.datetime]
Calculates the orbit number at time Tnow and returns the start time of that orbit.
Parameters:utc (datetime) – The Coordinated Universal Time at which to calculate the orbit number
Returns:Returns a two element tuple specifiying the orbit number and the time of the last equator crossing
Return type:(int,datetime)
_set_current_state(ecipos: numpy.ndarray, ecivel: numpy.ndarray, t: datetime.datetime)

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:
  • ecipos (np.ndarray[3]) – The three element (X,Y,Z) array specifying ECI position in meters .
  • ecivel (np.ndarray[3]) – The three element (X,Y,Z) array specifying ECI velocity in meters/second
  • t (datetime.datetime) – The current UTC time of the eciposition and ecivelocity.

SatelliteKepler

Implements a classic Keplerian 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 skimpy.satellite  import SatelliteKepler
.
.
kepler  = SatelliteKepler ( 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 skimpy.satellite.SatelliteKepler(utc: datetime.datetime, period_from_seconds: float = None, period_from_altitude: 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)
__init__(utc: datetime.datetime, period_from_seconds: float = None, period_from_altitude: 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)

Initializes the Kepler orbit.

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()
  • 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()
  • 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

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:The eccentricty of the satellite orbit in seconds
Return type:float
from_elements(utc: datetime.datetime, period_from_seconds: float = None, period_from_altitude: 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)

Define the Kepler orbit from the classic 6 Keplerian elements.

  1. period
  2. inclination
  3. eccentricity
  4. mean anomaly
  5. right ascension of ascending node
  6. argument of perigee

Several of the orbital 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 elements,

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

Leaving the remaining three 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:
  • utc (datetime.datetime) – The UTC time of the elements
  • period_from_seconds (float) – 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_altitude (float) – 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.
  • inclination_radians (float) – 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_sync (bool) – 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 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 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 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.datetime, orbitnumber: int, r: numpy.ndarray, v: numpy.ndarray)

Update the object so it calculates orbits derived from the specified state vector

Parameters:
  • utc (datetime) – The coordinated universal time of the state vector.
  • orbitnumber (int) – The orbit number at the epoch
  • r (np.ndarray [3]) – ECI coordinates at epoch (in metres) eciposition of the satellite
  • v (np.ndarray[3]) – ECI ecivelocity at epoch in m/s
make_two_line_elements(first_derivative=0.0, second_derivative=0.0, bstar=0.0, satnum=1) → Tuple[str, str]

Returns the current orbital elements as two line elements. This is handy if you want to initialize an SGP4 predictor from a Kepler “starter orbit” using two line 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 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 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:

Returns the two lines of the elements as a two element tuple of two strings
Return type:

tuple( str,str)
period() → datetime.timedelta

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

Returns:The orbital period.
Return type:datetime.timedelta
sun_synchronous_inclination(semi_major_axis_meters: float) → float

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:
Return type:The required inclination of the orbit in radians
update_eci_position(utc: datetime.datetime)

Purely abstract method which are implemented in derivative classes to update the internal attributes self._m_ecilocation, self._m_ecivelocity and self._m_time

Parameters:utc (datetime) – Updates the ECI eciposition and ECI ecivelocity of the satellite to this Coordinated Universal Time

SatelliteSGP4

class skimpy.satellite.satellitesgp4.SatelliteSGP4(twolines: Tuple[str, str] = None)

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

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

Initialize self. See help(type(self)) for accurate signature.

eccentricity() → float

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:The eccentricty of the satellite orbit in seconds
Return type:float
from_kepler_orbit(kepler: skimpy.satellite.satellitekepler.SatelliteKepler, bstar=0.0)

A simple algorithm that extracts two line elements from a kepler orbit and feeds them into the SGP4 model. Note that the kepler orbit does not correect coordinate to the mean equinox and equator so their may be minor issues. On the hand its a simple way to fire uo the SGP4 from a Kepler orbit, which is useful when modelling simple orbits.

Parameters:
  • kepler (SatelliteKepler) – The Kepler elements for the satellite. The two line 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 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)
period() → datetime.timedelta

Return the orbital period of this orbit using the mean motion

Returns:The orbital period in seconds
Return type:float
update_eci_position(utc: datetime.datetime)

Purely abstract method which are implemented in derivative classes to update the internal attributes self._m_ecilocation, self._m_ecivelocity and self._m_time

Parameters:utc (datetime) – Updates the ECI eciposition and ECI ecivelocity of the satellite to this Coordinated Universal Time

SatelliteSunSync

class skimpy.satellite.satellitesunsync.SatelliteSunSync(utc: datetime.datetime, orbittype='kepler', sgp4_bstar_drag=0.0, **kwargs)

Implements a sun-synchronous orbit. This model can utilize either a Keplerian or SGP4 orbit propagator. The user will typically call set_sun_sync_from_elements() during initialization to configure the sun-sync orbit

__init__(utc: datetime.datetime, orbittype='kepler', sgp4_bstar_drag=0.0, **kwargs)

Initialize self. See help(type(self)) for accurate signature.

eccentricity() → float

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:The eccentricty of the satellite orbit in seconds
Return type:float
period() → float

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

Returns:The period of the satellite
Return type:datetime.timedelta
set_sun_sync_from_elements(utc: datetime.datetime, orbittype='kepler', sgp4_bstar_drag=0.0, **kwargs)

Defines the sun-synchronous orbit using Keplerian orbital 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.

Parameters:utc (datetime.datetime) – The universal time of the orbital 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(). Note that parameter localtime_of_ascending_node will override, if set, the longitude_of_ascending_node_degrees setting in the key words options.
update_eci_position(tnow: datetime.datetime)

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

Parameters:tnow (datetime) – Updates the ECI eci-position and ECI eci-velocity of the satellite to this time

SatelliteTudat

class skimpy.satellite.satellitetudat.SatelliteTudat
__init__()

Initialize self. See help(type(self)) for accurate signature.

period() → datetime.timedelta

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

Returns:The orbital period.
Return type:datetime.timedelta
update_eci_position(mjd: datetime.datetime)

Purely abstract method which are implemented in derivative classes to update the internal attributes self._m_ecilocation, self._m_ecivelocity and self._m_time

Parameters:utc (datetime) – Updates the ECI eciposition and ECI ecivelocity of the satellite to this Coordinated Universal Time

PlatformLocator

class skimpy.satellite.PlatformLocator

The base class used to specify the location and velocity, if appropriate, of all platforms that carry instruments, which covers the gamut of spacecraft, aircraft, balloons and ground sites. This base class exposes three functions that all PlatformLocator classes will support, (i) update_position(), (ii) position() and (iii) velocity()

update_position(utc: datetime.datetime) → numpy.ndarray

Updates the geographic geocentric location of the platform at the given coordinated universal time and returns the new position. This is an abstract method and must be implemented in derived child classes.

Parameters:utc (datetime) – The time at which to update the location of the platform
Returns:The three element X,Y,Z geographic geocentric location of the platform
Return type:np.ndarray, Array[3]
position() → numpy.ndarray

Returns the geographic geocentric location calculated in the last call to update_position(). This is an abstract method and must be implemented in derived child classes.

Returns:The three element X,Y,Z geocentric location of the platform. All numbers are in meters.
Return type:np.ndarray, Array[3]
velocity() → numpy.ndarray

Returns the geocentric velocity calculated in the last call to update_position(). This may be implemented in derived child classes to override the default method which returns an array of zeros, i.e. suitable for ground stations

Returns:The three element X,Y,Z geographic geocentric velocity of the platform. All numbers are in meters/second.
Return type:np.ndarray, Array[3]