0
# Utility Functions
1

2
General utility functions for array inspection, memory management, and CuPy-specific operations. These functions provide essential tools for working with GPU arrays and managing CuPy's runtime environment.
3

4
## Capabilities
5

6
### Array Information and Inspection
7

8
Functions to inspect array properties and get information about CuPy arrays.
9

10
```python { .api }
11
def get_array_module(*args):
12
    """
13
    Returns the array module for arguments.
14
    
15
    Parameters:
16
    - args: sequence of arrays or array-like objects
17
    
18
    Returns:
19
    module: cupy if any argument is cupy.ndarray, otherwise numpy
20
    """
21

22
def asnumpy(a, stream=None, blocking=True):
23
    """
24
    Returns a copy of the array on host memory.
25
    
26
    Parameters:
27
    - a: cupy.ndarray, input GPU array
28
    - stream: cupy.cuda.Stream, CUDA stream for the copy operation
29
    - blocking: bool, if True, synchronize before returning
30
    
31
    Returns:
32
    numpy.ndarray: copy of array on host memory
33
    """
34

35
def size(a, axis=None):
36
    """
37
    Return the number of elements along a given axis.
38
    
39
    Parameters:
40
    - a: cupy.ndarray, input array
41
    - axis: int or None, axis along which to count elements
42
    
43
    Returns:
44
    int: number of elements
45
    """
46

47
def shape(a):
48
    """
49
    Return the shape of an array.
50
    
51
    Parameters:
52
    - a: cupy.ndarray, input array
53
    
54
    Returns:
55
    tuple: shape tuple
56
    """
57

58
def ndim(a):
59
    """
60
    Return the number of dimensions of an array.
61
    
62
    Parameters:
63
    - a: cupy.ndarray, input array
64
    
65
    Returns:
66
    int: number of dimensions
67
    """
68
```
69

70
### Memory and Performance Utilities
71

72
Functions for memory management and performance monitoring specific to GPU operations.
73

74
```python { .api }
75
def get_default_memory_pool():
76
    """
77
    Gets the default memory pool for GPU memory allocation.
78
    
79
    Returns:
80
    cupy.cuda.MemoryPool: default memory pool instance
81
    """
82

83
def get_default_pinned_memory_pool():
84
    """
85
    Gets the default pinned memory pool for host memory allocation.
86
    
87
    Returns:
88
    cupy.cuda.PinnedMemoryPool: default pinned memory pool instance
89
    """
90

91
def may_share_memory(a, b, max_work=None):
92
    """
93
    Determine if two arrays might share memory.
94
    
95
    Parameters:
96
    - a: cupy.ndarray, first input array
97
    - b: cupy.ndarray, second input array  
98
    - max_work: int, maximum work to do in checking
99
    
100
    Returns:
101
    bool: True if arrays might share memory
102
    """
103

104
def shares_memory(a, b, max_work=None):
105
    """
106
    Determine if two arrays share memory.
107
    
108
    Parameters:
109
    - a: cupy.ndarray, first input array
110
    - b: cupy.ndarray, second input array
111
    - max_work: int, maximum work to do in checking
112
    
113
    Returns:
114
    bool: True if arrays definitely share memory
115
    """
116

117
def byte_bounds(a):
118
    """
119
    Returns pointers to the end-points of an array.
120
    
121
    Parameters:
122
    - a: cupy.ndarray, input array
123
    
124
    Returns:
125
    tuple: (low, high) memory addresses
126
    """
127
```
128

129
### Array Testing and Debugging
130

131
Functions for debugging and testing array operations.
132

133
```python { .api }
134
def who(vardict=None):
135
    """
136
    Print the CuPy arrays in the given dictionary.
137
    
138
    Parameters:
139
    - vardict: dict, dictionary to inspect (default: globals())
140
    
141
    Returns:
142
    None: prints array information to stdout
143
    """
144

145
def show_config():
146
    """
147
    Show CuPy build and runtime configuration information.
148
    
149
    Returns:
150
    None: prints configuration information to stdout
151
    """
152

153
def is_available():
154
    """
155
    Returns True if CuPy is available for use.
156
    
157
    Returns:
158
    bool: True if CUDA/ROCm is available and CuPy can be used
159
    """
160
```
161

162
### Functional Programming Utilities
163

164
Functions for functional programming patterns and advanced array operations.
165

