0
# Array Manipulation
1

2
Array manipulation operations that transform array structure, shape, and organization. These functions provide comprehensive tools for reshaping, transposing, joining, splitting, and rearranging GPU arrays while maintaining optimal memory layout and performance.
3

4
## Capabilities
5

6
### Shape Manipulation
7

8
Functions for changing array dimensions and structure.
9

10
```python { .api }
11
def reshape(a, newshape, order='C'):
12
    """
13
    Gives a new shape to an array without changing its data.
14
    
15
    Parameters:
16
    - a: array_like, input array
17
    - newshape: int or tuple of ints, new shape
18
    - order: {'C', 'F', 'A'}, read elements order
19
    
20
    Returns:
21
    cupy.ndarray: reshaped array
22
    """
23

24
def ravel(a, order='C'):
25
    """
26
    Return a contiguous flattened array.
27
    
28
    Parameters:
29
    - a: array_like, input array
30
    - order: {'C', 'F', 'A', 'K'}, read elements order
31
    
32
    Returns:
33
    cupy.ndarray: 1-D array
34
    """
35

36
def shape(a):
37
    """
38
    Return the shape of an array.
39
    
40
    Parameters:
41
    - a: array_like, input array
42
    
43
    Returns:
44
    tuple of ints: shape of array
45
    """
46
```
47

48
### Transpose Operations
49

50
Functions for rearranging array axes.
51

52
```python { .api }
53
def transpose(a, axes=None):
54
    """
55
    Reverse or permute the axes of an array.
56
    
57
    Parameters:
58
    - a: array_like, input array
59
    - axes: tuple or list of ints, permutation of axes
60
    
61
    Returns:
62
    cupy.ndarray: transposed array
63
    """
64

65
def swapaxes(a, axis1, axis2):
66
    """
67
    Interchange two axes of an array.
68
    
69
    Parameters:
70
    - a: array_like, input array
71
    - axis1: int, first axis
72
    - axis2: int, second axis
73
    
74
    Returns:
75
    cupy.ndarray: array with swapped axes
76
    """
77

78
def moveaxis(a, source, destination):
79
    """
80
    Move axes of an array to new positions.
81
    
82
    Parameters:
83
    - a: array_like, input array
84
    - source: int or sequence of int, original positions
85
    - destination: int or sequence of int, destination positions
86
    
87
    Returns:
88
    cupy.ndarray: array with moved axes
89
    """
90

91
def rollaxis(a, axis, start=0):
92
    """
93
    Roll the specified axis backwards.
94
    
95
    Parameters:
96
    - a: array_like, input array
97
    - axis: int, axis to roll backwards
98
    - start: int, position to roll before
99
    
100
    Returns:
101
    cupy.ndarray: array with rolled axis
102
    """
103
```
104

105
### Dimension Manipulation
106

107
Functions for adding or removing array dimensions.
108

109
```python { .api }
110
def expand_dims(a, axis):
111
    """
112
    Expand the shape of an array by inserting new axes.
113
    
114
    Parameters:
115
    - a: array_like, input array
116
    - axis: int or tuple of ints, position of new axes
117
    
118
    Returns:
119
    cupy.ndarray: array with expanded dimensions
120
    """
121

122
def squeeze(a, axis=None):
123
    """
124
    Remove single-dimensional entries from array shape.
125
    
126
    Parameters:
127
    - a: array_like, input array
128
    - axis: None, int, or tuple of ints, axes to squeeze
129
    
130
    Returns:
131
    cupy.ndarray: squeezed array
132
    """
133

134
def atleast_1d(*arys):
135
    """
136
    Convert inputs to arrays with at least one dimension.
137
    
138
    Parameters:
139
    - arys: array_like, input arrays
140
    
141
    Returns:
142
    list of cupy.ndarray: arrays with at least 1-D
143
    """
144

145
def atleast_2d(*arys):
146
    """
147
    View inputs as arrays with at least two dimensions.
148
    
149
    Parameters:
150
    - arys: array_like, input arrays
151
    
152
    Returns:
153
    list of cupy.ndarray: arrays with at least 2-D
154
    """
155

156
def atleast_3d(*arys):
157
    """
158
    View inputs as arrays with at least three dimensions.
159
    
160
    Parameters:
161
    - arys: array_like, input arrays
162
    
163
    Returns:
164
    list of cupy.ndarray: arrays with at least 3-D
165
    """
166
```
167

168
### Broadcasting
169

170
Functions for broadcasting arrays to compatible shapes.
171

