satkit 0.14.3__tar.gz → 0.16.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (126) hide show
  1. {satkit-0.14.3 → satkit-0.16.0}/Cargo.toml +1 -1
  2. {satkit-0.14.3/python/satkit.egg-info → satkit-0.16.0}/PKG-INFO +12 -5
  3. {satkit-0.14.3 → satkit-0.16.0}/README.md +11 -4
  4. {satkit-0.14.3 → satkit-0.16.0}/pyproject.toml +1 -1
  5. {satkit-0.14.3 → satkit-0.16.0}/python/Cargo.toml +1 -1
  6. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/__init__.py +6 -6
  7. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/__init__.pyi +11 -1
  8. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/density.pyi +0 -2
  9. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/frametransform.pyi +257 -1
  10. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/jplephem.pyi +0 -1
  11. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/planets.pyi +0 -1
  12. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/satkit.pyi +587 -58
  13. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/utils.pyi +0 -3
  14. {satkit-0.14.3 → satkit-0.16.0/python/satkit.egg-info}/PKG-INFO +12 -5
  15. {satkit-0.14.3 → satkit-0.16.0}/python/satkit.egg-info/SOURCES.txt +5 -0
  16. {satkit-0.14.3 → satkit-0.16.0}/python/src/lib.rs +17 -0
  17. satkit-0.16.0/python/src/pyframes.rs +106 -0
  18. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyframetransform.rs +195 -0
  19. {satkit-0.14.3 → satkit-0.16.0}/python/src/pygravity.rs +4 -4
  20. satkit-0.16.0/python/src/pyomm.rs +75 -0
  21. {satkit-0.14.3 → satkit-0.16.0}/python/src/pypropagate.rs +7 -9
  22. {satkit-0.14.3 → satkit-0.16.0}/python/src/pypropresult.rs +3 -2
  23. {satkit-0.14.3 → satkit-0.16.0}/python/src/pypropsettings.rs +37 -1
  24. satkit-0.16.0/python/src/pysatproperties.rs +210 -0
  25. satkit-0.16.0/python/src/pysatstate.rs +509 -0
  26. satkit-0.16.0/python/src/pythrust.rs +102 -0
  27. {satkit-0.14.3 → satkit-0.16.0}/python/src/pytle.rs +31 -0
  28. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyutils.rs +15 -0
  29. {satkit-0.14.3 → satkit-0.16.0}/src/earth_orientation_params.rs +4 -10
  30. {satkit-0.14.3 → satkit-0.16.0}/src/earthgravity.rs +8 -8
  31. satkit-0.16.0/src/frames.rs +166 -0
  32. satkit-0.16.0/src/frametransform/mod.rs +1084 -0
  33. {satkit-0.14.3 → satkit-0.16.0}/src/lambert.rs +1 -0
  34. {satkit-0.14.3 → satkit-0.16.0}/src/lib.rs +8 -3
  35. {satkit-0.14.3 → satkit-0.16.0}/src/nrlmsise.rs +19 -7
  36. {satkit-0.14.3 → satkit-0.16.0}/src/omm/mod.rs +44 -5
  37. {satkit-0.14.3 → satkit-0.16.0}/src/omm/xml.rs +5 -5
  38. satkit-0.16.0/src/orbitprop/mod.rs +22 -0
  39. satkit-0.16.0/src/orbitprop/ode/gauss_jackson.rs +1321 -0
  40. satkit-0.16.0/src/orbitprop/ode/mod.rs +14 -0
  41. {satkit-0.14.3 → satkit-0.16.0}/src/orbitprop/precomputed.rs +43 -9
  42. {satkit-0.14.3 → satkit-0.16.0}/src/orbitprop/propagator.rs +484 -17
  43. {satkit-0.14.3 → satkit-0.16.0}/src/orbitprop/satproperties.rs +44 -9
  44. satkit-0.16.0/src/orbitprop/satstate.rs +1189 -0
  45. {satkit-0.14.3 → satkit-0.16.0}/src/orbitprop/settings.rs +79 -16
  46. satkit-0.16.0/src/orbitprop/thrust.rs +112 -0
  47. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/sgp4_impl.rs +2 -2
  48. {satkit-0.14.3 → satkit-0.16.0}/src/time/timelike.rs +2 -2
  49. {satkit-0.14.3 → satkit-0.16.0}/src/tle/fitting.rs +8 -8
  50. {satkit-0.14.3 → satkit-0.16.0}/src/tle/mod.rs +30 -2
  51. satkit-0.14.3/python/src/pyframes.rs +0 -60
  52. satkit-0.14.3/python/src/pysatproperties.rs +0 -120
  53. satkit-0.14.3/python/src/pysatstate.rs +0 -331
  54. satkit-0.14.3/src/frames.rs +0 -54
  55. satkit-0.14.3/src/frametransform/mod.rs +0 -560
  56. satkit-0.14.3/src/orbitprop/mod.rs +0 -16
  57. satkit-0.14.3/src/orbitprop/satstate.rs +0 -394
  58. {satkit-0.14.3 → satkit-0.16.0}/LICENSE +0 -0
  59. {satkit-0.14.3 → satkit-0.16.0}/MANIFEST.in +0 -0
  60. {satkit-0.14.3 → satkit-0.16.0}/python/build.rs +0 -0
  61. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/moon.pyi +0 -0
  62. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/py.typed +0 -0
  63. {satkit-0.14.3 → satkit-0.16.0}/python/satkit/sun.pyi +0 -0
  64. {satkit-0.14.3 → satkit-0.16.0}/python/satkit.egg-info/dependency_links.txt +0 -0
  65. {satkit-0.14.3 → satkit-0.16.0}/python/satkit.egg-info/requires.txt +0 -0
  66. {satkit-0.14.3 → satkit-0.16.0}/python/satkit.egg-info/top_level.txt +0 -0
  67. {satkit-0.14.3 → satkit-0.16.0}/python/src/mod_utils.rs +0 -0
  68. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyconsts.rs +0 -0
  69. {satkit-0.14.3 → satkit-0.16.0}/python/src/pydensity.rs +0 -0
  70. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyduration.rs +0 -0
  71. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyinstant.rs +0 -0
  72. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyitrfcoord.rs +0 -0
  73. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyjplephem.rs +0 -0
  74. {satkit-0.14.3 → satkit-0.16.0}/python/src/pykepler.rs +0 -0
  75. {satkit-0.14.3 → satkit-0.16.0}/python/src/pylambert.rs +0 -0
  76. {satkit-0.14.3 → satkit-0.16.0}/python/src/pylpephem_moon.rs +0 -0
  77. {satkit-0.14.3 → satkit-0.16.0}/python/src/pylpephem_planets.rs +0 -0
  78. {satkit-0.14.3 → satkit-0.16.0}/python/src/pylpephem_sun.rs +0 -0
  79. {satkit-0.14.3 → satkit-0.16.0}/python/src/pympsuccess.rs +0 -0
  80. {satkit-0.14.3 → satkit-0.16.0}/python/src/pynrlmsise.rs +0 -0
  81. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyquaternion.rs +0 -0
  82. {satkit-0.14.3 → satkit-0.16.0}/python/src/pysgp4.rs +0 -0
  83. {satkit-0.14.3 → satkit-0.16.0}/python/src/pysolarsystem.rs +0 -0
  84. {satkit-0.14.3 → satkit-0.16.0}/python/src/pyukf.rs +0 -0
  85. {satkit-0.14.3 → satkit-0.16.0}/setup.cfg +0 -0
  86. {satkit-0.14.3 → satkit-0.16.0}/src/consts.rs +0 -0
  87. {satkit-0.14.3 → satkit-0.16.0}/src/frametransform/ierstable.rs +0 -0
  88. {satkit-0.14.3 → satkit-0.16.0}/src/frametransform/qcirs2gcrs.rs +0 -0
  89. {satkit-0.14.3 → satkit-0.16.0}/src/itrfcoord.rs +0 -0
  90. {satkit-0.14.3 → satkit-0.16.0}/src/jplephem.rs +0 -0
  91. {satkit-0.14.3 → satkit-0.16.0}/src/kepler.rs +0 -0
  92. {satkit-0.14.3 → satkit-0.16.0}/src/lpephem/mod.rs +0 -0
  93. {satkit-0.14.3 → satkit-0.16.0}/src/lpephem/moon.rs +0 -0
  94. {satkit-0.14.3 → satkit-0.16.0}/src/lpephem/planets.rs +0 -0
  95. {satkit-0.14.3 → satkit-0.16.0}/src/lpephem/sun.rs +0 -0
  96. {satkit-0.14.3 → satkit-0.16.0}/src/mathtypes.rs +0 -0
  97. {satkit-0.14.3 → satkit-0.16.0}/src/orbitprop/drag.rs +0 -0
  98. {satkit-0.14.3 → satkit-0.16.0}/src/orbitprop/point_gravity.rs +0 -0
  99. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/dpper.rs +0 -0
  100. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/dscom.rs +0 -0
  101. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/dsinit.rs +0 -0
  102. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/dspace.rs +0 -0
  103. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/getgravconst.rs +0 -0
  104. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/initl.rs +0 -0
  105. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/mod.rs +0 -0
  106. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/satrec.rs +0 -0
  107. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/sgp4_lowlevel.rs +0 -0
  108. {satkit-0.14.3 → satkit-0.16.0}/src/sgp4/sgp4init.rs +0 -0
  109. {satkit-0.14.3 → satkit-0.16.0}/src/solar_cycle_forecast.rs +0 -0
  110. {satkit-0.14.3 → satkit-0.16.0}/src/solarsystem.rs +0 -0
  111. {satkit-0.14.3 → satkit-0.16.0}/src/spaceweather.rs +0 -0
  112. {satkit-0.14.3 → satkit-0.16.0}/src/time/chrono.rs +0 -0
  113. {satkit-0.14.3 → satkit-0.16.0}/src/time/duration.rs +0 -0
  114. {satkit-0.14.3 → satkit-0.16.0}/src/time/instant.rs +0 -0
  115. {satkit-0.14.3 → satkit-0.16.0}/src/time/instant_err.rs +0 -0
  116. {satkit-0.14.3 → satkit-0.16.0}/src/time/instant_ops.rs +0 -0
  117. {satkit-0.14.3 → satkit-0.16.0}/src/time/instantparse.rs +0 -0
  118. {satkit-0.14.3 → satkit-0.16.0}/src/time/mod.rs +0 -0
  119. {satkit-0.14.3 → satkit-0.16.0}/src/time/tests.rs +0 -0
  120. {satkit-0.14.3 → satkit-0.16.0}/src/time/timescale.rs +0 -0
  121. {satkit-0.14.3 → satkit-0.16.0}/src/time/weekday.rs +0 -0
  122. {satkit-0.14.3 → satkit-0.16.0}/src/utils/datadir.rs +0 -0
  123. {satkit-0.14.3 → satkit-0.16.0}/src/utils/download.rs +0 -0
  124. {satkit-0.14.3 → satkit-0.16.0}/src/utils/mod.rs +0 -0
  125. {satkit-0.14.3 → satkit-0.16.0}/src/utils/test.rs +0 -0
  126. {satkit-0.14.3 → satkit-0.16.0}/src/utils/update_data.rs +0 -0
