0
# Logic Functions
1

2
Logical operations and comparison functions including element-wise and array-wise logical operations, truth value testing, and type checking functions. These operations provide comprehensive tools for conditional logic, array comparison, and data validation on GPU arrays.
3

4
## Capabilities
5

6
### Element-wise Logical Operations
7

8
Logical operations applied element-wise to arrays.
9

10
```python { .api }
11
def logical_and(x1, x2, out=None, **kwargs):
12
    """
13
    Compute the truth value of x1 AND x2 element-wise.
14
    
15
    Parameters:
16
    - x1, x2: array_like, input arrays
17
    - out: cupy.ndarray, optional output array
18
    - **kwargs: additional keyword arguments
19
    
20
    Returns:
21
    cupy.ndarray: boolean array with logical AND results
22
    """
23

24
def logical_or(x1, x2, out=None, **kwargs):
25
    """
26
    Compute the truth value of x1 OR x2 element-wise.
27
    
28
    Parameters:
29
    - x1, x2: array_like, input arrays
30
    - out: cupy.ndarray, optional output array
31
    - **kwargs: additional keyword arguments
32
    
33
    Returns:
34
    cupy.ndarray: boolean array with logical OR results
35
    """
36

37
def logical_xor(x1, x2, out=None, **kwargs):
38
    """
39
    Compute the truth value of x1 XOR x2 element-wise.
40
    
41
    Parameters:
42
    - x1, x2: array_like, input arrays
43
    - out: cupy.ndarray, optional output array
44
    - **kwargs: additional keyword arguments
45
    
46
    Returns:
47
    cupy.ndarray: boolean array with logical XOR results
48
    """
49

50
def logical_not(x, out=None, **kwargs):
51
    """
52
    Compute the truth value of NOT x element-wise.
53
    
54
    Parameters:
55
    - x: array_like, input array
56
    - out: cupy.ndarray, optional output array
57
    - **kwargs: additional keyword arguments
58
    
59
    Returns:
60
    cupy.ndarray: boolean array with logical NOT results
61
    """
62
```
63

64
### Comparison Operations
65

66
Element-wise comparison functions returning boolean arrays.
67

68
```python { .api }
69
def equal(x1, x2, out=None, **kwargs):
70
    """
71
    Return (x1 == x2) element-wise.
72
    
73
    Parameters:
74
    - x1, x2: array_like, input arrays
75
    - out: cupy.ndarray, optional output array
76
    - **kwargs: additional keyword arguments
77
    
78
    Returns:
79
    cupy.ndarray: boolean array with equality comparison results
80
    """
81

82
def not_equal(x1, x2, out=None, **kwargs):
83
    """
84
    Return (x1 != x2) element-wise.
85
    
86
    Parameters:
87
    - x1, x2: array_like, input arrays
88
    - out: cupy.ndarray, optional output array
89
    - **kwargs: additional keyword arguments
90
    
91
    Returns:
92
    cupy.ndarray: boolean array with inequality comparison results
93
    """
94

95
def less(x1, x2, out=None, **kwargs):
96
    """
97
    Return (x1 < x2) element-wise.
98
    
99
    Parameters:
100
    - x1, x2: array_like, input arrays
101
    - out: cupy.ndarray, optional output array
102
    - **kwargs: additional keyword arguments
103
    
104
    Returns:
105
    cupy.ndarray: boolean array with less-than comparison results
106
    """
107

108
def less_equal(x1, x2, out=None, **kwargs):
109
    """
110
    Return (x1 <= x2) element-wise.
111
    
112
    Parameters:
113
    - x1, x2: array_like, input arrays
114
    - out: cupy.ndarray, optional output array
115
    - **kwargs: additional keyword arguments
116
    
117
    Returns:
118
    cupy.ndarray: boolean array with less-equal comparison results
119
    """
120

121
def greater(x1, x2, out=None, **kwargs):
122
    """
123
    Return (x1 > x2) element-wise.
124
    
125
    Parameters:
126
    - x1, x2: array_like, input arrays
127
    - out: cupy.ndarray, optional output array
128
    - **kwargs: additional keyword arguments
129
    
130
    Returns:
131
    cupy.ndarray: boolean array with greater-than comparison results
132
    """
133

134
def greater_equal(x1, x2, out=None, **kwargs):
135
    """
136
    Return (x1 >= x2) element-wise.
137
    
138
    Parameters:
139
    - x1, x2: array_like, input arrays
140
    - out: cupy.ndarray, optional output array
141
    - **kwargs: additional keyword arguments
142
    
143
    Returns:
144
    cupy.ndarray: boolean array with greater-equal comparison results
145
    """
146
```
147

