0
# Data Structures and Cells
1

2
SPICE-specific data structures including cells, windows, and containers for managing sets of data. These structures provide efficient storage and manipulation of collections commonly used in SPICE operations.
3

4
## Capabilities
5

6
### Cell Creation
7

8
Create SPICE cells for different data types.
9

10
```python { .api }
11
def cell_double(cell_size: int) -> SpiceCell:
12
    """
13
    Create a double precision cell.
14
    
15
    Parameters:
16
    - cell_size: int, maximum number of elements
17
    
18
    Returns:
19
    SpiceCell: empty double precision cell
20
    """
21

22
def cell_int(cell_size: int) -> SpiceCell:
23
    """
24
    Create an integer cell.
25
    
26
    Parameters:
27
    - cell_size: int, maximum number of elements
28
    
29
    Returns:
30
    SpiceCell: empty integer cell
31
    """
32

33
def cell_char(cell_size: int, length: int) -> SpiceCell:
34
    """
35
    Create a character string cell.
36
    
37
    Parameters:
38
    - cell_size: int, maximum number of strings
39
    - length: int, maximum length of each string
40
    
41
    Returns:
42
    SpiceCell: empty character cell
43
    """
44
```
45

46
### Cell Operations
47

48
Basic operations on SPICE cells.
49

50
```python { .api }
51
def card(cell: SpiceCell) -> int:
52
    """
53
    Return cardinality (number of elements) of a cell.
54
    
55
    Parameters:
56
    - cell: SpiceCell, input cell
57
    
58
    Returns:
59
    int: number of elements in cell
60
    """
61

62
def size(cell: SpiceCell) -> int:
63
    """
64
    Return size (maximum capacity) of a cell.
65
    
66
    Parameters:
67
    - cell: SpiceCell, input cell
68
    
69
    Returns:
70
    int: maximum number of elements cell can hold
71
    """
72

73
def copy(cell: SpiceCell) -> SpiceCell:
74
    """
75
    Copy a cell.
76
    
77
    Parameters:
78
    - cell: SpiceCell, input cell
79
    
80
    Returns:
81
    SpiceCell: copy of input cell
82
    """
83
```
84

85
### Window Operations
86

87
Specialized operations for time windows (double precision cells).
88