@@ -3,7 +3,7 @@ members = [".", "python"]
3
3
 
4
4
  [package]
5
5
  name = "satkit"
6
- version = "0.14.3"
6
+ version = "0.16.0"
7
7
  edition = "2021"
8
8
  description = "Satellite Toolkit"
9
9
  readme = "README.md"
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: satkit
3
- Version: 0.14.3
3
+ Version: 0.16.0
4
4
  Summary: Satellite Orbital Dynamics Toolkit
5
5
  Author-email: Steven Michael <ssmichael@gmail.com>
6
6
  Maintainer-email: Steven Michael <ssmichael@gmail.com>
@@ -92,9 +92,10 @@ r0 = 6378e3 + 500e3 # 500 km altitude
92
92
  v0 = np.sqrt(sk.consts.mu_earth / r0)
93
93
 
94
94
  settings = sk.propsettings(
95
- gravity_model=sk.gravmodel.jgm3,
95
+ gravity_model=sk.gravmodel.egm96, # default; also jgm3, jgm2, itugrace16
96
96
  gravity_degree=8,
97
- integrator=sk.integrator.rkv98, # default; also rkv87, rkv65, rkts54
97
+ integrator=sk.integrator.rkv98, # default; also rkv87, rkv65, rkts54,
98
+ # gauss_jackson8 (fixed-step multistep)
98
99
  )
