spherapy 0.2.1__tar.gz → 0.3.0__tar.gz

spherapy-0.3.0/CHANGELOG.md

@@ -0,0 +1,21 @@
+The change log should include
+- theme of the upversion
+- changes in API
+- changes in model behaviour
+
+# v0.3.0
+ - renamed fromAnalyticalOrbitalParams() argument mean_nu to true_nu to reflect the underlying api call to hapsira.
+ - added an epoch argument for the orbital parameters of fromAnalyticalOrbitalParams(). Note the default epoch for fromAnalyticalOrbitalParams() is now the first timestep of the TimeSpan rather than astropy's J2000. This is a breaking change and thus existing calls to fromAnalyticalOrbitalParams() will almost certainly now produce different results. The previous functionality can be obtained by choosing datetime.datetime.fromisoformat('2000-01-01T12:00:00+00:00') as the epoch.
+ - adding typing overloads to the TimeSpan.__getitem__() function which specify a stronger typing constraints dependent on the type of the argument.
+ - fixed TimeSpan.__getitem__() adding extra layer of list nesting when index was of type list.
+
+# v0.2.1
+- minor bug fixes to the API for pulling TLEs from Celestrak
+
+# v0.2.0
+- initial release to pypi
+- timespan object
+- orbit object
+- orbit object creation from: TLE, propagated orbital parameters, analytical orbital parameters, list of positions
+- TLE updater, pulls requested TLEs from spacetrack, stores all TLEs for that satellite in a saved file
+- TLE updater falls back to celestrak if no credentials provided

{spherapy-0.2.1/spherapy.egg-info → spherapy-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spherapy
-Version: 0.2.1
+Version: 0.3.0
 Summary: An orbital propagator wrapper and TLE fetcher
 Author-email: Robert Mearns <rz.mearns@gmail.com>
 Maintainer-email: Robert Mearns <rz.mearns@gmail.com>
@@ -87,7 +87,7 @@ o = spherapy.orbit.Orbit.fromAnalyticalOrbitalParam(timespan, body='Earth',
 					 inc=0,
 					 raan=0,
 					 argp=0,
-					 mean_nu=0,
+					 true_nu=0,
 					 name='My Analytical Orbit',
 					 astrobodies=True)
 ```  
@@ -115,7 +115,7 @@ o = spherapy.orbit.Orbit.fromAnalyticalOrbitalParam(timespan, body='Earth',
 					 inc=0,
 					 raan=0,
 					 argp=0,
-					 mean_nu=0,
+					 true_nu=0,
 					 name='My Analytical Orbit',
 					 astrobodies=True)
 ```

{spherapy-0.2.1 → spherapy-0.3.0}/README.md

@@ -53,7 +53,7 @@ o = spherapy.orbit.Orbit.fromAnalyticalOrbitalParam(timespan, body='Earth',
 					 inc=0,
 					 raan=0,
 					 argp=0,
-					 mean_nu=0,
+					 true_nu=0,
 					 name='My Analytical Orbit',
 					 astrobodies=True)
 ```  
@@ -81,7 +81,7 @@ o = spherapy.orbit.Orbit.fromAnalyticalOrbitalParam(timespan, body='Earth',
 					 inc=0,
 					 raan=0,
 					 argp=0,
-					 mean_nu=0,
+					 true_nu=0,
 					 name='My Analytical Orbit',
 					 astrobodies=True)
 ```

{spherapy-0.2.1 → spherapy-0.3.0}/spherapy/_version.py

@@ -28,7 +28,7 @@ version_tuple: VERSION_TUPLE
 commit_id: COMMIT_ID
 __commit_id__: COMMIT_ID
 
-__version__ = version = '0.2.1'
-__version_tuple__ = version_tuple = (0, 2, 1)
+__version__ = version = '0.3.0'
+__version_tuple__ = version_tuple = (0, 3, 0)
 
-__commit_id__ = commit_id = 'ge103d2055'
+__commit_id__ = commit_id = 'gad44a3cde'

{spherapy-0.2.1 → spherapy-0.3.0}/spherapy/orbit.py

@@ -626,7 +626,8 @@ class Orbit:
 											inc:float=0,
 											raan:float=0,
 											argp:float=0,
-											mean_nu:float=0,
+											true_nu:float=0,
+											epoch:dt.datetime|None=None,
 											name:str='Analytical',
 											astrobodies:bool=True,
 											unsafe:bool=False) -> 'Orbit':
