0
# Types and Arrays
1

2
Warp provides a comprehensive type system including primitive types, vectors, matrices, quaternions, transforms, and multi-dimensional arrays with device-aware memory management. This type system enables efficient GPU/CPU computation while maintaining Python accessibility.
3

4
## Capabilities
5

6
### Primitive Types
7

8
Basic numeric types optimized for GPU computation with explicit bit-width specification.
9

10
```python { .api }
11
# Integer types
12
int8 = typing.Type[int]     # 8-bit signed integer
13
uint8 = typing.Type[int]    # 8-bit unsigned integer  
14
int16 = typing.Type[int]    # 16-bit signed integer
15
uint16 = typing.Type[int]   # 16-bit unsigned integer
16
int32 = typing.Type[int]    # 32-bit signed integer
17
uint32 = typing.Type[int]   # 32-bit unsigned integer
18
int64 = typing.Type[int]    # 64-bit signed integer
19
uint64 = typing.Type[int]   # 64-bit unsigned integer
20

21
# Floating point types
22
float16 = typing.Type[float]  # 16-bit half precision
23
float32 = typing.Type[float]  # 32-bit single precision
24
float64 = typing.Type[float]  # 64-bit double precision
25

26
# Boolean type
27
bool = typing.Type[bool]
28
```
29

30
### Vector Types
31

32
Fixed-size vector types with component-wise operations for spatial computing.
33

34
```python { .api }
35
# 2D vectors with different component types
36
vec2 = typing.Type[Vector2]      # float32 components
37
vec2b = typing.Type[Vector2]     # int8 components
38
vec2ub = typing.Type[Vector2]    # uint8 components  
39
vec2s = typing.Type[Vector2]     # int16 components
40
vec2us = typing.Type[Vector2]    # uint16 components
41
vec2i = typing.Type[Vector2]     # int32 components
42
vec2ui = typing.Type[Vector2]    # uint32 components
43
vec2l = typing.Type[Vector2]     # int64 components
44
vec2ul = typing.Type[Vector2]    # uint64 components
45
vec2h = typing.Type[Vector2]     # float16 components
46
vec2f = typing.Type[Vector2]     # float32 components
47
vec2d = typing.Type[Vector2]     # float64 components
48

49
# 3D vectors with different component types
50
vec3 = typing.Type[Vector3]      # float32 components
51
vec3b = typing.Type[Vector3]     # int8 components
52
vec3ub = typing.Type[Vector3]    # uint8 components
53
vec3s = typing.Type[Vector3]     # int16 components
54
vec3us = typing.Type[Vector3]    # uint16 components
55
vec3i = typing.Type[Vector3]     # int32 components
56
vec3ui = typing.Type[Vector3]    # uint32 components
57
vec3l = typing.Type[Vector3]     # int64 components
58
vec3ul = typing.Type[Vector3]    # uint64 components
59
vec3h = typing.Type[Vector3]     # float16 components
60
vec3f = typing.Type[Vector3]     # float32 components
61
vec3d = typing.Type[Vector3]     # float64 components
62

63
# 4D vectors with different component types  
64
vec4 = typing.Type[Vector4]      # float32 components
65
vec4b = typing.Type[Vector4]     # int8 components
66
vec4ub = typing.Type[Vector4]    # uint8 components
67
vec4s = typing.Type[Vector4]     # int16 components
68
vec4us = typing.Type[Vector4]    # uint16 components
69
vec4i = typing.Type[Vector4]     # int32 components
70
vec4ui = typing.Type[Vector4]    # uint32 components
71
vec4l = typing.Type[Vector4]     # int64 components
72
vec4ul = typing.Type[Vector4]    # uint64 components
73
vec4h = typing.Type[Vector4]     # float16 components
74
vec4f = typing.Type[Vector4]     # float32 components
75
vec4d = typing.Type[Vector4]     # float64 components
76
```
77

78
### Matrix Types
79

80
Square matrix types for linear algebra and transformations.
81

82
```python { .api }
83
# 2x2 matrices
84
mat22 = typing.Type[Matrix22]    # float32 components
85
mat22h = typing.Type[Matrix22]   # float16 components  
86
mat22f = typing.Type[Matrix22]   # float32 components
87
mat22d = typing.Type[Matrix22]   # float64 components
88

89
# 3x3 matrices
90
mat33 = typing.Type[Matrix33]    # float32 components
91
mat33h = typing.Type[Matrix33]   # float16 components
92
mat33f = typing.Type[Matrix33]   # float32 components  
93
mat33d = typing.Type[Matrix33]   # float64 components
94

95
# 4x4 matrices
96
mat44 = typing.Type[Matrix44]    # float32 components
97
mat44h = typing.Type[Matrix44]   # float16 components
98
mat44f = typing.Type[Matrix44]   # float32 components
99
mat44d = typing.Type[Matrix44]   # float64 components
100
```
101