172
```python { .api }
173
def broadcast(*args):
174
    """
175
    Produce an object that mimics broadcasting.
176
    
177
    Parameters:
178
    - args: array_like, input arrays
179
    
180
    Returns:
181
    broadcast object
182
    """
183

184
def broadcast_arrays(*args, **kwargs):
185
    """
186
    Broadcast any number of arrays against each other.
187
    
188
    Parameters:
189
    - args: array_like, input arrays
190
    
191
    Returns:
192
    list of cupy.ndarray: broadcasted arrays
193
    """
194

195
def broadcast_to(array, shape, subok=False):
196
    """
197
    Broadcast an array to a new shape.
198
    
199
    Parameters:
200
    - array: array_like, input array
201
    - shape: tuple, target shape
202
    - subok: bool, whether to allow subclasses
203
    
204
    Returns:
205
    cupy.ndarray: broadcasted array
206
    """
207
```
208

209
### Joining Arrays
210

211
Functions for combining multiple arrays.
212

213
```python { .api }
214
def concatenate(arrays, axis=0, out=None, dtype=None, casting="same_kind"):
215
    """
216
    Join a sequence of arrays along an existing axis.
217
    
218
    Parameters:
219
    - arrays: sequence of array_like, arrays to concatenate
220
    - axis: int, axis along which arrays are joined
221
    - out: cupy.ndarray, optional output array
222
    - dtype: str or dtype, output array data type
223
    - casting: str, casting rule
224
    
225
    Returns:
226
    cupy.ndarray: concatenated array
227
    """
228

229
def stack(arrays, axis=0, out=None):
230
    """
231
    Join a sequence of arrays along a new axis.
232
    
233
    Parameters:
234
    - arrays: sequence of array_like, arrays to stack
235
    - axis: int, axis along which arrays are stacked
236
    - out: cupy.ndarray, optional output array
237
    
238
    Returns:
239
    cupy.ndarray: stacked array
240
    """
241

242
def vstack(arrays):
243
    """
244
    Stack arrays in sequence vertically (row wise).
245
    
246
    Parameters:
247
    - arrays: sequence of array_like, arrays to stack
248
    
249
    Returns:
250
    cupy.ndarray: stacked array
251
    """
252

253
def hstack(arrays):
254
    """
255
    Stack arrays in sequence horizontally (column wise).
256
    
257
    Parameters:
258
    - arrays: sequence of array_like, arrays to stack
259
    
260
    Returns:
261
    cupy.ndarray: stacked array
262
    """
263

264
def dstack(arrays):
265
    """
266
    Stack arrays in sequence depth wise (along third axis).
267
    
268
    Parameters:
269
    - arrays: sequence of array_like, arrays to stack
270
    
271
    Returns:
272
    cupy.ndarray: stacked array
273
    """
274

275
def column_stack(arrays):
276
    """
277
    Stack 1-D arrays as columns into a 2-D array.
278
    
279
    Parameters:
280
    - arrays: sequence of 1-D array_like, arrays to stack
281
    
282
    Returns:
283
    cupy.ndarray: 2-D stacked array
284
    """
285
```
286

287
### Splitting Arrays
288

289
Functions for dividing arrays into sub-arrays.
290

291
```python { .api }
292
def split(ary, indices_or_sections, axis=0):
293
    """
294
    Split an array into multiple sub-arrays.
295
    
296
    Parameters:
297
    - ary: cupy.ndarray, input array
298
    - indices_or_sections: int or 1-D array, split points
299
    - axis: int, axis along which to split
300
    
301
    Returns:
302
    list of cupy.ndarray: sub-arrays
303
    """
304

305
def array_split(ary, indices_or_sections, axis=0):
306
    """
307
    Split an array into multiple sub-arrays of equal or near-equal size.
308
    
309
    Parameters:
310
    - ary: cupy.ndarray, input array
311
    - indices_or_sections: int or 1-D array, split points
312
    - axis: int, axis along which to split
313
    
314
    Returns:
315
    list of cupy.ndarray: sub-arrays
316
    """
317

318
def hsplit(ary, indices_or_sections):
319
    """
320
    Split an array into multiple sub-arrays horizontally.
321
    
322
    Parameters:
323
    - ary: cupy.ndarray, input array
324
    - indices_or_sections: int or 1-D array, split points
325
    
326
    Returns:
327
    list of cupy.ndarray: sub-arrays
328
    """
329

330
def vsplit(ary, indices_or_sections):
331
    """
332
    Split an array into multiple sub-arrays vertically.
333
    
334
    Parameters:
335
    - ary: cupy.ndarray, input array
336
    - indices_or_sections: int or 1-D array, split points
337
    
338
    Returns:
339
    list of cupy.ndarray: sub-arrays
340
    """
341

342
def dsplit(ary, indices_or_sections):
343
    """
344
    Split array into multiple sub-arrays along the 3rd axis (depth).
345
    
346
    Parameters:
347
    - ary: cupy.ndarray, input array
348
    - indices_or_sections: int or 1-D array, split points
349
    
350
    Returns:
351
    list of cupy.ndarray: sub-arrays
352
    """
353
```
354

355
### Tiling and Repeating
356

357
Functions for creating repetitions of arrays.
358

