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.

Parameters

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)

Returns

incfloat

satellite inclination (radian)

raanfloat

Right ascension of ascending node (radian)

apfloat

Argument of periapsis (radian)

efloat

eccentricity (radian)

TAfloat

True anomaly (radian)

Examples

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.

Parameters

file_casstr

file name including path

time_startdatetime.datetime

start of the experiment

time_enddatetime.datetime

end of the experiment

Returns

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

Latnp.array[float]

Geodetic latitude

Lonnp.array[float]

Geodetic longitude

Altnp.array[float]

geodetic altitude (km)

MLat: np.array[float]

Magnetic latitude (deg)

MLon: np.array[float]

Magnetic longitude (deg)

MLT: np.array[float]

Magnetic local time (h)

GEIxnp.array[float]

Spacecraft position in GEI coordinates (X-km)

GEIynp.array[float]

Spacecraft position in GEI coordinates (Y-km)

GEIznp.array[float]

Spacecraft position in GEI coordinates (Z-km)

GEIVxnp.array[float]

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

GEIVynp.array[float]

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

GEIVznp.array[float]

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

GSMxnp.array[float]

Spacecraft position in GEI coordinates (X-km)

GSMynp.array[float]

Spacecraft position in GEI coordinates (Y-km)

GSMznp.array[float]

Spacecraft position in GEI coordinates (Z-km)

rollnp.array[float]

roll angle; rotation around x axis (degrees)

pitchnp.array[float]

pitch angle; rotation around y axis (degrees)

yawnp.array[float]

yaw angle; rotation around z axis (degrees)

accint

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

Examples

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

Parameters

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).

Returns

sap_compTuple[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)

Examples

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/

Parameters

filename: str

filename for TLE file.

filedate: str

date of RRI passage.

DOY: int

day of year of RRI passage.

Returns

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).

Examples

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:

Parameters

file_rriTYPE

RRI file name including path

Returns

dict:

keys and properties of the keys are below: time_data : np.array[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

Latnp.array[float]

Geodetic latitude

Lonnp.array[float]

Geodetic longitude

Altnp.array[float]

geodetic altitude (km)

MLat: np.array[float]

Magnetic latitude (deg)

MLon: np.array[float]

Magnetic longitude (deg)

MLT: np.array[float]

Magnetic local time (h)

GEOxnp.array[float]

Spacecraft position in GEO coordinates (X-km)

GEOynp.array[float]

Spacecraft position in GEO coordinates (Y-km)

GEOznp.array[float]

Spacecraft position in GEO coordinates (Z-km)

GEOVxnp.array[float]

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

GEOVynp.array[float]

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

GEOVznp.array[float]

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

GEIxnp.array[float]

Spacecraft position in GEI coordinates (X-km)

GEIynp.array[float]

Spacecraft position in GEI coordinates (Y-km)

GEIznp.array[float]

Spacecraft position in GEI coordinates (Z-km)

GEIVxnp.array[float]

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

GEIVynp.array[float]

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

GEIVznp.array[float]

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

rollnp.array[float]

roll angle; rotation around x axis (degrees)

pitchnp.array[float]

pitch angle; rotation around y axis (degrees)

yawnp.array[float]

yaw angle; rotation around z axis (degrees)

accuracyint

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

Examples

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.

Parameters

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

Returns

dictdict

keys and properties listed below ITRFx : np.array[float]

Spacecraft position in ITRF coordinates (X-km)

ITRFynp.array[float]

Spacecraft position in ITRF coordinates (Y-km)

ITRFznp.array[float]

Spacecraft position in ITRF coordinates (Z-km)

ITRFVxnp.array[float]

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

ITRFVynp.array[float]

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

ITRFVznp.array[float]

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

Examples

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

ITRFx = dict_sp3[‘ITRFx’]