0
# Ephemeris and Trajectories
1

2
Functions for computing positions and velocities of celestial bodies, spacecraft, and other objects in the Solar System with high precision. These are the core functions for trajectory analysis and spacecraft navigation.
3

4
## Capabilities
5

6
### Position Computations
7

8
Compute the position of target objects relative to observers with various aberration corrections.
9

10
```python { .api }
11
def spkpos(targ: Union[int, str], et: Union[float, ndarray], ref: str, abcorr: str, obs: Union[int, str]) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
12
    """
13
    Return the position of a target body relative to an observer.
14
    
15
    Parameters:
16
    - targ: Union[int, str], target body name or NAIF ID
17
    - et: Union[float, ndarray], ephemeris time(s) in seconds past J2000
18
    - ref: str, reference frame ("J2000", "IAU_EARTH", etc.)
19
    - abcorr: str, aberration correction ("NONE", "LT", "LT+S", "CN", "CN+S")
20
    - obs: Union[int, str], observer body name or NAIF ID
21
    
22
    Returns:
23
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]: 
24
    - For scalar ET: (position_vector, light_time)
25
    - For array ET: (position_vectors, light_times)
26
    
27
    position_vector: 3-element array [x, y, z] in km
28
    light_time: one-way light time in seconds
29
    """
30

31
def spkgeo(targ: int, et: Union[float, ndarray], ref: str, obs: int) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
32
    """
33
    Compute geometric position (no aberration corrections).
34
    
35
    Parameters:
36
    - targ: int, target body NAIF ID
37
    - et: Union[float, ndarray], ephemeris time(s)
38
    - ref: str, reference frame
39
    - obs: int, observer body NAIF ID
40
    
41
    Returns:
42
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]: (position, light_time)
43
    """
44
```
45

46
Usage example:
47
```python
48
import spiceypy as spice
49

50
# Load kernels
51
spice.furnsh("metakernel.mk")
52

53
# Get Mars position relative to Earth
54
et = spice.str2et("2023-07-01T12:00:00")
55
position, light_time = spice.spkpos(
56
    "MARS",       # Target
57
    et,           # Time
58
    "J2000",      # Reference frame  
59
    "LT+S",       # Light time + stellar aberration correction
60
    "EARTH"       # Observer
61
)
62

63
print(f"Mars position: {position} km")
64
print(f"Light time: {light_time:.2f} seconds")
65
print(f"Distance: {spice.vnorm(position):.0f} km")
66
```
67

68
### State Vector Computations
69

70
Compute both position and velocity (6-element state vectors) for complete kinematic information.
71

72
```python { .api }
73
def spkezr(targ: Union[int, str], et: Union[float, ndarray], ref: str, abcorr: str, obs: Union[int, str]) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
74
    """
75
    Return the state (position and velocity) of a target relative to observer.
76
    
77
    Parameters:
78
    - targ: Union[int, str], target body name or NAIF ID
79
    - et: Union[float, ndarray], ephemeris time(s)
80
    - ref: str, reference frame
81
    - abcorr: str, aberration correction
82
    - obs: Union[int, str], observer body name or NAIF ID
83
    
84
    Returns:
85
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
86
    - For scalar ET: (state_vector, light_time)
87
    - For array ET: (state_vectors, light_times)
88
    
89
    state_vector: 6-element array [x, y, z, vx, vy, vz]
90
    - Position in km, velocity in km/s
91
    """
92

93
def spkgps(targ: int, et: Union[float, ndarray], ref: str, obs: int) -> Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]:
94
    """
95
    Geometric state (no aberration corrections).
96
    
97
    Parameters:
98
    - targ: int, target body NAIF ID
99
    - et: Union[float, ndarray], ephemeris time(s)
100
    - ref: str, reference frame
101
    - obs: int, observer body NAIF ID
102
    
103
    Returns:
104
    Union[Tuple[ndarray, float], Tuple[ndarray, ndarray]]: (state, light_time)
105
    """
106
```
107

