ephemeris_importer: module to import RRI ephemeris and Celestrak TLE

ephemeris_importer module imports several types of data files to obtain spacecraft ephemeris. Values are returned as Python dictionaries.

Swarm-E specific data files are: CAS_ephemeris, Cas_AttQUAT, and RRI

Files standard for all spacecraft: sp3, TLE

ephemeris_importer also includes functions to compute satellite orbital elements using GEIJ2K position and velocity (calculate_orbital_elements), and to compare computed values with data in TLE file (compare_orbital).

@author: ceren

ephemeris_importer.calculate_orbital_elements(pX, pY, pZ, Vx, Vy, Vz)

Calculates satellite orbital parameters using X, Y, Z, Vx, Vy, Vz in GEIJ2K

Reference: Curtis, H. D. (2014). Orbits in Three Dimensions in Orbital mechanics for engineering students. Butterworth-Heinemann.

pXnumpy.ndarray[float]

X position in GEIJ2K (km).

pYnumpy.ndarray[float]

Y position in GEIJ2K (km).

pZnumpy.ndarray[float]

Z position in GEIJ2K (km).

Vxnumpy.ndarray[float]

X component of velocity in GEIJ2K (km/s).

Vynumpy.ndarray[float]

Y component of velocity in GEIJ2K (km/s).

Vznumpy.ndarray[float]

Z component of velocity in GEIJ2K (km/s).

incfloat

satellite inclination (radian).

raanfloat

Right ascension of ascending node (radian).

apfloat

Argument of periapsis (radian).

efloat

eccentricity (radian).

TAfloat

True anomaly (radian).

sat_inc, sat_ap, sat_raan, sat_ecc, sat_TA =
ei.calculate_orbital_elements(dict_rri[‘GEIx’], dict_rri[‘GEIy’],

dict_rri[‘GEIz’], dict_rri[‘GEIVx’], dict_rri[‘GEIVy’], dict_rri[‘GEIVz’])

ephemeris_importer.cas_ephemeris(file_cas, time_start, time_end)