148
### Array Comparison Functions
149

150
Functions for comparing entire arrays and testing for approximate equality.
151

152
```python { .api }
153
def allclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False):
154
    """
155
    Returns True if two arrays are element-wise equal within a tolerance.
156
    
157
    Parameters:
158
    - a, b: array_like, input arrays to compare
159
    - rtol: float, relative tolerance parameter
160
    - atol: float, absolute tolerance parameter
161
    - equal_nan: bool, whether to compare NaN's as equal
162
    
163
    Returns:
164
    bool: True if arrays are close within tolerance
165
    """
166

167
def array_equal(a1, a2, equal_nan=False):
168
    """
169
    True if two arrays have the same shape and elements, False otherwise.
170
    
171
    Parameters:
172
    - a1, a2: array_like, input arrays
173
    - equal_nan: bool, whether to compare NaN's as equal
174
    
175
    Returns:
176
    bool: True if arrays are equal
177
    """
178

179
def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False):
180
    """
181
    Returns a boolean array where two arrays are element-wise equal within tolerance.
182
    
183
    Parameters:
184
    - a, b: array_like, input arrays to compare
185
    - rtol: float, relative tolerance parameter
186
    - atol: float, absolute tolerance parameter
187
    - equal_nan: bool, whether to compare NaN's as equal
188
    
189
    Returns:
190
    cupy.ndarray: boolean array indicating closeness
191
    """
192
```
193

194
### Content Testing
195

196
Functions for testing array content for special values.
197

198
```python { .api }
199
def isfinite(x, out=None, **kwargs):
200
    """
201
    Test finiteness element-wise (not infinity or not Not a Number).
202
    
203
    Parameters:
204
    - x: array_like, input array
205
    - out: cupy.ndarray, optional output array
206
    - **kwargs: additional keyword arguments
207
    
208
    Returns:
209
    cupy.ndarray: boolean array indicating finite elements
210
    """
211

212
def isinf(x, out=None, **kwargs):
213
    """
214
    Test for positive or negative infinity element-wise.
215
    
216
    Parameters:
217
    - x: array_like, input array
218
    - out: cupy.ndarray, optional output array
219
    - **kwargs: additional keyword arguments
220
    
221
    Returns:
222
    cupy.ndarray: boolean array indicating infinite elements
223
    """
224

225
def isnan(x, out=None, **kwargs):
226
    """
227
    Test for NaN element-wise and return result as a boolean array.
228
    
229
    Parameters:
230
    - x: array_like, input array
231
    - out: cupy.ndarray, optional output array
232
    - **kwargs: additional keyword arguments
233
    
234
    Returns:
235
    cupy.ndarray: boolean array indicating NaN elements
236
    """
237
```
238

239
### Type Testing
240

241
Functions for testing array data type properties.
242

243
```python { .api }
244
def iscomplex(x):
245
    """
246
    Returns a bool array, where True if input element is complex.
247
    
248
    Parameters:
249
    - x: array_like, input array
250
    
251
    Returns:
252
    cupy.ndarray: boolean array indicating complex elements
253
    """
254

255
def iscomplexobj(x):
256
    """
257
    Check for a complex type or an array of complex numbers.
258
    
259
    Parameters:
260
    - x: array_like, input array
261
    
262
    Returns:
263
    bool: True if x is complex type
264
    """
265

266
def isreal(x):
267
    """
268
    Returns a bool array, where True if input element is real.
269
    
270
    Parameters:
271
    - x: array_like, input array
272
    
273
    Returns:
274
    cupy.ndarray: boolean array indicating real elements
275
    """
276

277
def isrealobj(x):
278
    """
279
    Return True if x is a not complex type or an array of complex numbers.
280
    
281
    Parameters:
282
    - x: array_like, input array
283
    
284
    Returns:
285
    bool: True if x is real type
286
    """
287

288
def isfortran(a):
289
    """
290
    Check if the array is Fortran contiguous but *not* C contiguous.
291
    
292
    Parameters:
293
    - a: cupy.ndarray, input array
294
    
295
    Returns:
296
    bool: True if array is Fortran contiguous
297
    """
298

299
def isscalar(element):
300
    """
301
    Returns True if the type of element is a scalar type.
302
    
303
    Parameters:
304
    - element: any, input element
305
    
306
    Returns:
307
    bool: True if element is scalar
308
    """
309
```
310

311
### Truth Value Testing
312

313
Functions for testing array truth values and membership.
314

