0
# Spacecraft Clock Functions
1

2
Time correlation functions for converting between spacecraft clock time and other time systems. Spacecraft clocks provide the primary time reference for mission operations, and these functions enable translation between spacecraft time and standard time systems like Ephemeris Time (ET) and UTC.
3

4
## Capabilities
5

6
### Spacecraft Clock to Ephemeris Time
7

8
Convert spacecraft clock strings and ticks to ephemeris time.
9

10
```python { .api }
11
def scs2e(sc: int, sclkch: str) -> float:
12
    """
13
    Convert spacecraft clock string to ephemeris time.
14
    
15
    Parameters:
16
    - sc: int, spacecraft ID
17
    - sclkch: str, spacecraft clock string
18
    
19
    Returns:
20
    float: ephemeris time (seconds past J2000)
21
    """
22

23
def sct2e(sc: int, sclkdp: float) -> float:
24
    """
25
    Convert spacecraft clock ticks to ephemeris time.
26
    
27
    Parameters:
28
    - sc: int, spacecraft ID
29
    - sclkdp: float, spacecraft clock ticks
30
    
31
    Returns:
32
    float: ephemeris time (seconds past J2000)
33
    """
34
```
35

36
### Ephemeris Time to Spacecraft Clock
37

38
Convert ephemeris time to spacecraft clock format.
39

40
```python { .api }
41
def sce2s(sc: int, et: float) -> str:
42
    """
43
    Convert ephemeris time to spacecraft clock string.
44
    
45
    Parameters:
46
    - sc: int, spacecraft ID
47
    - et: float, ephemeris time
48
    
49
    Returns:
50
    str: spacecraft clock string
51
    """
52

53
def sce2t(sc: int, et: float) -> float:
54
    """
55
    Convert ephemeris time to spacecraft clock ticks.
56
    
57
    Parameters:
58
    - sc: int, spacecraft ID
59
    - et: float, ephemeris time
60
    
61
    Returns:
62
    float: spacecraft clock ticks
63
    """
64

65
def sce2c(sc: int, et: float) -> float:
66
    """
67
    Convert ephemeris time to continuous spacecraft clock ticks.
68
    
69
    Parameters:
70
    - sc: int, spacecraft ID
71
    - et: float, ephemeris time
72
    
73
    Returns:
74
    float: continuous spacecraft clock ticks
75
    """
76
```
77

78
### Spacecraft Clock Formatting
79

80
Format and decode spacecraft clock strings.
81

82
```python { .api }
83
def scfmt(sc: int, ticks: float) -> str:
84
    """
85
    Format spacecraft clock ticks as string.
86
    
87
    Parameters:
88
    - sc: int, spacecraft ID
89
    - ticks: float, spacecraft clock ticks
90
    
91
    Returns:
92
    str: formatted spacecraft clock string
93
    """
94

95
def scencd(sc: int, sclkch: str) -> float:
96
    """
97
    Encode spacecraft clock string to ticks.
98
    
99
    Parameters:
100
    - sc: int, spacecraft ID
101
    - sclkch: str, spacecraft clock string
102
    
103
    Returns:
104
    float: spacecraft clock ticks
105
    """
106

107
def scdecd(sc: int, sclkdp: float) -> str:
108
    """
109
    Decode spacecraft clock ticks to string.
110
    
111
    Parameters:
112
    - sc: int, spacecraft ID
113
    - sclkdp: float, spacecraft clock ticks
114
    
115
    Returns:
116
    str: spacecraft clock string
117
    """
118
```
119

120
### Spacecraft Clock Information
121

122
Query spacecraft clock parameters and metadata.
123

124
```python { .api }
125
def scpart(sc: int) -> Tuple[int, ndarray, ndarray]:
126
    """
127
    Get spacecraft clock partition information.
128
    
129
    Parameters:
130
    - sc: int, spacecraft ID
131
    
132
    Returns:
133
    Tuple[int, ndarray, ndarray]: (nparts, pstart, pstop)
134
    - nparts: number of partitions
135
    - pstart: partition start times
136
    - pstop: partition stop times
137
    """
138

139
def sctiks(sc: int, clkstr: str) -> float:
140
    """
141
    Convert spacecraft clock string to ticks.
142
    
143
    Parameters:
144
    - sc: int, spacecraft ID
145
    - clkstr: str, spacecraft clock string
146
    
147
    Returns:
148
    float: number of ticks
149
    """
150

151
def scard(cell: SpiceCell) -> int:  
152
    """
153
    Get spacecraft clock cardinality (number of elements).
154
    
155
    Parameters:
156
    - cell: SpiceCell, spacecraft clock cell
157
    
158
    Returns:
159
    int: number of elements in cell
160
    """
161
```
162

163
## Common Usage Patterns
164