102
### Quaternion and Transform Types
103

104
Specialized types for 3D rotations and transformations.
105

106
```python { .api }
107
# Quaternions for rotations
108
quat = typing.Type[Quaternion]    # float32 components
109
quath = typing.Type[Quaternion]   # float16 components
110
quatf = typing.Type[Quaternion]   # float32 components  
111
quatd = typing.Type[Quaternion]   # float64 components
112

113
# 3D transforms (rotation + translation)
114
transform = typing.Type[Transform]    # float32 components
115
transformh = typing.Type[Transform]   # float16 components
116
transformf = typing.Type[Transform]   # float32 components
117
transformd = typing.Type[Transform]   # float64 components
118
```
119

120
### Spatial Mathematics Types
121

122
Specialized types for spatial mechanics and robotics.
123

124
```python { .api }
125
# 6D spatial vectors (angular + linear velocity/force)
126
spatial_vector = typing.Type[SpatialVector]    # float32 components
127
spatial_vectorh = typing.Type[SpatialVector]   # float16 components
128
spatial_vectorf = typing.Type[SpatialVector]   # float32 components
129
spatial_vectord = typing.Type[SpatialVector]   # float64 components
130

131
# 6x6 spatial matrices (inertia, compliance)
132
spatial_matrix = typing.Type[SpatialMatrix]    # float32 components
133
spatial_matrixh = typing.Type[SpatialMatrix]   # float16 components
134
spatial_matrixf = typing.Type[SpatialMatrix]   # float32 components
135
spatial_matrixd = typing.Type[SpatialMatrix]   # float64 components
136
```
137

138
### Array Types
139

140
Multi-dimensional arrays with device-aware memory management.
141

142
```python { .api }
143
class array:
144
    """
145
    Multi-dimensional array with device-aware memory management.
146
    
147
    Attributes:
148
        shape: Tuple of dimension sizes
149
        dtype: Element data type
150
        device: Device where array is stored
151
        size: Total number of elements
152
    """
153
    
154
    def __init__(self, data=None, dtype=float32, shape=None, device=None):
155
        """
156
        Create array from data or with specified shape.
157
        
158
        Args:
159
            data: Initial data (numpy array, list, or scalar)
160
            dtype: Element type (warp type or numpy dtype)
161
            shape: Array dimensions if data is None
162
            device: Target device for array storage
163
        """
164
    
165
    def numpy(self) -> np.ndarray:
166
        """Convert to NumPy array (copies from device if needed)."""
167
    
168
    def __getitem__(self, key):
169
        """Get array element or slice."""
170
    
171
    def __setitem__(self, key, value):
172
        """Set array element or slice."""
173

174
# Type aliases for common array dimensions
175
array1d = array  # 1D array
176
array2d = array  # 2D array
177
array3d = array  # 3D array
178
array4d = array  # 4D array
179

180
# Indexed arrays for sparse data access
181
indexedarray = typing.Type[IndexedArray]
182
indexedarray1d = typing.Type[IndexedArray]
183
indexedarray2d = typing.Type[IndexedArray]
184
indexedarray3d = typing.Type[IndexedArray]
185
indexedarray4d = typing.Type[IndexedArray]
186

187
# Fabric arrays for distributed computing
188
fabricarray = typing.Type[FabricArray]
189
fabricarrayarray = typing.Type[FabricArrayArray]
190
indexedfabricarray = typing.Type[IndexedFabricArray]
191
indexedfabricarrayarray = typing.Type[IndexedFabricArrayArray]
192

193
# Tiled arrays for blocked algorithms
194
tile = typing.Type[Tile]
195
```
196

197
### Geometry Types
198

199
Spatial data structures for collision detection, ray tracing, and geometric queries.
200

201
```python { .api }
202
class Mesh:
203
    """Triangle mesh for collision detection and rendering."""
204
    
205
    def __init__(self, vertices: array, indices: array):
206
        """
207
        Create mesh from vertex positions and triangle indices.
208
        
209
        Args:
210
            vertices: Array of 3D vertex positions
211
            indices: Array of triangle vertex indices
212
        """
213

214
class Volume:
215
    """3D volume for sampling and level sets."""
216
    
217
    def __init__(self, data: array, transform: transform = None):
218
        """
219
        Create volume from 3D scalar field data.
220
        
221
        Args:
222
            data: 3D array of scalar values
223
            transform: World-space transformation
224
        """
225

226
class Bvh:
227
    """Bounding Volume Hierarchy for fast spatial queries."""
228
    
229
    def __init__(self, mesh: Mesh):
230
        """Build BVH from triangle mesh."""
231

232
class HashGrid:
233
    """Spatial hash grid for neighbor finding."""
234
    
235
    def __init__(self, dim_x: int, dim_y: int, dim_z: int):
236
        """Create hash grid with specified dimensions."""
237

238
class MarchingCubes:
239
    """Marching cubes for isosurface extraction."""
240
    
241
    def __init__(self):
242
        """Create marching cubes instance."""
243
```
244