108
### Advanced Position Functions
109

110
Specialized position computation functions for specific use cases.
111

112
```python { .api }
113
def spkcpo(target: str, et: float, outref: str, refloc: str, abcorr: str, obspos: ndarray, obsctr: str, obsref: str) -> Tuple[ndarray, float]:
114
    """
115
    Return position of target relative to constant observer position.
116
    
117
    Parameters:
118
    - target: str, target body name
119
    - et: float, ephemeris time
120
    - outref: str, output reference frame
121
    - refloc: str, reference location ("CENTER", "OBSERVER")
122
    - abcorr: str, aberration correction
123
    - obspos: ndarray, observer position vector
124
    - obsctr: str, observer frame center
125
    - obsref: str, observer reference frame
126
    
127
    Returns:
128
    Tuple[ndarray, float]: (position, light_time)
129
    """
130

131
def spkcpt(trgpos: ndarray, trgctr: str, trgref: str, et: float, outref: str, refloc: str, abcorr: str, obsrvr: str) -> Tuple[ndarray, float]:
132
    """
133
    Return position of constant target position relative to observer.
134
    
135
    Parameters:
136
    - trgpos: ndarray, target position vector
137
    - trgctr: str, target frame center  
138
    - trgref: str, target reference frame
139
    - et: float, ephemeris time
140
    - outref: str, output reference frame
141
    - refloc: str, reference location
142
    - abcorr: str, aberration correction
143
    - obsrvr: str, observer body name
144
    
145
    Returns:
146
    Tuple[ndarray, float]: (position, light_time)
147
    """
148

149
def spkcvo(target: str, et: float, outref: str, refloc: str, abcorr: str, obssta: ndarray, obsepc: float, obsctr: str, obsref: str) -> Tuple[ndarray, float]:
150
    """
151
    Return state of target relative to constant observer state.
152
    
153
    Parameters:
154
    - target: str, target body name
155
    - et: float, ephemeris time
156
    - outref: str, output reference frame
157
    - refloc: str, reference location
158
    - abcorr: str, aberration correction
159
    - obssta: ndarray, observer state vector
160
    - obsepc: float, observer epoch
161
    - obsctr: str, observer frame center
162
    - obsref: str, observer reference frame
163
    
164
    Returns:
165
    Tuple[ndarray, float]: (state, light_time)
166
    """
167
```
168

169
### Apparent Positions
170

171
Functions for computing apparent positions accounting for light time and stellar aberration.
172

173
```python { .api }
174
def spkapp(targ: Union[int, str], et: float, ref: str, sobs: ndarray, abcorr: str) -> Tuple[ndarray, float]:
175
    """
176
    Return apparent state of target as seen by observer.
177
    
178
    Parameters:
179
    - targ: Union[int, str], target body
180
    - et: float, ephemeris time
181
    - ref: str, reference frame
182
    - sobs: ndarray, observer state vector
183
    - abcorr: str, aberration correction
184
    
185
    Returns:
186
    Tuple[ndarray, float]: (apparent_state, light_time)
187
    """
188

189
def spkapo(targ: Union[int, str], et: float, ref: str, sobs: ndarray, abcorr: str) -> Tuple[ndarray, float]:
190
    """
191
    Return apparent position of target as seen by observer.
192
    
193
    Parameters:
194
    - targ: Union[int, str], target body
195
    - et: float, ephemeris time
196
    - ref: str, reference frame
197
    - sobs: ndarray, observer state vector
198
    - abcorr: str, aberration correction
199
    
200
    Returns:
201
    Tuple[ndarray, float]: (apparent_position, light_time)
202
    """
203
```
204

205
### Solar System Barycenter Functions
206

207
Functions for computing states relative to the solar system barycenter.
208