165
### Basic Time Conversion
166
```python
167
import spiceypy as spice
168

169
# Load required kernels
170
spice.furnsh("spacecraft_sclk.tsc")  # Spacecraft clock kernel
171
spice.furnsh("leapseconds.tls")     # Leap seconds kernel
172

173
spacecraft_id = -123
174

175
# Convert ephemeris time to spacecraft clock
176
et = spice.str2et("2023-01-01T12:00:00")
177
sclk_string = spice.sce2s(spacecraft_id, et)
178
sclk_ticks = spice.sce2t(spacecraft_id, et)
179

180
print(f"ET: {et}")
181
print(f"SCLK string: {sclk_string}")
182
print(f"SCLK ticks: {sclk_ticks}")
183

184
# Convert spacecraft clock back to ephemeris time
185
et_converted = spice.scs2e(spacecraft_id, sclk_string)
186
et_from_ticks = spice.sct2e(spacecraft_id, sclk_ticks)
187

188
print(f"ET from string: {et_converted}")
189
print(f"ET from ticks: {et_from_ticks}")
190
```
191

192
### Working with Spacecraft Clock Partitions
193
```python
194
import spiceypy as spice
195

196
# Get spacecraft clock partition information
197
spacecraft_id = -123
198
nparts, pstart, pstop = spice.scpart(spacecraft_id)
199

200
print(f"Spacecraft {spacecraft_id} has {nparts} clock partitions:")
201

202
for i in range(nparts):
203
    start_et = spice.sct2e(spacecraft_id, pstart[i])
204
    stop_et = spice.sct2e(spacecraft_id, pstop[i]) 
205
    
206
    start_utc = spice.et2utc(start_et, "C", 0)
207
    stop_utc = spice.et2utc(stop_et, "C", 0)
208
    
209
    print(f"  Partition {i}: {start_utc} to {stop_utc}")
210
    print(f"    Ticks: {pstart[i]} to {pstop[i]}")
211
```
212

213
### Formatting Spacecraft Clock Times
214
```python
215
import spiceypy as spice
216

217
spacecraft_id = -123
218

219
# Get current spacecraft clock time
220
et_now = spice.str2et("2023-06-15T14:30:00")
221
sclk_ticks = spice.sce2t(spacecraft_id, et_now)
222

223
# Format in different ways
224
sclk_string = spice.scfmt(spacecraft_id, sclk_ticks)
225
decoded_string = spice.scdecd(spacecraft_id, sclk_ticks)
226

227
print(f"SCLK ticks: {sclk_ticks}")
228
print(f"Formatted SCLK: {sclk_string}")
229
print(f"Decoded SCLK: {decoded_string}")
230

231
# Parse spacecraft clock string to ticks
232
parsed_ticks = spice.scencd(spacecraft_id, sclk_string)
233
ticks_from_sctiks = spice.sctiks(spacecraft_id, sclk_string)
234

235
print(f"Parsed ticks (scencd): {parsed_ticks}")
236
print(f"Parsed ticks (sctiks): {ticks_from_sctiks}")
237
```
238

239
### Continuous Clock Conversion
240
```python
241
import spiceypy as spice
242

243
spacecraft_id = -123
244

245
# Convert to continuous spacecraft clock (handles partition boundaries)
246
et = spice.str2et("2023-01-01T12:00:00")
247
continuous_ticks = spice.sce2c(spacecraft_id, et)
248

249
print(f"ET: {et}")
250
print(f"Continuous SCLK ticks: {continuous_ticks}")
251

252
# Note: Continuous ticks can span partition boundaries
253
# unlike regular ticks which reset at each partition
254
```
255

256
### Batch Time Conversion
257
```python
258
import spiceypy as spice
259
import numpy as np
260

261
spacecraft_id = -123
262

263
# Convert multiple times
264
times_utc = [
265
    "2023-01-01T00:00:00",
266
    "2023-01-01T06:00:00", 
267
    "2023-01-01T12:00:00",
268
    "2023-01-01T18:00:00",
269
    "2023-01-02T00:00:00"
270
]
271

272
print("Time conversion table:")
273
print("UTC                   ET           SCLK String    SCLK Ticks")
274
print("-" * 70)
275

276
for utc_str in times_utc:
277
    et = spice.str2et(utc_str)
278
    sclk_str = spice.sce2s(spacecraft_id, et)
279
    sclk_ticks = spice.sce2t(spacecraft_id, et)
280
    
281
    print(f"{utc_str}  {et:12.3f}  {sclk_str:12s}  {sclk_ticks:12.3f}")
282
```
283

284
### Error Handling for Clock Conversions
285
```python
286
import spiceypy as spice
287

288
spacecraft_id = -123
289

290
try:
291
    # Attempt conversion that might fail
292
    et = spice.str2et("2025-01-01T12:00:00")  # Future time
293
    sclk_string = spice.sce2s(spacecraft_id, et)
294
    print(f"Conversion successful: {sclk_string}")
295
    
296
except spice.SpiceyError as e:
297
    print(f"Clock conversion failed: {e}")
298
    print("This might happen if:")
299
    print("  - SCLK kernel doesn't cover the requested time")
300
    print("  - Spacecraft ID is invalid")
301
    print("  - Required kernels aren't loaded")
302
```