359
```python { .api }
360
def tile(A, reps):
361
    """
362
    Construct an array by repeating A the number of times given by reps.
363
    
364
    Parameters:
365
    - A: array_like, input array
366
    - reps: int or sequence of ints, repetitions
367
    
368
    Returns:
369
    cupy.ndarray: tiled array
370
    """
371

372
def repeat(a, repeats, axis=None):
373
    """
374
    Repeat elements of an array.
375
    
376
    Parameters:
377
    - a: array_like, input array
378
    - repeats: int or array of ints, repetitions for each element
379
    - axis: int, axis along which to repeat
380
    
381
    Returns:
382
    cupy.ndarray: repeated array
383
    """
384
```
385

386
### Adding and Removing Elements
387

388
Functions for modifying array contents.
389

390
```python { .api }
391
def append(arr, values, axis=None):
392
    """
393
    Append values to the end of an array.
394
    
395
    Parameters:
396
    - arr: array_like, input array
397
    - values: array_like, values to append
398
    - axis: int, axis along which to append
399
    
400
    Returns:
401
    cupy.ndarray: array with appended values
402
    """
403

404
def resize(a, new_shape):
405
    """
406
    Return a new array with the specified shape.
407
    
408
    Parameters:
409
    - a: array_like, input array
410
    - new_shape: int or tuple of int, new shape
411
    
412
    Returns:
413
    cupy.ndarray: resized array
414
    """
415

416
def unique(ar, return_index=False, return_inverse=False, return_counts=False, axis=None):
417
    """
418
    Find the unique elements of an array.
419
    
420
    Parameters:
421
    - ar: array_like, input array
422
    - return_index: bool, return indices of unique elements
423
    - return_inverse: bool, return inverse indices
424
    - return_counts: bool, return counts of unique elements
425
    - axis: int, axis to operate on
426
    
427
    Returns:
428
    cupy.ndarray or tuple: unique elements and optional arrays
429
    """
430

431
def trim_zeros(filt, trim='fb'):
432
    """
433
    Trim the leading and/or trailing zeros from a 1-D array.
434
    
435
    Parameters:
436
    - filt: 1-D array_like, input array
437
    - trim: str, trimming behavior
438
    
439
    Returns:
440
    cupy.ndarray: trimmed array
441
    """
442
```
443

444
### Rearranging Elements
445

446
Functions for reordering array elements.
447

448
```python { .api }
449
def flip(m, axis=None):
450
    """
451
    Reverse the order of elements in an array along given axis.
452
    
453
    Parameters:
454
    - m: array_like, input array
455
    - axis: None, int, or tuple of ints, axis to flip
456
    
457
    Returns:
458
    cupy.ndarray: flipped array
459
    """
460

461
def fliplr(m):
462
    """
463
    Flip array in the left/right direction.
464
    
465
    Parameters:
466
    - m: array_like, input array
467
    
468
    Returns:
469
    cupy.ndarray: flipped array
470
    """
471

472
def flipud(m):
473
    """
474
    Flip array in the up/down direction.
475
    
476
    Parameters:
477
    - m: array_like, input array
478
    
479
    Returns:
480
    cupy.ndarray: flipped array
481
    """
482

483
def roll(a, shift, axis=None):
484
    """
485
    Roll array elements along a given axis.
486
    
487
    Parameters:
488
    - a: array_like, input array
489
    - shift: int or tuple of int, number of places to shift
490
    - axis: int or tuple of int, axis to roll
491
    
492
    Returns:
493
    cupy.ndarray: rolled array
494
    """
495

496
def rot90(m, k=1, axes=(0, 1)):
497
    """
498
    Rotate an array by 90 degrees in the plane specified by axes.
499
    
500
    Parameters:
501
    - m: array_like, input array
502
    - k: int, number of times to rotate
503
    - axes: tuple of int, plane of rotation
504
    
505
    Returns:
506
    cupy.ndarray: rotated array
507
    """
508
```
509

510
### Data Type and Memory Layout
511

512
Functions for controlling array memory layout and data types.
513

514
```python { .api }
515
def asfortranarray(a, dtype=None):
516
    """
517
    Return an array laid out in Fortran order in memory.
518
    
519
    Parameters:
520
    - a: array_like, input array
521
    - dtype: str or dtype, output data type
522
    
523
    Returns:
524
    cupy.ndarray: Fortran-ordered array
525
    """
526

527
def require(a, dtype=None, requirements=None):
528
    """
529
    Return an array which satisfies requirements.
530
    
531
    Parameters:
532
    - a: array_like, input array
533
    - dtype: str or dtype, required data type
534
    - requirements: str or list of str, requirements
535
    
536
    Returns:
537
    cupy.ndarray: array satisfying requirements
538
    """
539

540
def copyto(dst, src, casting='same_kind', where=True):
541
    """
542
    Copies values from one array to another, broadcasting as necessary.
543
    
544
    Parameters:
545
    - dst: cupy.ndarray, destination array
546
    - src: array_like, source array
547
    - casting: str, casting rule
548
    - where: array_like of bool, where to copy
549
    """
550
```