89
```python { .api }
90
def wninsd(left: float, right: float, window: SpiceCell) -> None:
91
    """
92
    Insert interval into window.
93
    
94
    Parameters:
95
    - left: float, left endpoint of interval
96
    - right: float, right endpoint of interval
97
    - window: SpiceCell, window to modify
98
    
99
    Returns:
100
    None (window is modified in place)
101
    """
102

103
def wncard(window: SpiceCell) -> int:
104
    """
105
    Return number of intervals in window.
106
    
107
    Parameters:
108
    - window: SpiceCell, input window
109
    
110
    Returns:
111
    int: number of intervals
112
    """
113

114
def wnfetd(window: SpiceCell, n: int) -> Tuple[float, float]:
115
    """
116
    Fetch nth interval from window.
117
    
118
    Parameters:
119
    - window: SpiceCell, input window
120
    - n: int, interval index (0-based)
121
    
122
    Returns:
123
    Tuple[float, float]: (left, right) endpoints of interval
124
    """
125

126
def wnunid(a: SpiceCell, b: SpiceCell, c: SpiceCell) -> None:
127
    """
128
    Union two windows into a third window.
129
    
130
    Parameters:
131
    - a: SpiceCell, first input window
132
    - b: SpiceCell, second input window
133
    - c: SpiceCell, output window (a ∪ b)
134
    
135
    Returns:
136
    None (output window modified in place)
137
    """
138

139
def wnintd(a: SpiceCell, b: SpiceCell, c: SpiceCell) -> None:
140
    """
141
    Intersect two windows into a third window.
142
    
143
    Parameters:
144
    - a: SpiceCell, first input window
145
    - b: SpiceCell, second input window
146
    - c: SpiceCell, output window (a ∩ b)
147
    
148
    Returns:
149
    None (output window modified in place)
150
    """
151

152
def wndifd(a: SpiceCell, b: SpiceCell, c: SpiceCell) -> None:
153
    """
154
    Difference of two windows into a third window.
155
    
156
    Parameters:
157
    - a: SpiceCell, first input window
158
    - b: SpiceCell, second input window
159
    - c: SpiceCell, output window (a - b)
160
    
161
    Returns:
162
    None (output window modified in place)
163
    """
164

165
def wnexpd(left: float, right: float, window: SpiceCell) -> None:
166
    """
167
    Expand intervals in window by specified amounts.
168
    
169
    Parameters:
170
    - left: float, expansion amount for left endpoints
171
    - right: float, expansion amount for right endpoints
172
    - window: SpiceCell, window to expand (modified in place)
173
    
174
    Returns:
175
    None
176
    """
177

178
def wncond(left: float, right: float, window: SpiceCell) -> None:
179
    """
180
    Contract intervals in window by specified amounts.
181
    
182
    Parameters:
183
    - left: float, contraction amount for left endpoints
184
    - right: float, contraction amount for right endpoints
185
    - window: SpiceCell, window to contract (modified in place)
186
    
187
    Returns:
188
    None
189
    """
190

191
def wnfild(small: float, window: SpiceCell) -> None:
192
    """
193
    Fill small gaps in window.
194
    
195
    Parameters:
196
    - small: float, maximum gap size to fill
197
    - window: SpiceCell, window to modify (modified in place)
198
    
199
    Returns:
200
    None
201
    """
202

203
def wnfltd(small: float, window: SpiceCell) -> None:
204
    """
205
    Filter small intervals from window.
206
    
207
    Parameters:
208
    - small: float, minimum interval size to keep
209
    - window: SpiceCell, window to filter (modified in place)
210
    
211
    Returns:
212
    None
213
    """
214

215
def wnsumd(window: SpiceCell) -> float:
216
    """
217
    Compute total measure (sum of interval lengths) of window.
218
    
219
    Parameters:
220
    - window: SpiceCell, input window
221
    
222
    Returns:
223
    float: total measure of all intervals
224
    """
225

226
def wnelmd(point: float, window: SpiceCell) -> bool:
227
    """
228
    Test whether point is element of window.
229
    
230
    Parameters:
231
    - point: float, test point
232
    - window: SpiceCell, input window
233
    
234
    Returns:
235
    bool: True if point is in window
236
    """
237

238
def wnincd(left: float, right: float, window: SpiceCell) -> bool:
239
    """
240
    Test whether interval is included in window.
241
    
242
    Parameters:
243
    - left: float, left endpoint of test interval
244
    - right: float, right endpoint of test interval
245
    - window: SpiceCell, input window
246
    
247
    Returns:
248
    bool: True if interval is completely contained in window
249
    """
250

251
def wnreld(a: SpiceCell, op: str, b: SpiceCell) -> bool:
252
    """
253
    Compare two windows using relational operator.
254
    
255
    Parameters:
256
    - a: SpiceCell, first window
257
    - op: str, relational operator ("=", "<>", "<=", ">=", "<", ">")
258
    - b: SpiceCell, second window
259
    
260
    Returns:
261
    bool: result of comparison
262
    """
263

264
def wnvald(window: SpiceCell) -> None:
265
    """
266
    Validate window (remove invalid intervals, merge overlaps).
267
    
268
    Parameters:
269
    - window: SpiceCell, window to validate (modified in place)
270
    
271
    Returns:
272
    None
273
    """
274

275
def wnextd(side: str, window: SpiceCell) -> float:
276
    """
277
    Extract leftmost or rightmost endpoint from window.
278
    
279
    Parameters:
280
    - side: str, which endpoint ("L" for left, "R" for right)
281
    - window: SpiceCell, input window
282
    
283
    Returns:
284
    float: leftmost left endpoint or rightmost right endpoint
285
    """
286

287
def wncomd(left: float, right: float, window: SpiceCell, result: SpiceCell) -> None:
288
    """
289
    Complement of window over specified interval.
290
    
291
    Parameters:
292
    - left: float, left endpoint of complement interval
293
    - right: float, right endpoint of complement interval  
294
    - window: SpiceCell, input window
295
    - result: SpiceCell, complement window (modified)
296
    
297
    Returns:
298
    None
299
    """
300
```
301

