0
# Time Systems
1

2
Comprehensive time conversion and manipulation functions supporting various time systems including UTC, ET (Ephemeris Time), TDB, and custom calendar formats. Time handling is fundamental to all SPICE computations as ephemeris data is indexed by time.
3

4
## Capabilities
5

6
### Time String to Ephemeris Time Conversion
7

8
Convert human-readable time strings to ephemeris time (ET), which is the standard time system used throughout SPICE.
9

10
```python { .api }
11
def str2et(time: Union[str, Iterable[str]]) -> Union[float, ndarray]:
12
    """
13
    Convert time string(s) to ephemeris time.
14
    
15
    Parameters:
16
    - time: str or Iterable[str], time string(s) in various formats
17
    
18
    Returns:
19
    Union[float, ndarray]: ephemeris time in seconds past J2000 epoch
20
    
21
    Supported formats:
22
    - ISO: "2023-01-01T12:00:00"
23
    - Calendar: "Jan 1, 2023 12:00:00"
24
    - DOY: "2023-001T12:00:00"  
25
    - JD: "JD 2459945.5"
26
    """
27
```
28

29
Usage example:
30
```python
31
import spiceypy as spice
32

33
# Single time conversion
34
et = spice.str2et("2023-01-01T12:00:00")
35
print(f"ET: {et} seconds past J2000")
36

37
# Multiple time conversions (vectorized)
38
times = ["2023-01-01", "2023-06-01", "2023-12-31"] 
39
ets = spice.str2et(times)
40
print(f"ETs: {ets}")
41
```
42

43
### Ephemeris Time to UTC Conversion
44

45
Convert ephemeris time back to UTC strings in various formats.
46

47
```python { .api }
48
def et2utc(et: Union[float, ndarray], format: str, prec: int) -> Union[str, List[str]]:
49
    """
50
    Convert ephemeris time to UTC string representation.
51
    
52
    Parameters:
53
    - et: Union[float, ndarray], ephemeris time(s)
54
    - format: str, output format ("C", "D", "ISO", "ISOC", "J")
55
    - prec: int, precision (digits after decimal point)
56
    
57
    Returns:
58
    Union[str, List[str]]: formatted UTC string(s)
59
    
60
    Format options:
61
    - "C": Calendar format "MON DD, YYYY HR:MN:SC.### ::UTC"
62
    - "D": DOY format "YYYY-DOY // HR:MN:SC.### ::UTC"  
63
    - "ISO": ISO format "YYYY-MM-DDTHR:MN:SC.###"
64
    - "ISOC": Compact ISO "YYYYMMDDTHRMNSC.###"
65
    - "J": Julian date "JD ###.######"
66
    """
67

68
def utc2et(utcstr: str) -> float:
69
    """
70
    Convert UTC string to ephemeris time.
71
    
72
    Parameters:
73
    - utcstr: str, UTC time string
74
    
75
    Returns:
76
    float: ephemeris time
77
    """
78
```
79

80
Usage example:
81
```python
82
# Convert ET to various UTC formats
83
et = spice.str2et("2023-01-01T12:00:00")
84

85
utc_iso = spice.et2utc(et, "ISO", 3)      # "2023-01-01T12:00:00.000"
86
utc_cal = spice.et2utc(et, "C", 0)        # "JAN 01, 2023 12:00:00 ::UTC"
87
utc_doy = spice.et2utc(et, "D", 0)        # "2023-001 // 12:00:00 ::UTC"
88
utc_jd = spice.et2utc(et, "J", 6)         # "JD 2459945.500000"
89
```
90

91
### Local Solar Time Conversion
92

93
Convert between ephemeris time and local solar time for planetary bodies.
94

95
```python { .api }
96
def et2lst(et: Union[float, ndarray], body: Union[int, str], lon: float, type: str) -> Union[Tuple[int, int, int, str, str], List[Tuple[int, int, int, str, str]]]:
97
    """
98
    Convert ephemeris time to local solar time.
99
    
100
    Parameters:
101
    - et: Union[float, ndarray], ephemeris time(s)
102
    - body: Union[int, str], target body name or ID
103
    - lon: float, longitude in radians (positive east)
104
    - type: str, "PLANETOCENTRIC" or "PLANETOGRAPHIC"
105
    
106
    Returns:
107
    Union[Tuple, List[Tuple]]: (hr, mn, sc, time, ampm)
108
    - hr: int, hour (0-23)
109
    - mn: int, minute (0-59)  
110
    - sc: int, second (0-59)
111
    - time: str, formatted time string
112
    - ampm: str, "A.M." or "P.M."
113
    """
114
```
115

116
### Time Parsing and Formatting
117

118
Advanced time parsing and custom formatting functions.
119