245
### Query Types
246

247
Spatial query objects for geometric computations.
248

249
```python { .api }
250
class BvhQuery:
251
    """Query object for BVH spatial searches."""
252

253
class HashGridQuery:
254
    """Query object for hash grid neighbor searches."""
255

256
class MeshQueryAABB:
257
    """Axis-aligned bounding box mesh query."""
258

259
class MeshQueryPoint:
260
    """Point-to-mesh distance query."""
261

262
class MeshQueryRay:
263
    """Ray-mesh intersection query."""
264
```
265

266
### Utility Functions
267

268
Functions for creating and manipulating arrays and types.
269

270
```python { .api }
271
def constant(value, dtype: type = None):
272
    """Create compile-time constant value."""
273

274
def from_ptr(ptr: int, dtype: type, shape: tuple) -> array:
275
    """Create array from raw memory pointer."""
276

277
def from_ipc_handle(handle, dtype: type, shape: tuple) -> array:
278
    """Create array from CUDA IPC memory handle."""
279
```
280

281
### Type Annotations
282

283
Special types for kernel parameter annotations and generic programming.
284

285
```python { .api }
286
Int = typing.TypeVar('Int')        # Any integer type
287
Float = typing.TypeVar('Float')    # Any floating point type  
288
Scalar = typing.TypeVar('Scalar')  # Any numeric type
289
```
290

291
### NumPy Interoperability
292

293
Functions for converting between Warp and NumPy types.
294

295
```python { .api }
296
def dtype_from_numpy(np_dtype) -> type:
297
    """Convert NumPy dtype to Warp type."""
298

299
def dtype_to_numpy(wp_dtype: type):
300
    """Convert Warp type to NumPy dtype."""
301
```
302

303
## Usage Examples
304

305
### Vector Operations
306
```python
307
import warp as wp
308

309
# Create 3D vectors
310
pos = wp.vec3(1.0, 2.0, 3.0)
311
vel = wp.vec3(0.1, 0.2, 0.3)
312

313
# Vector operations available in kernels
314
@wp.kernel
315
def update_positions(positions: wp.array(dtype=wp.vec3),
316
                    velocities: wp.array(dtype=wp.vec3),
317
                    dt: float):
318
    i = wp.tid()
319
    positions[i] = positions[i] + velocities[i] * dt
320
```
321

322
### Matrix Transformations
323
```python
324
# 4x4 transformation matrix
325
transform_matrix = wp.mat44(
326
    1.0, 0.0, 0.0, 0.0,
327
    0.0, 1.0, 0.0, 0.0, 
328
    0.0, 0.0, 1.0, 0.0,
329
    0.0, 0.0, 0.0, 1.0
330
)
331

332
# Quaternion rotation
333
rotation = wp.quat(0.0, 0.0, 0.0, 1.0)  # Identity rotation
334
```
335

336
### Array Creation and Access
337
```python
338
import numpy as np
339

340
# Create arrays on different devices
341
cpu_array = wp.zeros(1000, dtype=wp.float32, device="cpu")
342
gpu_array = wp.ones((100, 100), dtype=wp.vec3, device="cuda:0")
343

344
# Convert from NumPy
345
np_data = np.random.rand(1000).astype(np.float32)
346
wp_array = wp.from_numpy(np_data, device="cuda:0")
347

348
# Access data
349
result = wp_array.numpy()  # Copy back to NumPy
350
```
351

352
## Types
353

354
```python { .api }
355
# Vector component access (available in kernels)
356
class Vector2:
357
    x: float
358
    y: float
359

360
class Vector3:
361
    x: float
362
    y: float
363
    z: float
364

365
class Vector4:
366
    x: float
367
    y: float
368
    z: float
369
    w: float
370

371
# Matrix types
372
class Matrix22:
373
    def __getitem__(self, key: tuple[int, int]) -> float: ...
374

375
class Matrix33:
376
    def __getitem__(self, key: tuple[int, int]) -> float: ...
377

378
class Matrix44:
379
    def __getitem__(self, key: tuple[int, int]) -> float: ...
380

381
# Quaternion type
382
class Quaternion:
383
    x: float  # i component
384
    y: float  # j component  
385
    z: float  # k component
386
    w: float  # real component
387

388
# Transform type (rotation + translation)
389
class Transform:
390
    p: vec3  # translation
391
    q: quat  # rotation
392
```