166
```python { .api }
167
def vectorize(pyfunc, otypes=None, doc=None, excluded=None, cache=False,
168
             signature=None):
169
    """
170
    Returns an object that acts like pyfunc, but takes arrays as input.
171
    
172
    Parameters:
173
    - pyfunc: function, Python function to vectorize
174
    - otypes: str or list, output data type(s)
175
    - doc: str, docstring for vectorized function
176
    - excluded: set, set of strings or integers representing excluded arguments
177
    - cache: bool, whether to cache compiled kernels
178
    - signature: str, signature for universal function
179
    
180
    Returns:
181
    vectorized function object
182
    """
183

184
def piecewise(x, condlist, funclist, *args, **kw):
185
    """
186
    Evaluate a piecewise-defined function.
187
    
188
    Parameters:
189
    - x: cupy.ndarray, input domain
190
    - condlist: list of bool arrays or callables, conditions for each piece
191
    - funclist: list of functions or scalars, functions/values for each piece
192
    - args: additional arguments for functions in funclist
193
    - kw: additional keyword arguments for functions in funclist
194
    
195
    Returns:
196
    cupy.ndarray: evaluation of piecewise function
197
    """
198

199
def iterable(y):
200
    """
201
    Check whether or not an object can be iterated over.
202
    
203
    Parameters:
204
    - y: object, input object to check
205
    
206
    Returns:
207
    bool: True if object is iterable
208
    """
209
```
210

211
### Array Padding
212

213
Functions for padding arrays with various padding modes.
214

215
```python { .api }
216
def pad(array, pad_width, mode='constant', **kwargs):
217
    """
218
    Pad an array according to the given parameters.
219
    
220
    Parameters:
221
    - array: cupy.ndarray, array to pad
222
    - pad_width: sequence or int, padding width for each dimension
223
    - mode: str or function, padding mode
224
    - kwargs: additional arguments for padding mode
225
    
226
    Returns:
227
    cupy.ndarray: padded array
228
    """
229
```
230

231
### Type Utilities
232

233
Additional utilities for working with data types and type conversion.
234

235
```python { .api }
236
def binary_repr(num, width=None):
237
    """
238
    Return the binary representation of the input number as a string.
239
    
240
    Parameters:
241
    - num: int, input number
242
    - width: int, minimum width of output string
243
    
244
    Returns:
245
    str: binary representation
246
    """
247
```
248

249
### Usage Examples
250

251
```python
252
import cupy as cp
253
import numpy as np
254

255
# Array module detection
256
x_cpu = np.array([1, 2, 3])
257
x_gpu = cp.array([1, 2, 3])
258
module = cp.get_array_module(x_gpu)  # Returns cupy module
259
module_mixed = cp.get_array_module(x_cpu, x_gpu)  # Returns cupy module
260

261
# Memory transfer
262
gpu_array = cp.array([[1, 2, 3], [4, 5, 6]])
263
cpu_copy = cp.asnumpy(gpu_array)  # Transfer to CPU
264
print(type(cpu_copy))  # <class 'numpy.ndarray'>
265

266
# Array inspection
267
print(f"Size: {cp.size(gpu_array)}")  # Total elements
268
print(f"Shape: {cp.shape(gpu_array)}")  # Shape tuple
269
print(f"Dimensions: {cp.ndim(gpu_array)}")  # Number of dimensions
270

271
# Memory management
272
mempool = cp.get_default_memory_pool()
273
print(f"Memory used: {mempool.used_bytes()} bytes")
274
print(f"Memory free: {mempool.free_bytes()} bytes")
275

276
pinned_pool = cp.get_default_pinned_memory_pool()
277
print(f"Pinned memory used: {pinned_pool.used_bytes()} bytes")
278

279
# Memory sharing checks
280
a = cp.array([1, 2, 3, 4, 5])
281
b = a[1:4]  # View of a
282
print(cp.may_share_memory(a, b))  # True - b is a view of a
283
print(cp.shares_memory(a, b))     # True - definite sharing
284

285
c = cp.array([1, 2, 3])
286
print(cp.may_share_memory(a, c))  # False - different arrays
287

288
# System information
289
cp.show_config()  # Prints CuPy configuration
290
print(f"CuPy available: {cp.is_available()}")
291

292
# Debug information about arrays in scope
293
x = cp.array([1, 2, 3])
294
y = cp.random.rand(10, 10)
295
cp.who()  # Prints information about x and y
296

297
# Vectorize a Python function
298
def python_func(a, b):
299
    return a**2 + b**2
300

301
vectorized_func = cp.vectorize(python_func)
302
result = vectorized_func(cp.array([1, 2, 3]), cp.array([4, 5, 6]))
303

304
# Piecewise function
305
x = cp.linspace(-2, 2, 100)
306
conditions = [x < 0, x >= 0]
307
functions = [lambda x: x**2, lambda x: x**3]
308
y = cp.piecewise(x, conditions, functions)
309

310
# Array padding
311
arr = cp.array([[1, 2], [3, 4]])
312
padded = cp.pad(arr, pad_width=1, mode='constant', constant_values=0)
313
# Result: [[0, 0, 0, 0],
314
#          [0, 1, 2, 0], 
315
#          [0, 3, 4, 0],
316
#          [0, 0, 0, 0]]
317

318
# Binary representation
319
binary_str = cp.binary_repr(42, width=8)  # '00101010'
320

321
# Check if objects are iterable
322
print(cp.iterable([1, 2, 3]))  # True
323
print(cp.iterable(5))          # False
324
```