120
```python { .api }
121
def tparse(string: str) -> Tuple[float, str]:
122
    """
123
    Parse a time string and return ephemeris time.
124
    
125
    Parameters:
126
    - string: str, time string to parse
127
    
128
    Returns:
129
    Tuple[float, str]: (et, error_message)
130
    """
131

132
def timout(et: float, pictur: str) -> str:
133
    """
134
    Format ephemeris time using a custom picture string.
135
    
136
    Parameters:
137
    - et: float, ephemeris time
138
    - pictur: str, format picture string
139
    
140
    Returns:
141
    str: formatted time string
142
    
143
    Picture format examples:
144
    - "MON DD, YYYY"  → "JAN 01, 2023"
145
    - "YYYY-MM-DD"    → "2023-01-01"
146
    - "HR:MN:SC.###"  → "12:00:00.000"
147
    """
148

149
def etcal(et: float) -> str:
150
    """
151
    Convert ephemeris time to calendar format.
152
    
153
    Parameters:
154
    - et: float, ephemeris time
155
    
156
    Returns:
157
    str: calendar format "YYYY MON DD HR:MN:SC.FFF"
158
    """
159
```
160

161
### Time Constants and Utilities
162

163
Functions that return useful time-related constants and utilities.
164

165
```python { .api }
166
def spd() -> float:
167
    """
168
    Return the number of seconds per day.
169
    
170
    Returns:
171
    float: 86400.0 (seconds per day)
172
    """
173

174
def rpd() -> float:
175
    """
176
    Return the number of radians per degree.
177
    
178
    Returns:
179
    float: π/180 (radians per degree)
180
    """
181

182
def dpr() -> float:
183
    """
184
    Return the number of degrees per radian.
185
    
186
    Returns:
187
    float: 180/π (degrees per radian)
188
    """
189

190
def j1900() -> float:
191
    """
192
    Return the Julian date of 1900 JAN 0.5.
193
    
194
    Returns:
195
    float: 2415020.0
196
    """
197

198
def j1950() -> float:
199
    """
200
    Return the Julian date of 1950 JAN 1.0.
201
    
202
    Returns:
203
    float: 2433282.5
204
    """
205

206
def j2000() -> float:
207
    """
208
    Return the Julian date of 2000 JAN 1.5.
209
    
210
    Returns:
211
    float: 2451545.0
212
    """
213

214
def j2100() -> float:
215
    """
216
    Return the Julian date of 2100 JAN 1.5.
217
    
218
    Returns:
219
    float: 2488070.0
220
    """
221
```
222

223
### Time Differences and Light Time
224

225
Functions for computing time differences and light travel time corrections.
226

227
```python { .api }
228
def deltet(epoch: float, eptype: str) -> float:
229
    """
230
    Return the difference TDB - TDT at a given epoch.
231
    
232
    Parameters:
233
    - epoch: float, epoch time
234
    - eptype: str, epoch type ("UTC", "ET", "TAI", "TDT", "TDB")
235
    
236
    Returns:
237
    float: TDB - TDT in seconds
238
    """
239

240
def ltime(obs: ndarray, dir: int, target: ndarray) -> Tuple[float, ndarray]:
241
    """
242
    Compute light time between observer and target.
243
    
244
    Parameters:
245
    - obs: ndarray, observer position vector
246
    - dir: int, direction (1 for transmission, -1 for reception)
247
    - target: ndarray, target position vector
248
    
249
    Returns:
250
    Tuple[float, ndarray]: (light_time, target_position_corrected)
251
    """
252
```
253

254
## Common Usage Patterns
255

256
### Basic Time Conversion Workflow
257
```python
258
import spiceypy as spice
259

260
# Convert human-readable time to ET for SPICE computations
261
et = spice.str2et("2023-07-15T14:30:00")
262

263
# Use ET in SPICE functions
264
position, lt = spice.spkpos("MARS", et, "J2000", "LT+S", "EARTH")
265

266
# Convert back to human-readable format for output
267
utc_time = spice.et2utc(et, "ISO", 3)
268
print(f"Time: {utc_time}")
269
```
270

271
### Working with Time Arrays
272
```python
273
# Create a time series
274
start_time = spice.str2et("2023-01-01T00:00:00")
275
end_time = spice.str2et("2023-01-02T00:00:00") 
276
n_points = 25
277
dt = (end_time - start_time) / (n_points - 1)
278
times = [start_time + i * dt for i in range(n_points)]
279

280
# Convert time array to UTC strings for display
281
utc_times = spice.et2utc(times, "ISO", 0)
282
for utc in utc_times[:3]:  # Show first 3
283
    print(utc)
284
```
285

286
### Local Solar Time on Mars
287
```python
288
# Convert Earth UTC time to Mars local solar time
289
et = spice.str2et("2023-07-15T12:00:00")
290
mars_lon = spice.dpr() * 175.0  # 175 degrees east longitude
291

292
# Get Mars local solar time
293
hr, mn, sc, time_str, ampm = spice.et2lst(et, "MARS", mars_lon, "PLANETOCENTRIC")
294
print(f"Mars LST: {time_str} {ampm}")
295
```