Imports CAS_ephemeris files of Swarm-E: Ref:(https://epop.phys.ucalgary.ca/data-handbook/cas-ephemeris-text-files/)

Extracts satellite ephemeris info for the experiment time interval specified by time_start and time_end.

file_casstr

file name including path.

time_startdatetime.datetime

start of the experiment.

time_enddatetime.datetime

end of the experiment.

dictdict

keys and properties listed below srow : int

row of the start time in the cas_ephemeris file.

erowint

row of the end time in the cas_ephemeris file.

startdatetime.datetime

start time in CAS_ephemeris file.

enddatetime.datetime

end time in CAS_ephemeris file.

time_arraydatetime.datetime

time of the observations.

Latnumpy.ndarray[float]

Geodetic latitude.

Lonnumpy.ndarray[float]

Geodetic longitude.

Altnumpy.ndarray[float]

geodetic altitude (km) .

MLat: numpy.ndarray[float]

Magnetic latitude (deg).

MLon: numpy.ndarray[float]

Magnetic longitude (deg).

MLT: numpy.ndarray[float]

Magnetic local time (h).

GEIxnumpy.ndarray[float]

Spacecraft position in GEI coordinates (X-km).

GEIynumpy.ndarray[float]

Spacecraft position in GEI coordinates (Y-km).

GEIznumpy.ndarray[float]

Spacecraft position in GEI coordinates (Z-km).

GEIVxnumpy.ndarray[float]

X component of the spacecraft velocity in GEI coordinates (Vx-km/s).

GEIVynumpy.ndarray[float]

Y component of the spacecraft velocity in GEI coordinates (Vy-km/s).

GEIVznumpy.ndarray[float]

Z component of the spacecraft velocity in GEI coordinates (Vz-km/s).

GSMxnumpy.ndarray[float]

Spacecraft position in GEI coordinates (X-km).

GSMynumpy.ndarray[float]

Spacecraft position in GEI coordinates (Y-km).

GSMznumpy.ndarray[float]

Spacecraft position in GEI coordinates (Z-km).

rollnumpy.ndarray[float]

roll angle; rotation around x axis (degrees).

pitchnumpy.ndarray[float]

pitch angle; rotation around y axis (degrees).

yawnumpy.ndarray[float]

yaw angle; rotation around z axis (degrees).

accint

accuracy of the attitude solution. (0 = Dropout, 1 = Rough, 2 = Coarse, 3 = Moderate, 4 = Fine)

eclipse: str

spacecraft eclipse (umbra, penumbra, sunlit)

dict_cas = ei.cas_ephemeris(file_CAS, time_start, time_end)

GEIx = dict_cas[‘GEIx’]

ephemeris_importer.compare_orbital(file_TLE, filedate, DOY, pX, pY, pZ, Vx, Vy, Vz)

Compares values from the TLE file with the calculated average TLE values. Prints out the comparison results.

inc: spacecraft inclination angle raan: right ascension of ascending node ap: argument of periapsis

file_TLE: str

filename for TLE file (including path).

filedate: str

date of RRI passage, format: ‘%H%M%S’.

DOY: int

day of year of RRI passage.

pXnumpy.ndarray[float]

X position in GEIJ2K (km).

pYnumpy.ndarray[float]

Y position in GEIJ2K (km).

pZnumpy.ndarray[float]

Z position in GEIJ2K (km).

Vxnumpy.ndarray[float]

X component of velocity in GEIJ2K (km/s).

VyTnumpy.ndarray[float]

Y component of velocity in GEIJ2K (km/s).

Vznumpy.ndarray[float]

Z component of velocity in GEIJ2K (km/s).

sap_comp : list[float, float, float]

Element1: the difference between the tle and computed inclination (deg)

Element2: the difference between the tle and computed raan (deg)

Element3: the difference between the tle and computed ap (deg)

time_start = datetime.datetime(2016, 4, 18, 22, 27, 59)

DOY = time_start.timetuple().tm_yday

filedate = ‘20160418’

comp = ei.compare_orbital(file_TLE, filedate, DOY, dict_rri[‘GEIx’],

dict_rri[‘GEIy’], dict_rri[‘GEIz’],

dict_rri[‘GEIVx’], dict_rri[‘GEIVy’],

dict_rri[‘GEIVz’])

ephemeris_importer.import_tle(filename, filedate, DOY)

Reads Celestrak TLE file

File obtained from: https://celestrak.com/

filename: str

filename for TLE file.

filedate: str

date of RRI passage.

DOY: int

day of year of RRI passage.

tle_epochfloat

epoch of TLE file.

tle_incfloat

satellite inclination (degrees).

tle_apfloat

satellite argument of perigee (degrees).

tle_raanfloat

right ascension of ascending node (degrees).

tle_eccint

orbit eccentricity.

tle_mafloat

mean anomaly (degrees).

time_start = datetime.datetime(2016, 4, 18, 22, 27, 59)

DOY = time_start.timetuple().tm_yday

filedate = ‘20160418’

tle_epoch, tle_inc, tle_ap, tle_raan, tle_ecc, tle_ma =

ei.import_tle(file_TLE, filedate, DOY)

ephemeris_importer.rri_ephemeris(file_rri)

Imports rri_ephemeris and returns the ephemeris information within a dictionary.

Dictionary keys are listed below:

file_rriTYPE

RRI file name including path

dict:

keys and properties of the keys are below: time_data : numpy.ndarray[float]

seconds since May 24, 1968.

time_arraydatetime.datetime

time of the observations.

start_timedatetime.datetime

start_time of the experiment.

end_timedatetime.datetime

end time of the experiment.

Latnumpy.ndarray[float]

Geodetic latitude (degrees).

Lonnumpy.ndarray[float]

Geodetic longitude (degrees).

Altnumpy.ndarray[float]

geodetic altitude (km).

MLat: numpy.ndarray[float]

Magnetic latitude (deg).

MLon: numpy.ndarray[float]

Magnetic longitude (degrees).

MLT: numpy.ndarray[float]

Magnetic local time (h).

GEOxnumpy.ndarray[float]

Spacecraft position in GEO coordinates (X-km).

GEOynumpy.ndarray[float]

Spacecraft position in GEO coordinates (Y-km).

GEOznumpy.ndarray[float]

Spacecraft position in GEO coordinates (Z-km).

GEOVxnumpy.ndarray[float]

X component of the spacecraft velocity in GEO coordinates (Vx-km/s).

GEOVynumpy.ndarray[float]

Y component of the spacecraft velocity in GEO coordinates (Vy-km/s).

GEOVznumpy.ndarray[float]

Z component of the spacecraft velocity in GEO coordinates (Vz-km/s).

GEIxnumpy.ndarray[float]

Spacecraft position in GEI coordinates (X-km).

GEIynumpy.ndarray[float]

Spacecraft position in GEI coordinates (Y-km).

GEIznumpy.ndarray[float]

Spacecraft position in GEI coordinates (Z-km).

GEIVxnumpy.ndarray[float]

X component of the spacecraft velocity in GEI coordinates (Vx-km/s).

GEIVynumpy.ndarray[float]

Y component of the spacecraft velocity in GEI coordinates (Vy-km/s).

GEIVznumpy.ndarray[float]

Z component of the spacecraft velocity in GEI coordinates (Vz-km/s).

rollnumpy.ndarray[float]

roll angle; rotation around x axis (degrees).

pitchnumpy.ndarray[float]

pitch angle; rotation around y axis (degrees).

yawnumpy.ndarray[float]

yaw angle; rotation around z axis (degrees).

accuracyint

accuracy of the attitude solution. (0 = Dropout, 1 = Rough, 2 = Coarse, 3 = Moderate, 4 = Fine)

dict_rri = ei.rri_ephemeris(file_RRI)

Lat = dict_rri[‘Lat’]

ephemeris_importer.sp3_ephemeris(file_SP3, start_date, end_date)

imports position and velocity data in the International Terrestrial Reference Frame (ITRF) from the sp3 data file:

Ref: (https://epop.phys.ucalgary.ca/data-handbook/orbit-geo-sp3-file/)

Extracts satellite ephemeris info for the experiment time interval specified by time_start and time_end.

file_SP3str

SP3 filename with file path

start_datedatetime.datetime

beginning of the data sampling interval

end_datedatetime.datetime

end of the data sampling interval

dictdict

keys and properties listed below: srow : int

row of the experiment start time in sp3 file

erow: int

row of the experiment end time in sp3 file

time_array_gpsdatetime.datetime

time array for the whole day: note that sp3 files for Swarm-E may have some offset as they use GPS time rather than the UT time. to check the beginning and end times of the data file simply do:

dict_sp3[‘time_array’][0] dict_sp3[‘time_array’][-1]

time_array_ut: datetime.datetime

time array in ut. corrected from gps time.

time_experiment: datetime.datetume

time array for the experiment interval in ut.

ITRFxnumpy.ndarray[float]

Spacecraft position in ITRF coordinates (X-km).

ITRFynumpy.ndarray[float]

Spacecraft position in ITRF coordinates (Y-km).

ITRFznumpy.ndarray[float]

Spacecraft position in ITRF coordinates (Z-km).

ITRFVxnumpy.ndarray[float]

X component of the spacecraft velocity in ITRF coordinates(Vx-dm/s).

ITRFVynumpy.ndarray[float]

Y component of the spacecraft velocity in ITRF coordinates(Vy-dm/s).

ITRFVznumpy.ndarray[float]

Z component of the spacecraft velocity in ITRF coordinates(Vz-dm/s).

dict_sp3 = ei.sp3_ephemeris(file_SP3, start_date, end_date)

ITRFx = dict_sp3[‘ITRFx’]