315
```python { .api }
316
def all(a, axis=None, out=None, keepdims=False):
317
    """
318
    Test whether all array elements along a given axis evaluate to True.
319
    
320
    Parameters:
321
    - a: array_like, input array
322
    - axis: None, int, or tuple of ints, axis along which to operate
323
    - out: cupy.ndarray, optional output array
324
    - keepdims: bool, whether to keep dimensions
325
    
326
    Returns:
327
    cupy.ndarray or bool: result of all operation
328
    """
329

330
def any(a, axis=None, out=None, keepdims=False):
331
    """
332
    Test whether any array element along a given axis evaluates to True.
333
    
334
    Parameters:
335
    - a: array_like, input array
336
    - axis: None, int, or tuple of ints, axis along which to operate
337
    - out: cupy.ndarray, optional output array
338
    - keepdims: bool, whether to keep dimensions
339
    
340
    Returns:
341
    cupy.ndarray or bool: result of any operation
342
    """
343

344
def in1d(ar1, ar2, assume_unique=False, invert=False):
345
    """
346
    Test whether each element of a 1-D array is also present in a second array.
347
    
348
    Parameters:
349
    - ar1: array_like, input array
350
    - ar2: array_like, values against which to test each element of ar1
351
    - assume_unique: bool, assume input arrays are unique
352
    - invert: bool, invert the boolean return array
353
    
354
    Returns:
355
    cupy.ndarray: boolean array of same shape as ar1
356
    """
357

358
def isin(element, test_elements, assume_unique=False, invert=False):
359
    """
360
    Calculates element in test_elements, broadcasting over element only.
361
    
362
    Parameters:
363
    - element: array_like, input array
364
    - test_elements: array_like, values against which to test each element
365
    - assume_unique: bool, assume input arrays are unique
366
    - invert: bool, invert the boolean return array
367
    
368
    Returns:
369
    cupy.ndarray: boolean array of same shape as element
370
    """
371
```
372

373
## Usage Examples
374

375
### Logical Operations
376

377
```python
378
import cupy as cp
379

380
# Create test arrays
381
a = cp.array([True, False, True, False])
382
b = cp.array([True, True, False, False])
383

384
# Logical AND
385
result_and = cp.logical_and(a, b)
386
print(result_and)  # [True False False False]
387

388
# Logical OR
389
result_or = cp.logical_or(a, b)
390
print(result_or)  # [True True True False]
391

392
# Logical NOT
393
result_not = cp.logical_not(a)
394
print(result_not)  # [False True False True]
395
```
396

397
### Comparison Operations
398

399
```python
400
import cupy as cp
401

402
# Create numeric arrays
403
x = cp.array([1, 2, 3, 4, 5])
404
y = cp.array([1, 3, 2, 4, 6])
405

406
# Element-wise comparisons
407
print(cp.equal(x, y))        # [True False False True False]
408
print(cp.less(x, y))         # [False True False False True]
409
print(cp.greater(x, y))      # [False False True False False]
410
```
411

412
### Content Testing
413

414
```python
415
import cupy as cp
416

417
# Array with special values
418
arr = cp.array([1.0, cp.inf, cp.nan, -cp.inf, 0.0])
419

420
# Test for finite values
421
finite_mask = cp.isfinite(arr)
422
print(finite_mask)  # [True False False False True]
423

424
# Test for infinite values
425
inf_mask = cp.isinf(arr)
426
print(inf_mask)  # [False True False True False]
427

428
# Test for NaN values
429
nan_mask = cp.isnan(arr)
430
print(nan_mask)  # [False False True False False]
431
```
432

433
### Array-wise Truth Testing
434

435
```python
436
import cupy as cp
437

438
# Boolean array
439
bool_arr = cp.array([[True, True], [False, True]])
440

441
# Test if all elements are True
442
all_true = cp.all(bool_arr)
443
print(all_true)  # False
444

445
# Test if any elements are True
446
any_true = cp.any(bool_arr)
447
print(any_true)  # True
448

449
# Test along specific axis
450
all_axis0 = cp.all(bool_arr, axis=0)
451
print(all_axis0)  # [False True]
452
```
453

454
### Membership Testing
455

456
```python
457
import cupy as cp
458

459
# Test array membership
460
elements = cp.array([1, 2, 3, 4, 5])
461
test_values = cp.array([2, 4, 6])
462

463
# Test which elements are in test_values
464
mask = cp.isin(elements, test_values)
465
print(mask)  # [False True False True False]
466

467
# Get elements that are in test_values
468
result = elements[mask]
469
print(result)  # [2 4]
470
```