209
```python { .api }
210
def spkssb(targ: Union[int, str], et: Union[float, ndarray], ref: str) -> Union[ndarray, ndarray]:
211
    """
212
    Return state of target relative to solar system barycenter.
213
    
214
    Parameters:
215
    - targ: Union[int, str], target body
216
    - et: Union[float, ndarray], ephemeris time(s)
217
    - ref: str, reference frame
218
    
219
    Returns:
220
    Union[ndarray, ndarray]: state vector(s) relative to SSB
221
    """
222

223
def spkssb_c(targ: int, et: float, ref: str) -> ndarray:
224
    """
225
    Return state of target relative to solar system barycenter (C version).
226
    
227
    Parameters:
228
    - targ: int, target body NAIF ID
229
    - et: float, ephemeris time
230
    - ref: str, reference frame
231
    
232
    Returns:
233
    ndarray: 6-element state vector [x, y, z, vx, vy, vz]
234
    """
235
```
236

237
## Aberration Corrections
238

239
Understanding aberration correction options is crucial for accurate ephemeris computations:
240

241
- **"NONE"**: No corrections applied (geometric positions)
242
- **"LT"**: One-way light time correction only
243
- **"LT+S"**: Light time plus stellar aberration correction  
244
- **"CN"**: Converged Newtonian light time correction
245
- **"CN+S"**: Converged Newtonian light time plus stellar aberration
246
- **"XLT"**: Transmission case light time correction
247
- **"XLT+S"**: Transmission case light time plus stellar aberration
248
- **"XCN"**: Transmission case converged Newtonian correction
249
- **"XCN+S"**: Transmission case converged Newtonian plus stellar aberration
250

251
## Common Usage Patterns
252

253
### Basic Position Query
254
```python
255
import spiceypy as spice
256
import numpy as np
257

258
# Load kernels
259
spice.furnsh("metakernel.mk")
260

261
# Get current position of Mars relative to Earth
262
et = spice.str2et("now")
263
pos, lt = spice.spkpos("MARS", et, "J2000", "LT+S", "EARTH")
264

265
# Calculate distance and direction
266
distance = spice.vnorm(pos)  # km
267
unit_vector = spice.vhat(pos)  # direction
268

269
print(f"Mars distance: {distance:,.0f} km")
270
print(f"Light time: {lt/60:.1f} minutes")
271

272
spice.kclear()
273
```
274

275
### Trajectory Analysis Over Time
276
```python
277
# Create time array (24 hours with 1-hour intervals)
278
start_et = spice.str2et("2023-01-01T00:00:00")
279
times = [start_et + i * 3600 for i in range(24)]  # 24 hours
280

281
# Get Mars positions over 24 hours
282
positions, light_times = spice.spkpos("MARS", times, "J2000", "LT+S", "EARTH")
283

284
# Analyze trajectory
285
distances = [spice.vnorm(pos) for pos in positions]
286
print(f"Distance range: {min(distances):,.0f} - {max(distances):,.0f} km")
287
```
288

289
### Multiple Body Positions
290
```python
291
# Get positions of multiple planets at the same time
292
et = spice.str2et("2023-01-01T12:00:00")
293
bodies = ["MERCURY", "VENUS", "MARS", "JUPITER", "SATURN"]
294

295
for body in bodies:
296
    pos, lt = spice.spkpos(body, et, "J2000", "LT+S", "EARTH")
297
    distance = spice.vnorm(pos)
298
    print(f"{body}: {distance:,.0f} km")
299
```
300

301
### State Vector Analysis  
302
```python
303
# Get complete state vector (position + velocity)
304
state, lt = spice.spkezr("MARS", et, "J2000", "LT+S", "EARTH")
305

306
# Extract position and velocity components
307
position = state[:3]  # First 3 elements: x, y, z (km)
308
velocity = state[3:]  # Last 3 elements: vx, vy, vz (km/s)
309

310
speed = spice.vnorm(velocity)  # km/s
311
print(f"Mars relative speed: {speed:.3f} km/s")
312
```