99
100
 
100
101
  result = sk.propagate(
@@ -147,10 +148,16 @@ Plus ENU, NED, and geodesic distance (Vincenty) utilities.
147
148
 
148
149
  ### Orbit Propagation
149
150
 
150
- - **Numerical** -- Selectable adaptive Runge-Kutta integrators (9(8), 8(7), 6(5), 5(4)) with dense output, state transition matrix, and configurable force models
151
+ - **Numerical** -- Selectable adaptive Runge-Kutta integrators (9(8), 8(7), 6(5), 5(4)) plus RODAS4 (stiff) and Gauss-Jackson 8 (fixed-step multistep for high-precision long-duration propagation), with dense output, state transition matrix, and configurable force models
151
152
  - **SGP4** -- Standard TLE/OMM propagator with TLE fitting from precision states
152
153
  - **Keplerian** -- Analytical two-body propagation
153
154
 
155
+ ### Orbit Maneuvers
156
+
157
+ - **Impulsive maneuvers** -- Instantaneous delta-v applied at a scheduled time during propagation. Supported frames: GCRF (inertial), RTN (radial/tangential/normal — the CCSDS OEM convention, also exposed as `RSW` and `RIC` aliases), NTW (normal/tangent/cross-track — natural for prograde burns on eccentric orbits), and LVLH (Local Vertical / Local Horizontal). Ergonomic helpers `add_prograde` / `add_retrograde` / `add_radial` / `add_normal` for common scalar-magnitude burns.
158
+ - **Continuous thrust** -- Constant-acceleration thrust arcs over time windows in any of the frames above, integrated directly into the force model
159
+ - **Automatic segmentation** -- Propagation through maneuver sequences is handled transparently, including backward propagation
160
+
154
161
  ### Force Models
155
162
 
156
163
  - **Earth gravity**: JGM2, JGM3, EGM96, ITU GRACE16 (spherical harmonics up to degree/order 360)
@@ -221,7 +228,7 @@ Then run tests with the environment variables pointing to the downloaded directo
221
228
  SATKIT_DATA=astro-data SATKIT_TESTVEC_ROOT=satkit-testvecs cargo test
222
229
 
223
230
  # Python tests
224
- SATKIT_DATA=astro-data SATKIT_TESTVEC_ROOT=satkit-testvecs pytest python/test/test.py
231
+ SATKIT_DATA=astro-data SATKIT_TESTVEC_ROOT=satkit-testvecs pytest python/test/
225
232
  ```
226
233
 
227
234
  ## Documentation
@@ -68,9 +68,10 @@ r0 = 6378e3 + 500e3 # 500 km altitude
68
68
  v0 = np.sqrt(sk.consts.mu_earth / r0)
69
69
 
70
70
  settings = sk.propsettings(
71
- gravity_model=sk.gravmodel.jgm3,
71
+ gravity_model=sk.gravmodel.egm96, # default; also jgm3, jgm2, itugrace16
72
72
  gravity_degree=8,
73
- integrator=sk.integrator.rkv98, # default; also rkv87, rkv65, rkts54
73
+ integrator=sk.integrator.rkv98, # default; also rkv87, rkv65, rkts54,
74
+ # gauss_jackson8 (fixed-step multistep)
74
75
  )
75
76
 
76
77
  result = sk.propagate(
@@ -123,10 +124,16 @@ Plus ENU, NED, and geodesic distance (Vincenty) utilities.
123
124
 
124
125
  ### Orbit Propagation
125
126
 
126
- - **Numerical** -- Selectable adaptive Runge-Kutta integrators (9(8), 8(7), 6(5), 5(4)) with dense output, state transition matrix, and configurable force models
127
+ - **Numerical** -- Selectable adaptive Runge-Kutta integrators (9(8), 8(7), 6(5), 5(4)) plus RODAS4 (stiff) and Gauss-Jackson 8 (fixed-step multistep for high-precision long-duration propagation), with dense output, state transition matrix, and configurable force models
127
128
  - **SGP4** -- Standard TLE/OMM propagator with TLE fitting from precision states
128
129
  - **Keplerian** -- Analytical two-body propagation
129
130
 
131
+ ### Orbit Maneuvers
132
+
133
+ - **Impulsive maneuvers** -- Instantaneous delta-v applied at a scheduled time during propagation. Supported frames: GCRF (inertial), RTN (radial/tangential/normal — the CCSDS OEM convention, also exposed as `RSW` and `RIC` aliases), NTW (normal/tangent/cross-track — natural for prograde burns on eccentric orbits), and LVLH (Local Vertical / Local Horizontal). Ergonomic helpers `add_prograde` / `add_retrograde` / `add_radial` / `add_normal` for common scalar-magnitude burns.
134
+ - **Continuous thrust** -- Constant-acceleration thrust arcs over time windows in any of the frames above, integrated directly into the force model
135
+ - **Automatic segmentation** -- Propagation through maneuver sequences is handled transparently, including backward propagation
136
+
130
137
  ### Force Models
131
138
 
132
139
  - **Earth gravity**: JGM2, JGM3, EGM96, ITU GRACE16 (spherical harmonics up to degree/order 360)
@@ -197,7 +204,7 @@ Then run tests with the environment variables pointing to the downloaded directo
197
204
  SATKIT_DATA=astro-data SATKIT_TESTVEC_ROOT=satkit-testvecs cargo test
198
205
 
199
206
  # Python tests
200
- SATKIT_DATA=astro-data SATKIT_TESTVEC_ROOT=satkit-testvecs pytest python/test/test.py
207
+ SATKIT_DATA=astro-data SATKIT_TESTVEC_ROOT=satkit-testvecs pytest python/test/
201
208
  ```
202
209
 
203
210
  ## Documentation
@@ -9,7 +9,7 @@ requires-python = ">= 3.10"
9
9
  authors = [{ name = "Steven Michael", email = "ssmichael@gmail.com" }]
10
10
  maintainers = [{ name = "Steven Michael", email = "ssmichael@gmail.com" }]
11
11
  readme = "README.md"
12
- version = "0.14.3"
12
+ version = "0.16.0"
13
13
  license = "MIT"
14
14
  description = "Satellite Orbital Dynamics Toolkit"
15
15
  keywords = [
@@ -1,6 +1,6 @@
1
1
  [package]
2
2
  name = "satkit-python"
3
- version = "0.14.3"
3
+ version = "0.16.0"
4
4
  edition = "2021"
5
5
  publish = false
6
6
 
@@ -20,14 +20,14 @@ if not utils.datafiles_exist(): # type: ignore
20
20
  pass
21
21
 
22
22
  if not utils.datafiles_exist(): # type: ignore
23
- print(f"Could not find necessary data files.", file=sys.stderr)
24
- print(f"Install satkit-data package via pypi or", file=sys.stderr)
23
+ print("Could not find necessary data files.", file=sys.stderr)
24
+ print("Install satkit-data package via pypi or", file=sys.stderr)
25
25
  print(
26
- f'Run "satkit.utils.update_datafiles()" to download necessary files',
26
+ 'Run "satkit.utils.update_datafiles()" to download necessary files',
27
27
  file=sys.stderr,
28
28
  )
29
- print(f"This includes JPL ephemeris, gravity, space weather, ", file=sys.stderr)
29
+ print("This includes JPL ephemeris, gravity, space weather, ", file=sys.stderr)
30
30
  print(
31
- f"Earth orientation parameters, leap seconds, and coefficients", file=sys.stderr
31
+ "Earth orientation parameters, leap seconds, and coefficients", file=sys.stderr
32
32
  )
33
- print(f"for inertial-to-Earth-fixed transforms", file=sys.stderr)
33
+ print("for inertial-to-Earth-fixed transforms", file=sys.stderr)
@@ -14,14 +14,22 @@ __all__ = [
14
14
  "time",
15
15
  "duration",
16
16
  "timescale",
17
+ "weekday",
17
18
  "quaternion",
19
+ "frame",
18
20
  "sgp4",
21
+ "sgp4_error",
22
+ "sgp4_gravconst",
23
+ "sgp4_opsmode",
19
24
  "gravmodel",
20
25
  "gravity",
26
+ "gravity_and_partials",
27
+ "nrlmsise00",
21
28
  "density",
22
29
  "solarsystem",
23
30
  "TLE",
24
31
  "itrfcoord",
32
+ "geodetic",
25
33
  "kepler",
26
34
  "consts",
27
35
  "frametransform",
@@ -35,8 +43,10 @@ __all__ = [
35
43
  "lambert",
36
44
  "propsettings",
37
45
  "integrator",
38
- "satproperties_static",
46
+ "satproperties",
47
+ "thrust",
39
48
  "propresult",
40
49
  "propstats",
50
+ "omm_from_url",
41
51
  "__version__",
42
52
  ]
@@ -6,8 +6,6 @@ Currently only contains NRL MSISE-00 air density model
6
6
 
7
7
  from __future__ import annotations
8
8
  import typing
9
- import numpy.typing as npt
10
- import numpy as np
11
9
 
12
10
  import satkit
13
11
 
@@ -15,7 +15,7 @@ import numpy.typing as npt
15
15
  import numpy as np
16
16
  import datetime
17
17
 
18
- from .satkit import time, quaternion
18
+ from .satkit import time, quaternion, frame
19
19
 
20
20
  @typing.overload
21
21
  def gmst(tm: time | datetime.datetime) -> float:
@@ -384,6 +384,12 @@ def qgcrf2itrf_approx(
384
384
 
385
385
  Notes:
386
386
  - Accurate to approx. 1 arcsec
387
+ - **Velocity transforms**: this quaternion rotates *position* vectors
388
+ between GCRF and ITRF but **is not sufficient for velocity** on
389
+ its own. ITRF is a rotating frame, so the velocity transform
390
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
391
+ Use :func:`gcrf_to_itrf_state` / :func:`itrf_to_gcrf_state` for
392
+ full state (position + velocity) transforms.
387
393
 
388
394
  Args:
389
395
  tm (satkit.time | datetime.datetime): Time[s] at which to calculate the quaternion
@@ -432,6 +438,12 @@ def qitrf2gcrf_approx(
432
438
 
433
439
  Notes:
434
440
  - Accurate to approx. 1 arcsec
441
+ - **Velocity transforms**: this quaternion rotates *position* vectors
442
+ between ITRF and GCRF but **is not sufficient for velocity** on
443
+ its own. ITRF is a rotating frame, so the velocity transform
444
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
445
+ Use :func:`itrf_to_gcrf_state` / :func:`gcrf_to_itrf_state` for
446
+ full state (position + velocity) transforms.
435
447
 
436
448
  Args:
437
449
  tm (satkit.time | datetime.datetime): Time[s] at which to calculate the quaternion
@@ -483,6 +495,12 @@ def qgcrf2itrf(
483
495
  - See IERS Technical Note 36, Chapter 5
484
496
  - Does not include solid tides, ocean tides
485
497
  - Very computationally expensive
498
+ - **Velocity transforms**: this quaternion rotates *position* vectors
499
+ between ITRF and GCRF but **is not sufficient for velocity** on
500
+ its own. ITRF is a rotating frame, so the velocity transform
501
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
502
+ Use :func:`itrf_to_gcrf_state` / :func:`gcrf_to_itrf_state` for
503
+ full state (position + velocity) transforms.
486
504
 
487
505
  Args:
488
506
  tm (satkit.time | datetime.datetime): Time[s] at which to calculate the quaternion
@@ -515,6 +533,12 @@ def qgcrf2itrf(
515
533
  - See IERS Technical Note 36, Chapter 5
516
534
  - Does not include solid tides, ocean tides
517
535
  - Very computationally expensive
536
+ - **Velocity transforms**: this quaternion rotates *position* vectors
537
+ between ITRF and GCRF but **is not sufficient for velocity** on
538
+ its own. ITRF is a rotating frame, so the velocity transform
539
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
540
+ Use :func:`itrf_to_gcrf_state` / :func:`gcrf_to_itrf_state` for
541
+ full state (position + velocity) transforms.
518
542
 
519
543
  Args:
520
544
  tm (npt.ArrayLike[satkit.time] | npt.ArrayLike[datetime.datetime]): Time[s] at which to calculate the quaternion
@@ -532,6 +556,12 @@ def qgcrf2itrf(*args, **kwargs):
532
556
  - See IERS Technical Note 36, Chapter 5
533
557
  - Does not include solid tides, ocean tides
534
558
  - Very computationally expensive
559
+ - **Velocity transforms**: this quaternion rotates *position* vectors
560
+ between ITRF and GCRF but **is not sufficient for velocity** on
561
+ its own. ITRF is a rotating frame, so the velocity transform
562
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
563
+ Use :func:`itrf_to_gcrf_state` / :func:`gcrf_to_itrf_state` for
564
+ full state (position + velocity) transforms.
535
565
 
536
566
  Args:
537
567
  tm (satkit.time | datetime.datetime): Time[s] at which to calculate the quaternion
@@ -564,6 +594,12 @@ def qitrf2gcrf(
564
594
  - See IERS Technical Note 36, Chapter 5
565
595
  - Does not include solid tides, ocean tides
566
596
  - Very computationally expensive
597
+ - **Velocity transforms**: this quaternion rotates *position* vectors
598
+ between ITRF and GCRF but **is not sufficient for velocity** on
599
+ its own. ITRF is a rotating frame, so the velocity transform
600
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
601
+ Use :func:`itrf_to_gcrf_state` / :func:`gcrf_to_itrf_state` for
602
+ full state (position + velocity) transforms.
567
603
 
568
604
  Args:
569
605
  tm (satkit.time datetime.datetime): Time[s] at which to calculate the quaternion
@@ -589,6 +625,12 @@ def qitrf2gcrf(
589
625
  - See IERS Technical Note 36, Chapter 5
590
626
  - Does not include solid tides, ocean tides
591
627
  - Very computationally expensive
628
+ - **Velocity transforms**: this quaternion rotates *position* vectors
629
+ between ITRF and GCRF but **is not sufficient for velocity** on
630
+ its own. ITRF is a rotating frame, so the velocity transform
631
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
632
+ Use :func:`itrf_to_gcrf_state` / :func:`gcrf_to_itrf_state` for
633
+ full state (position + velocity) transforms.
592
634
 
593
635
  Args:
594
636
  tm (npt.ArrayLike[satkit.time] | npt.ArrayLike[datetime.datetime]): Time[s] at which to calculate the quaternion
@@ -606,6 +648,12 @@ def qitrf2gcrf(*args, **kwargs):
606
648
  - See IERS Technical Note 36, Chapter 5
607
649
  - Does not include solid tides, ocean tides
608
650
  - Very computationally expensive
651
+ - **Velocity transforms**: this quaternion rotates *position* vectors
652
+ between ITRF and GCRF but **is not sufficient for velocity** on
653
+ its own. ITRF is a rotating frame, so the velocity transform
654
+ picks up an extra ``omega_earth x r`` term (~470 m/s at LEO).
655
+ Use :func:`itrf_to_gcrf_state` / :func:`gcrf_to_itrf_state` for
656
+ full state (position + velocity) transforms.
609
657
 
610
658
  Args:
611
659
  tm (satkit.time datetime.datetime): Time[s] at which to calculate the quaternion
@@ -729,6 +777,214 @@ def earth_orientation_params(
729
777
  """
730
778
  ...
731
779
 
780
+ @typing.overload
781
+ def qmod2gcrf(tm: time | datetime.datetime) -> quaternion:
782
+ """Quaternion rotating Mean-of-Date (MOD) → GCRF at the given time.
783
+
784
+ Mean-of-Date accounts for precession but not nutation. For the
785
+ precession+nutation pair see :func:`qcirs2gcrf` or :func:`qitrf2gcrf`.
786
+ """
787
+ ...
788
+
789
+ @typing.overload
790
+ def qmod2gcrf(
791
+ tm: npt.ArrayLike | list[time] | list[datetime.datetime],
792
+ ) -> npt.ArrayLike:
793
+ """Quaternion rotating Mean-of-Date (MOD) → GCRF at the given times."""
794
+ ...
795
+
796
+ def qmod2gcrf(*args, **kwargs):
797
+ """Quaternion rotating Mean-of-Date (MOD) → GCRF at the given time(s).
798
+
799
+ Mean-of-Date accounts for precession but not nutation.
800
+ """
801
+ ...
802
+
803
+ @typing.overload
804
+ def qtod2mod_approx(tm: time | datetime.datetime) -> quaternion:
805
+ """Approximate True-of-Date (TOD) → Mean-of-Date (MOD) rotation at the
806
+ given time. Accounts for nutation only.
807
+ """
808
+ ...
809
+
810
+ @typing.overload
811
+ def qtod2mod_approx(
812
+ tm: npt.ArrayLike | list[time] | list[datetime.datetime],
813
+ ) -> npt.ArrayLike:
814
+ """Approximate True-of-Date (TOD) → Mean-of-Date (MOD) rotation at
815
+ the given times. Accounts for nutation only.
816
+ """
817
+ ...
818
+
819
+ def qtod2mod_approx(*args, **kwargs):
820
+ """Approximate True-of-Date (TOD) → Mean-of-Date (MOD) rotation.
821
+
822
+ Accounts for nutation only.
823
+ """
824
+ ...
825
+
826
+ def to_gcrf(
827
+ frame: frame,
828
+ pos: npt.ArrayLike,
829
+ vel: npt.ArrayLike,
830
+ ) -> npt.NDArray[np.float64]:
831
+ """Return the 3x3 DCM that transforms a vector from a satellite-local
832
+ orbital frame into GCRF at the current state.
833
+
834
+ This is the unified dispatch for satellite-local orbital frames.
835
+ Supported values:
836
+
837
+ - ``frame.GCRF`` — returns the 3x3 identity matrix (trivial case)
838
+ - ``frame.LVLH`` — Local Vertical / Local Horizontal
839
+ - ``frame.RTN`` — Radial / In-track / Cross-track (= RSW = RTN)
840
+ - ``frame.NTW`` — Normal-to-velocity / Tangent / Cross-track
841
+
842
+ For an arbitrary frame-to-frame rotation, compose with
843
+ :func:`from_gcrf`::
844
+
845
+ # NTW -> RIC
846
+ dcm = sk.frametransform.from_gcrf(sk.frame.RTN, pos, vel) @ \\
847
+ sk.frametransform.to_gcrf(sk.frame.NTW, pos, vel)
848
+
849
+ Args:
850
+ frame: Source satellite-local frame
851
+ pos: 3-element position vector in GCRF [m]
852
+ vel: 3-element velocity vector in GCRF [m/s]
853
+
854
+ Returns:
855
+ numpy.ndarray: 3x3 rotation matrix (frame → GCRF)
856
+
857
+ Raises:
858
+ RuntimeError: if ``frame`` is not a satellite-local orbital frame.
859
+ Earth-fixed / celestial frames (ITRF, TEME, EME2000, etc.) need
860
+ a time argument for their rotation to GCRF and must use the
861
+ dedicated quaternion helpers (:func:`qitrf2gcrf`,
862
+ :func:`qteme2gcrf`, etc.) instead.
863
+
864
+ Example:
865
+ ```python
866
+ import satkit as sk
867
+ dcm = sk.frametransform.to_gcrf(sk.frame.NTW, pos_gcrf, vel_gcrf)
868
+ v_gcrf = dcm @ v_ntw
869
+ ```
870
+ """
871
+ ...
872
+
873
+ def itrf_to_gcrf_state(
874
+ pos_itrf: npt.ArrayLike,
875
+ vel_itrf: npt.ArrayLike,
876
+ time: time,
877
+ ) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
878
+ """Transform a satellite state (position + velocity) from ITRF to GCRF.
879
+
880
+ Unlike the raw :func:`qitrf2gcrf` quaternion, this function correctly
881
+ handles the Earth-rotation contribution to velocity. A point at rest
882
+ on Earth's surface has zero velocity in ITRF but ~465 m/s in GCRF at
883
+ the equator, and this function accounts for that term.
884
+
885
+ The IAU 2010 ITRF → GCRF reduction decomposes into three stages:
886
+ polar motion (ITRF → TIRS), Earth rotation about the CIO polar axis
887
+ (TIRS → CIRS), and precession-nutation (CIRS → GCRF). The
888
+ Earth-rotation sweep term ``omega_earth x r`` is computed in
889
+ **TIRS** — not ITRF or GCRF — because TIRS is defined such that
890
+ Earth's rotation axis is exactly along its +z axis. Computing the
891
+ sweep anywhere else would introduce either a polar-motion-sized
892
+ error (~0.3 arcsec in ITRF) or a precession-sized error (tens of
893
+ degrees in GCRF).
894
+
895
+ Implementation:
896
+
897
+ 1. Rotate ``pos_itrf`` and ``vel_itrf`` into TIRS via polar motion.
898
+ 2. Add ``omega_earth x r_tirs`` to the velocity in TIRS, where
899
+ ``omega_earth = (0, 0, OMEGA_EARTH)`` exactly.
900
+ 3. Rotate TIRS → CIRS → GCRF via the full IAU 2010 chain.
901
+
902
+ Uses the full IAU 2010 reduction (polar motion + Earth rotation +
903
+ precession-nutation with dX/dY corrections from Earth orientation
904
+ parameters).
905
+
906
+ Args:
907
+ pos_itrf: 3-element position vector in ITRF [m]
908
+ vel_itrf: 3-element velocity vector *as observed in ITRF* [m/s]
909
+ (zero for a point at rest on Earth's surface)
910
+ time: Epoch of the state
911
+
912
+ Returns:
913
+ A 2-tuple ``(pos_gcrf, vel_gcrf)`` of numpy arrays with the
914
+ state expressed in GCRF.
915
+
916
+ Example:
917
+ ```python
918
+ import satkit as sk
919
+ import numpy as np
920
+
921
+ # Geostationary satellite, stationary in ITRF
922
+ t = sk.time(2024, 1, 1)
923
+ pos_itrf = np.array([42164.17e3, 0.0, 0.0])
924
+ vel_itrf = np.array([0.0, 0.0, 0.0])
925
+ pos_gcrf, vel_gcrf = sk.frametransform.itrf_to_gcrf_state(
926
+ pos_itrf, vel_itrf, t)
927
+ # |vel_gcrf| ≈ 3075 m/s (the GEO orbital speed)
928
+ ```
929
+ """
930
+ ...
931
+
932
+ def gcrf_to_itrf_state(
933
+ pos_gcrf: npt.ArrayLike,
934
+ vel_gcrf: npt.ArrayLike,
935
+ time: time,
936
+ ) -> tuple[npt.NDArray[np.float64], npt.NDArray[np.float64]]:
937
+ """Transform a satellite state (position + velocity) from GCRF to ITRF.
938
+
939
+ Inverse of :func:`itrf_to_gcrf_state`. Rotates the state through
940
+ GCRF → CIRS → TIRS, subtracts the Earth-rotation ``omega_earth x r``
941
+ term **in TIRS** (where Earth's rotation axis is exactly along +z),
942
+ then applies inverse polar motion to reach ITRF. A geostationary
943
+ satellite (whose GCRF velocity is pure orbital motion) produces
944
+ zero velocity in ITRF. Uses the full IAU 2010 reduction.
945
+
946
+ Args:
947
+ pos_gcrf: 3-element position vector in GCRF [m]
948
+ vel_gcrf: 3-element velocity vector in GCRF [m/s]
949
+ time: Epoch of the state
950
+
951
+ Returns:
952
+ A 2-tuple ``(pos_itrf, vel_itrf)`` where ``vel_itrf`` is the
953
+ velocity as observed in ITRF.
954
+ """
955
+ ...
956
+
957
+ def from_gcrf(
958
+ frame: frame,
959
+ pos: npt.ArrayLike,
960
+ vel: npt.ArrayLike,
961
+ ) -> npt.NDArray[np.float64]:
962
+ """Return the 3x3 DCM that transforms a vector from GCRF into a
963
+ satellite-local orbital frame at the current state.
964
+
965
+ Transpose of :func:`to_gcrf`. See that function for the list of
966
+ supported frames, composition examples, and error conditions.
967
+
968
+ Args:
969
+ frame: Destination satellite-local frame
970
+ pos: 3-element position vector in GCRF [m]
971
+ vel: 3-element velocity vector in GCRF [m/s]
972
+
973
+ Returns:
974
+ numpy.ndarray: 3x3 rotation matrix (GCRF → frame)
975
+
976
+ Raises:
977
+ RuntimeError: if ``frame`` is not a satellite-local orbital frame.
978
+
979
+ Example:
980
+ ```python
981
+ import satkit as sk
982
+ dcm = sk.frametransform.from_gcrf(sk.frame.RTN, pos_gcrf, vel_gcrf)
983
+ v_ric = dcm @ v_gcrf
984
+ ```
985
+ """
986
+ ...
987
+
732
988
  def disable_eop_time_warning() -> None:
733
989
  """Disable the warning printed to stderr when Earth Orientation Parameters (EOP) are not available for a given time.
734
990
 
@@ -5,7 +5,6 @@ For details, see: <https://ssd.jpl.nasa.gov/>
5
5
  """
6
6
 
7
7
  from __future__ import annotations
8
- import typing
9
8
  import numpy.typing as npt
10
9
  import numpy as np
11
10
 
@@ -3,7 +3,6 @@ Low-precision planetary ephemerides from https://ssd.jpl.nasa.gov/?planet_pos
3
3
  """
4
4
 
5
5
  from __future__ import annotations
6
- import typing
7
6
  import numpy.typing as npt
8
7
  import numpy as np
9
8