@@ -651,8 +652,11 @@ class Orbit:
 			argp: [Optional] argument of the perigee in degrees
 					Default is 0, which	represents an orbit with its semimajor axis in
 					the plane of the Earth's equator
-			mean_nu: [Optional] mean anomaly in degrees
-					Default is 0, which represents an orbit that is beginning at periapsis
+			true_nu: [Optional] true anomaly at epoch in degrees
+					Default is 0, which represents an orbit that is beginning
+					at periapsis on the epoch
+			epoch: [Optional] epoch for orbit
+					Default is the first timestep of the timespan
 			name: [Optional] string giving the name of the orbit
 					Default is 'Analytical'
 			astrobodies: [Optional] Flag to calculate Sun and Moon positions at timestamps
@@ -705,13 +709,25 @@ class Orbit:
 			raise exceptions.OutOfRangeError(f"Argument of periapsis, {raan}, is out of "
 										f"range, should be 0 < argp < 360")
 
-		if mean_nu > 360 or mean_nu < 0: 		#noqa: PLR2004
-			logger.error("Mean anomaly, %s, is out of range, should be 0 < mean_nu < 360", mean_nu)
-			raise exceptions.OutOfRangeError(f"Mean anomaly, {mean_nu}, is out of range, "
-										f"should be 0 < mean_nu < 360")
+		if true_nu > 360 or true_nu < 0: 		#noqa: PLR2004
+			logger.error("True anomaly, %s, is out of range, should be 0 < true_nu < 360", true_nu)
+			raise exceptions.OutOfRangeError(f"True anomaly, {true_nu}, is out of range, "
+										f"should be 0 < true_nu < 360")
+
+		if epoch is None:
+			epoch = timespan[0]
+		if isinstance(epoch, dt.datetime):
+			astropy_epoch = astropyTime(epoch, scale='utc')
+		else:
+			logger.error("epoch, %s must be of type dt.datetime|astropyTime but"
+											" is of type %s", epoch, type(epoch))
+			raise TypeError(f"epoch, {epoch} must be of type "
+						f"dt.datetime|astropyTime but is of type {type(epoch)}")
 
 		attr_dct = _createEmptyOrbitAttrDict()
 
+
+
 		logger.info("Creating analytical orbit")
 		orb = hapsiraOrbit.from_classical(central_body,
 											a * astropy_units.one * astropy_units.km,
@@ -719,7 +735,9 @@ class Orbit:
 											inc * astropy_units.one * astropy_units.deg,
 											raan * astropy_units.one * astropy_units.deg,
 											argp * astropy_units.one * astropy_units.deg,
-											mean_nu * astropy_units.one * astropy_units.deg)
+											true_nu * astropy_units.one * astropy_units.deg,
+											astropy_epoch
+											)
 
 
 		logger.info("Creating ephemeris for orbit, using timespan")

{spherapy-0.2.1 → spherapy-0.3.0}/spherapy/timespan.py

@@ -6,7 +6,7 @@ This module provides:
 import datetime as dt
 import logging
 
-from typing import cast
+from typing import cast, overload
 from typing_extensions import Self
 
 from astropy.time import Time as astropyTime
@@ -112,6 +112,16 @@ class TimeSpan:
 		"""Returns the internal _timearr when the TimeSpan is called."""
 		return self._timearr
 
+	@overload
+	def __getitem__(self, idx: None) -> np.ndarray[tuple[int], np.dtype[np.datetime64]]: ...
+
+	@overload
+	def __getitem__(self, idx: int | np.integer) -> dt.datetime: ...
+
+	@overload
+	def __getitem__(self, idx: slice | list[int] | tuple[int, ...] | np.ndarray) \
+						-> np.ndarray[tuple[int], np.dtype[np.datetime64]]: ...
+
 	def __getitem__(self, idx:None|int|np.integer|tuple|list|np.ndarray|slice=None) \
 						-> None|dt.datetime|np.ndarray[tuple[int], np.dtype[np.datetime64]]: 	# noqa: PLR0911
 		"""Returns an index or slice of the TimeSpan as an array of datetime objects."""