302
## Common Usage Patterns
303

304
### Working with Time Windows
305
```python
306
import spiceypy as spice
307

308
# Create a double precision cell for time windows
309
window = spice.cell_double(100)
310

311
# Insert time intervals
312
start1 = spice.str2et("2023-01-01T00:00:00")
313
end1 = spice.str2et("2023-01-01T12:00:00")
314
spice.wninsd(start1, end1, window)
315

316
start2 = spice.str2et("2023-01-02T00:00:00")
317
end2 = spice.str2et("2023-01-02T12:00:00")
318
spice.wninsd(start2, end2, window)
319

320
# Query window properties
321
num_intervals = spice.wncard(window)
322
print(f"Number of intervals: {num_intervals}")
323

324
# Extract intervals
325
for i in range(num_intervals):
326
    left, right = spice.wnfetd(window, i)
327
    print(f"Interval {i}: {spice.et2utc(left, 'C', 0)} to {spice.et2utc(right, 'C', 0)}")
328
```
329

330
### Window Set Operations
331
```python
332
import spiceypy as spice
333

334
# Create two windows
335
window_a = spice.cell_double(100)
336
window_b = spice.cell_double(100)
337
result = spice.cell_double(100)
338

339
# Add intervals to first window
340
spice.wninsd(spice.str2et("2023-01-01T00:00:00"), spice.str2et("2023-01-01T12:00:00"), window_a)
341
spice.wninsd(spice.str2et("2023-01-02T00:00:00"), spice.str2et("2023-01-02T12:00:00"), window_a)
342

343
# Add intervals to second window
344
spice.wninsd(spice.str2et("2023-01-01T06:00:00"), spice.str2et("2023-01-01T18:00:00"), window_b)
345
spice.wninsd(spice.str2et("2023-01-03T00:00:00"), spice.str2et("2023-01-03T12:00:00"), window_b)
346

347
# Union of windows
348
spice.wnunid(window_a, window_b, result)
349
print(f"Union has {spice.wncard(result)} intervals")
350

351
# Intersection of windows
352
spice.wnintd(window_a, window_b, result)
353
print(f"Intersection has {spice.wncard(result)} intervals")
354

355
# Difference (A - B)
356
spice.wndifd(window_a, window_b, result)
357
print(f"Difference has {spice.wncard(result)} intervals")
358
```
359

360
### Window Analysis and Modification
361
```python
362
import spiceypy as spice
363

364
# Create window with some intervals
365
window = spice.cell_double(100)
366
spice.wninsd(100.0, 200.0, window)
367
spice.wninsd(205.0, 210.0, window)  # Small gap of 5 seconds
368
spice.wninsd(215.0, 217.0, window)  # Short interval of 2 seconds
369

370
print(f"Original window measure: {spice.wnsumd(window)} seconds")
371

372
# Fill small gaps (less than 10 seconds)
373
spice.wnfild(10.0, window)
374
print(f"After filling gaps: {spice.wncard(window)} intervals")
375

376
# Filter out small intervals (less than 5 seconds)
377
spice.wnfltd(5.0, window)
378
print(f"After filtering small intervals: {spice.wncard(window)} intervals")
379

380
# Test point membership
381
test_time = 150.0
382
if spice.wnelmd(test_time, window):
383
    print(f"Time {test_time} is covered by window")
384

385
# Expand intervals by 30 seconds on each side
386
spice.wnexpd(30.0, 30.0, window)
387
print(f"After expansion: total measure = {spice.wnsumd(window)} seconds")
388
```