@@ -124,7 +134,7 @@ class TimeSpan:
 				return self._timearr[idx[0]:idx[1]]
 			return self._timearr[idx[0]:idx[1]:idx[2]]
 		if isinstance(idx, list):
-			return self._timearr[[idx]]
+			return self._timearr[idx]
 		if isinstance(idx, np.ndarray):
 			return self._timearr[idx]
 		if isinstance(idx,slice):

{spherapy-0.2.1 → spherapy-0.3.0}/spherapy/util/epoch_u.py

@@ -147,3 +147,66 @@ def getStoredEpochs(tle_path:pathlib.Path) -> None|tuple[dt.datetime, dt.datetim
 	last_epoch_dt = epoch2datetime(last_tle_line_1['fields'][3])
 
 	return (first_epoch_dt, last_epoch_dt)
+
+def getAllStoredEpochs(tle_path:pathlib.Path) -> None|list[dt.datetime]:
+	"""Return the all TLE epochs for tle_path.
+
+	Args:
+		tle_path: tle file
+
+	Returns:
+		list of datetime object equivalent to the TLE epoch for each TLE
+		None if no spacetrack tle stored for sat_id
+	"""
+	if not tle_path.exists():
+		return None
+
+	with tle_path.open('r') as fp:
+		lines = fp.readlines()
+
+	tle_epochs_dt = []
+	for ii in range(1,len(lines),3):
+		tle_line = elements_u.split3LELineIntoFields(lines[ii])
+		tle_epochs_dt.append(epoch2datetime(tle_line['fields'][3]))
+
+
+	return tle_epochs_dt
+
+def getStoredTLEByIdx(tle_path:pathlib.Path,
+						idx_list:int|list[int],
+						string_only:bool=True) \
+							-> list[dict[int, elements_u.ElementsLineDict]]|list[str]|None:
+	"""Return the TLE at the Idx within tle_path specifed by idx_list.
+
+	Args:
+		tle_path: tle file
+		idx_list: list of TLE indices within tle_path
+		string_only: if true, return only the raw TLE string,
+					if false returns a dict of each field within each line
+
+	Returns:
+		list of tle_data
+	"""
+	if not tle_path.exists():
+		return None
+
+	if isinstance(idx_list, int):
+		idx_list = [idx_list]
+
+	with tle_path.open('r') as fp:
+		lines = fp.readlines()
+
+	tles = []
+	for idx in idx_list:
+		tle_line_0 = elements_u.split3LELineIntoFields(lines[idx*3+0])
+		tle_line_1 = elements_u.split3LELineIntoFields(lines[idx*3+1])
+		tle_line_2 = elements_u.split3LELineIntoFields(lines[idx*3+2])
+
+		if string_only:
+			tle_data = f"{tle_line_0['line_str']}{tle_line_1['line_str']}{tle_line_2['line_str']}"
+		else:
+			tle_data = {0:tle_line_0, 1:tle_line_1, 2:tle_line_2} 	#type:ignore
+
+		tles.append(tle_data)
+
+	return tles

{spherapy-0.2.1 → spherapy-0.3.0/spherapy.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: spherapy
-Version: 0.2.1
+Version: 0.3.0
 Summary: An orbital propagator wrapper and TLE fetcher
 Author-email: Robert Mearns <rz.mearns@gmail.com>
 Maintainer-email: Robert Mearns <rz.mearns@gmail.com>
@@ -87,7 +87,7 @@ o = spherapy.orbit.Orbit.fromAnalyticalOrbitalParam(timespan, body='Earth',
 					 inc=0,
 					 raan=0,
 					 argp=0,
-					 mean_nu=0,
+					 true_nu=0,
 					 name='My Analytical Orbit',
 					 astrobodies=True)
 ```  
@@ -115,7 +115,7 @@ o = spherapy.orbit.Orbit.fromAnalyticalOrbitalParam(timespan, body='Earth',
 					 inc=0,
 					 raan=0,
 					 argp=0,
-					 mean_nu=0,
+					 true_nu=0,
 					 name='My Analytical Orbit',
 					 astrobodies=True)
 ```

{spherapy-0.2.1 → spherapy-0.3.0}/tests/spherapy/test_orbit.py

@@ -1,3 +1,5 @@
+from numpy.typing import NDArray
+
 import pytest
 from pytest_check import check
 import pathlib
@@ -44,8 +46,8 @@ def propagationData(pytestFillPackagedData:None) -> dict: 			#noqa: ARG001
 	data['o_ftle_astro'] = orbit.Orbit.fromPropagatedOrbitalParam(data['t'], a=(6378 + 600), ecc=0, inc=45, raan=0, argp=0, mean_nu=0, astrobodies=True)
 
 	# Analytic from orbital param
-	data['o_analytical'] = orbit.Orbit.fromAnalyticalOrbitalParam(data['t'], a=(6378 + 600), ecc=0, inc=45, raan=0, argp=0, mean_nu=0)
-	data['o_analytical_astro'] = orbit.Orbit.fromAnalyticalOrbitalParam(data['t'], a=(6378 + 600), ecc=0, inc=45, raan=0, argp=0, mean_nu=0, astrobodies=True)
+	data['o_analytical'] = orbit.Orbit.fromAnalyticalOrbitalParam(data['t'], a=(6378 + 600), ecc=0, inc=45, raan=0, argp=0, true_nu=0)
+	data['o_analytical_astro'] = orbit.Orbit.fromAnalyticalOrbitalParam(data['t'], a=(6378 + 600), ecc=0, inc=45, raan=0, argp=0, true_nu=0, astrobodies=True)
 
 	# From list of position
 	data['o_poslist'] = orbit.Orbit.fromListOfPositions(data['t'], data['pos'])
@@ -554,10 +556,47 @@ def test_analyticalValidity():
 		t0 = dt.datetime(2021, 1, 1, 0, 0, 1)
 		t = timespan.TimeSpan(t0, '1S', '180M')
 		a = 6378+600
-		o = orbit.Orbit.fromAnalyticalOrbitalParam(t, a=a, ecc=0, inc=45, raan=0, argp=0, mean_nu=0)
+		o = orbit.Orbit.fromAnalyticalOrbitalParam(t, a=a, ecc=0, inc=45, raan=0, argp=0, true_nu=0)
 
 		# Circular orbit should have the same semi-major for its duration
 		check.is_true(np.all(np.isclose(np.linalg.norm(o.pos, axis=1), a)))
 		# Circular orbit should have the same orbital speed for its duration
 		speed = orbital_u.calcOrbitalVel(a * 1e3, np.array((a * 1e3, 0, 0)))
 		check.is_true(np.all(np.isclose(np.linalg.norm(o.vel, axis=1), speed)))
+
+
+def test_fromAnalyticalOrbitalParams_epoch():
+		'''
+		Test that the epoch argument is set to the correct default value
+		'''
+
+		t0 = dt.datetime.fromisoformat('2026-03-20T14:46:00+00:00') # this is the vernal equinox so sun should be at raan
+		t = timespan.TimeSpan(t0, '1S', '1S')
+		o = orbit.Orbit.fromAnalyticalOrbitalParam(t, a=6378+600, ecc=0.4, inc=45, raan=0, argp=0, true_nu=0)
+
+		def unit_vector(v : NDArray) -> NDArray:
+			return v/np.linalg.norm(v)
+
+		# an orbit with raan=argp=true_nu=0 with epoch at vernal equinox should be at the sub solar point
+		check.is_true(np.all(np.isclose(unit_vector(o.pos[0]), unit_vector(o.sun_pos[0]), atol=0.01)))
+
+def test_fromAnalyiticalOrbitalParams_epoch_timespan_sampling():
+		'''
+		test that the epoch is kept consistent over different timespans when specified
+		'''
+
+		t0 = dt.datetime.fromisoformat('2026-01-12T23:34:18+00:00')
+
+		ts1 = timespan.TimeSpan(t0, '1M', '180M')
+		ts2 = timespan.TimeSpan(t0 + dt.timedelta(minutes=1), '2M', '180M')
+
+		o1 = orbit.Orbit.fromAnalyticalOrbitalParam(ts1, a=6378+400, ecc=0.2, inc=10, raan=18, argp=76, true_nu=23, epoch=ts1[0])
+		o2 = orbit.Orbit.fromAnalyticalOrbitalParam(ts2, a=6378+400, ecc=0.2, inc=10, raan=18, argp=76, true_nu=23, epoch=ts1[0])
+
+
+		check.is_true(
+			np.all(np.isclose(
+					o1.pos[1::2,:],
+					o2.pos[:-1,:],
+					atol=0.01
+				)))

{spherapy-0.2.1 → spherapy-0.3.0}/tests/spherapy/test_timespan.py

@@ -61,6 +61,81 @@ def test_init():
 	check.equal(first_decade[-1], dt.datetime(2006,9,8, tzinfo=dt.timezone.utc))
 	check.equal(minimum_ts[-1], t0.replace(tzinfo=dt.timezone.utc) + dt.timedelta(seconds=1))
 
+def test_getitem():
+	t0 = dt.datetime(2013,5,17,11,45,23, tzinfo=dt.timezone.utc)
+	ts = TimeSpan(t0, '1S', '1M')
+
+	# NONE
+	item = ts[None]
+	check.is_true(isinstance(item, np.ndarray))
+	check.is_true(np.array_equal(item, ts._timearr))
+
+	# int
+	item = ts[1]
+	check.is_true(isinstance(item, dt.datetime))
+	check.equal(item, t0 + dt.timedelta(seconds=1))
+
+	with check.raises(IndexError):
+		item = ts[70]
+
+	# slice
+	item = ts[1:4]
+	check.is_true(isinstance(item, np.ndarray))
+	check.equal(len(item), 3)
+	for rdt, edt in zip(item, [t0 + dt.timedelta(seconds=i) for i in range(1,4)]):
+		check.equal(rdt, edt)
+
+	# check that slice correctly crop the interval to valid range
+	item = ts[30:82]
+	check.equal(len(item), 31)
+
+	# list[int]
+	item = ts[[3,7,4]]
+	check.is_true(isinstance(item, np.ndarray))
+	check.equal(len(item), 3)
+	for rdt, edt in zip(item, [t0 + dt.timedelta(seconds=i) for i in [3,7,4]]):
+		check.equal(rdt, edt)
+
+	with check.raises(IndexError):
+		item = ts[[1,70]]
+
+	# np.ndarray
+	item = ts[np.array([3,7,4])]
+	check.is_true(isinstance(item, np.ndarray))
+	check.equal(len(item), 3)
+	for rdt, edt in zip(item, [t0 + dt.timedelta(seconds=i) for i in [3,7,4]]):
+		check.equal(rdt, edt)
+
+	with check.raises(IndexError):
+		item = ts[np.ndarray([1,70])]
+
+	# 2-tuple
+	item = ts[(5,20)]
+	check.is_true(isinstance(item, np.ndarray))
+	check.equal(len(item), 15)
+	for rdt, edt in zip(item, [t0 + dt.timedelta(seconds=i) for i in range(5,20)]):
+		check.equal(rdt, edt)
+
+	# check that 2-tuple correctly crop the interval to valid range
+	item = ts[(55,65)]
+	check.equal(len(item), 6)
+
+	# 3-tuple
+	item = ts[(5,20,3)]
+	check.is_true(isinstance(item, np.ndarray))
+	check.equal(len(item), 5)
+	for rdt, edt in zip(item, [t0 + dt.timedelta(seconds=i) for i in range(5,20,3)]):
+		check.equal(rdt, edt)
+
+	# check that 2-tuple correctly crop the interval to valid range
+	item = ts[(44, 62, 8)]
+	check.equal(len(item), 3)
+
+	with check.raises(TypeError):
+		item = ts[0.0]
+
+
+
 def test_len():
 	t0 = dt.datetime(2000,1,1,12,4,5)
 

spherapy-0.2.1/CHANGELOG.md

@@ -1,15 +0,0 @@
-The change log should include
-- theme of the upversion
-- changes in API
-- changes in model behaviour
-
-# v0.2.1
-- minor bug fixes to the API for pulling TLEs from Celestrak
-
-# v0.2.0
-- initial release to pypi
-- timespan object
-- orbit object
-- orbit object creation from: TLE, propagated orbital parameters, analytical orbital parameters, list of positions
-- TLE updater, pulls requested TLEs from spacetrack, stores all TLEs for that satellite in a saved file
-- TLE updater falls back to celestrak if no credentials provided