0
# Logic Functions
1

2
Logical operations, comparisons, and truth value testing for GPU arrays. These functions provide element-wise logical operations, array comparisons, and content testing essential for array manipulation and filtering.
3

4
## Capabilities
5

6
### Logical Operations
7

8
Element-wise logical operations on boolean and numeric arrays.
9

10
```python { .api }
11
def logical_and(x1, x2):
12
    """
13
    Compute truth value of x1 AND x2 element-wise.
14
    
15
    Parameters:
16
    - x1, x2: array-like, input arrays
17
    
18
    Returns:
19
    cupy.ndarray: Boolean result of logical AND
20
    """
21

22
def logical_or(x1, x2):
23
    """
24
    Compute truth value of x1 OR x2 element-wise.
25
    
26
    Parameters:
27
    - x1, x2: array-like, input arrays
28
    
29
    Returns:
30
    cupy.ndarray: Boolean result of logical OR
31
    """
32

33
def logical_not(x):
34
    """
35
    Compute truth value of NOT x element-wise.
36
    
37
    Parameters:
38
    - x: array-like, input array
39
    
40
    Returns:
41
    cupy.ndarray: Boolean result of logical NOT
42
    """
43

44
def logical_xor(x1, x2):
45
    """
46
    Compute truth value of x1 XOR x2 element-wise.
47
    
48
    Parameters:
49
    - x1, x2: array-like, input arrays
50
    
51
    Returns:
52
    cupy.ndarray: Boolean result of logical XOR
53
    """
54
```
55

56
### Comparison Operations
57

58
Element-wise comparison operations returning boolean arrays.
59

60
```python { .api }
61
def equal(x1, x2):
62
    """
63
    Return (x1 == x2) element-wise.
64
    
65
    Parameters:
66
    - x1, x2: array-like, input arrays
67
    
68
    Returns:
69
    cupy.ndarray: Boolean array of equality comparison
70
    """
71

72
def not_equal(x1, x2):
73
    """
74
    Return (x1 != x2) element-wise.
75
    
76
    Parameters:
77
    - x1, x2: array-like, input arrays
78
    
79
    Returns:
80
    cupy.ndarray: Boolean array of inequality comparison
81
    """
82

83
def less(x1, x2):
84
    """
85
    Return (x1 < x2) element-wise.
86
    
87
    Parameters:
88
    - x1, x2: array-like, input arrays
89
    
90
    Returns:
91
    cupy.ndarray: Boolean array of less-than comparison
92
    """
93

94
def less_equal(x1, x2):
95
    """
96
    Return (x1 <= x2) element-wise.
97
    
98
    Parameters:
99
    - x1, x2: array-like, input arrays
100
    
101
    Returns:
102
    cupy.ndarray: Boolean array of less-equal comparison
103
    """
104

105
def greater(x1, x2):
106
    """
107
    Return (x1 > x2) element-wise.
108
    
109
    Parameters:
110
    - x1, x2: array-like, input arrays
111
    
112
    Returns:
113
    cupy.ndarray: Boolean array of greater-than comparison
114
    """
115

116
def greater_equal(x1, x2):
117
    """
118
    Return (x1 >= x2) element-wise.
119
    
120
    Parameters:
121
    - x1, x2: array-like, input arrays
122
    
123
    Returns:
124
    cupy.ndarray: Boolean array of greater-equal comparison
125
    """
126
```
127

128
### Array Comparison Functions
129

130
Functions to compare entire arrays for equivalence and closeness within tolerance.
131

132
```python { .api }
133
def array_equal(a1, a2, equal_nan=False):
134
    """
135
    True if two arrays have the same shape and elements, False otherwise.
136
    
137
    Parameters:
138
    - a1, a2: cupy.ndarray, input arrays
139
    - equal_nan: bool, whether to compare NaN values as equal
140
    
141
    Returns:
142
    bool: True if arrays are equal
143
    """
144

145
def array_equiv(a1, a2):
146
    """
147
    Returns True if arrays are element-wise equal within broadcasting.
148
    
149
    Parameters:
150
    - a1, a2: array-like, input arrays
151
    
152
    Returns:
153
    bool: True if arrays are equivalent
154
    """
155

156
def allclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False):
157
    """
158
    Returns True if two arrays are element-wise equal within tolerance.
159
    
160
    Parameters:
161
    - a, b: array-like, input arrays
162
    - rtol: float, relative tolerance parameter
163
    - atol: float, absolute tolerance parameter
164
    - equal_nan: bool, whether to compare NaN values as equal
165
    
166
    Returns:
167
    bool: True if arrays are close within tolerance
168
    """
169

170
def isclose(a, b, rtol=1e-05, atol=1e-08, equal_nan=False):
171
    """
172
    Returns boolean array where two arrays are element-wise equal within tolerance.
173
    
174
    Parameters:
175
    - a, b: array-like, input arrays
176
    - rtol: float, relative tolerance parameter
177
    - atol: float, absolute tolerance parameter
178
    - equal_nan: bool, whether to compare NaN values as equal
179
    
180
    Returns:
181
    cupy.ndarray: Boolean array indicating closeness element-wise
182
    """
183
```
184

185
### Truth Value Testing
186

187
Functions to test truth values across arrays and determine overall boolean state.
188

189
```python { .api }
190
def all(a, axis=None, out=None, keepdims=False):
191
    """
192
    Test whether all array elements along given axis evaluate to True.
193
    
194
    Parameters:
195
    - a: array-like, input array
196
    - axis: None or int or tuple, axis along which logical AND is performed
197
    - out: cupy.ndarray, alternative output array
198
    - keepdims: bool, whether to retain reduced dimensions
199
    
200
    Returns:
201
    cupy.ndarray or bool: True if all elements are True
202
    """
203

204
def any(a, axis=None, out=None, keepdims=False):
205
    """
206
    Test whether any array element along given axis evaluates to True.
207
    
208
    Parameters:
209
    - a: array-like, input array
210
    - axis: None or int or tuple, axis along which logical OR is performed
211
    - out: cupy.ndarray, alternative output array
212
    - keepdims: bool, whether to retain reduced dimensions
213
    
214
    Returns:
215
    cupy.ndarray or bool: True if any element is True
216
    """
217

218
def alltrue(a, axis=None, out=None, keepdims=False):
219
    """
220
    Test whether all array elements along given axis evaluate to True.
221
    Alias for all().
222
    
223
    Parameters:
224
    - a: array-like, input array
225
    - axis: None or int or tuple, axis along which to test
226
    - out: cupy.ndarray, alternative output array
227
    - keepdims: bool, whether to retain reduced dimensions
228
    
229
    Returns:
230
    cupy.ndarray or bool: True if all elements are True
231
    """
232

233
def sometrue(a, axis=None, out=None, keepdims=False):
234
    """
235
    Test whether some array elements along given axis evaluate to True.
236
    Alias for any().
237
    
238
    Parameters:
239
    - a: array-like, input array
240
    - axis: None or int or tuple, axis along which to test
241
    - out: cupy.ndarray, alternative output array
242
    - keepdims: bool, whether to retain reduced dimensions
243
    
244
    Returns:
245
    cupy.ndarray or bool: True if any element is True
246
    """
247
```
248

249
### Content Testing
250

251
Functions to test array content for special values like NaN, infinity, and data types.
252

253
```python { .api }
254
def isfinite(x):
255
    """
256
    Test finiteness element-wise (not infinity or NaN).
257
    
258
    Parameters:
259
    - x: array-like, input array
260
    
261
    Returns:
262
    cupy.ndarray: Boolean array indicating finite elements
263
    """
264

265
def isinf(x):
266
    """
267
    Test for positive or negative infinity element-wise.
268
    
269
    Parameters:
270
    - x: array-like, input array
271
    
272
    Returns:
273
    cupy.ndarray: Boolean array indicating infinite elements
274
    """
275

276
def isnan(x):
277
    """
278
    Test for NaN element-wise.
279
    
280
    Parameters:
281
    - x: array-like, input array
282
    
283
    Returns:
284
    cupy.ndarray: Boolean array indicating NaN elements
285
    """
286

287
def isneginf(x, out=None):
288
    """
289
    Test for negative infinity element-wise.
290
    
291
    Parameters:
292
    - x: array-like, input array
293
    - out: cupy.ndarray, alternative output array
294
    
295
    Returns:
296
    cupy.ndarray: Boolean array indicating negative infinity
297
    """
298

299
def isposinf(x, out=None):
300
    """
301
    Test for positive infinity element-wise.
302
    
303
    Parameters:
304
    - x: array-like, input array
305
    - out: cupy.ndarray, alternative output array
306
    
307
    Returns:
308
    cupy.ndarray: Boolean array indicating positive infinity
309
    """
310

311
def isreal(x):
312
    """
313
    Returns True for real elements, False for complex elements.
314
    
315
    Parameters:
316
    - x: array-like, input array
317
    
318
    Returns:
319
    cupy.ndarray: Boolean array indicating real elements
320
    """
321

322
def iscomplex(x):
323
    """
324
    Returns True for complex elements, False for real elements.
325
    
326
    Parameters:
327
    - x: array-like, input array
328
    
329
    Returns:
330
    cupy.ndarray: Boolean array indicating complex elements
331
    """
332

333
def isrealobj(x):
334
    """
335
    Return True if x is not a complex type or an array of complex numbers.
336
    
337
    Parameters:
338
    - x: array-like, input array or scalar
339
    
340
    Returns:
341
    bool: True if object is real (not complex)
342
    """
343

344
def iscomplexobj(x):
345
    """
346
    Return True if x is a complex type or an array of complex numbers.
347
    
348
    Parameters:
349
    - x: array-like, input array or scalar
350
    
351
    Returns:
352
    bool: True if object is complex
353
    """
354

355
def isfortran(a):
356
    """
357
    Check if array is Fortran contiguous but not C contiguous.
358
    
359
    Parameters:
360
    - a: cupy.ndarray, input array
361
    
362
    Returns:
363
    bool: True if array is Fortran contiguous
364
    """
365
```
366

367
### Set Operations
368

369
Functions for set-like operations on arrays including membership testing and set algebra.
370

371
```python { .api }
372
def in1d(ar1, ar2, assume_unique=False, invert=False):
373
    """
374
    Test whether each element of ar1 is also present in ar2.
375
    
376
    Parameters:
377
    - ar1: array-like, input array
378
    - ar2: array-like, values against which to test
379
    - assume_unique: bool, whether input arrays are unique
380
    - invert: bool, whether to invert the result
381
    
382
    Returns:
383
    cupy.ndarray: Boolean array of same shape as ar1
384
    """
385

386
def isin(element, test_elements, assume_unique=False, invert=False):
387
    """
388
    Calculates element in test_elements, broadcasting over element only.
389
    
390
    Parameters:
391
    - element: array-like, input array
392
    - test_elements: array-like, values against which to test
393
    - assume_unique: bool, whether test_elements is unique
394
    - invert: bool, whether to invert the result
395
    
396
    Returns:
397
    cupy.ndarray: Boolean array of same shape as element
398
    """
399

400
def intersect1d(ar1, ar2, assume_unique=False, return_indices=False):
401
    """
402
    Find intersection of two arrays.
403
    
404
    Parameters:
405
    - ar1, ar2: array-like, input arrays
406
    - assume_unique: bool, whether input arrays are unique
407
    - return_indices: bool, whether to return indices
408
    
409
    Returns:
410
    cupy.ndarray: sorted 1D array of common and unique elements
411
    """
412

413
def setdiff1d(ar1, ar2, assume_unique=False):
414
    """
415
    Find set difference of two arrays.
416
    
417
    Parameters:
418
    - ar1: array-like, input array
419
    - ar2: array-like, values to remove from ar1
420
    - assume_unique: bool, whether input arrays are unique
421
    
422
    Returns:
423
    cupy.ndarray: 1D array of values in ar1 that are not in ar2
424
    """
425

426
def setxor1d(ar1, ar2, assume_unique=False):
427
    """
428
    Find set exclusive-or of two arrays.
429
    
430
    Parameters:
431
    - ar1, ar2: array-like, input arrays
432
    - assume_unique: bool, whether input arrays are unique
433
    
434
    Returns:
435
    cupy.ndarray: sorted 1D array of unique values in only one array
436
    """
437

438
def union1d(ar1, ar2):
439
    """
440
    Find union of two arrays.
441
    
442
    Parameters:
443
    - ar1, ar2: array-like, input arrays
444
    
445
    Returns:
446
    cupy.ndarray: unique, sorted union of input arrays
447
    """
448
```
449

450
### Usage Examples
451

452
```python
453
import cupy as cp
454

455
# Logical operations
456
a = cp.array([True, False, True, False])
457
b = cp.array([True, True, False, False])
458

459
logical_and_result = cp.logical_and(a, b)  # [True, False, False, False]
460
logical_or_result = cp.logical_or(a, b)    # [True, True, True, False]
461
logical_not_result = cp.logical_not(a)     # [False, True, False, True]
462
logical_xor_result = cp.logical_xor(a, b)  # [False, True, True, False]
463

464
# Comparison operations
465
x = cp.array([1, 2, 3, 4, 5])
466
y = cp.array([1, 3, 2, 4, 6])
467

468
equal_result = cp.equal(x, y)           # [True, False, False, True, False]
469
less_result = cp.less(x, y)             # [False, True, False, False, True]
470
greater_result = cp.greater(x, y)       # [False, False, True, False, False]
471

472
# Array comparison
473
arr1 = cp.array([[1, 2], [3, 4]])
474
arr2 = cp.array([[1, 2], [3, 4]])
475
arr3 = cp.array([[1.0, 2.0], [3.0, 4.0001]])
476

477
arrays_equal = cp.array_equal(arr1, arr2)  # True
478
arrays_close = cp.allclose(arr1, arr3, rtol=1e-3)  # True
479

480
# Element-wise closeness
481
close_elements = cp.isclose(arr1, arr3, rtol=1e-3)  # [[True, True], [True, True]]
482

483
# Truth value testing
484
bool_array = cp.array([True, False, True, True])
485
all_true = cp.all(bool_array)   # False
486
any_true = cp.any(bool_array)   # True
487

488
# Content testing
489
float_array = cp.array([1.0, cp.inf, cp.nan, -cp.inf, 2.5])
490
finite_mask = cp.isfinite(float_array)   # [True, False, False, False, True]
491
inf_mask = cp.isinf(float_array)         # [False, True, False, True, False]
492
nan_mask = cp.isnan(float_array)         # [False, False, True, False, False]
493

494
# Complex number testing
495
complex_array = cp.array([1+2j, 3, 4+0j, 5j])
496
real_mask = cp.isreal(complex_array)     # [False, True, True, False]
497
complex_mask = cp.iscomplex(complex_array)  # [True, False, False, True]
498

499
# Set operations
500
set1 = cp.array([1, 2, 3, 4, 5])
501
set2 = cp.array([3, 4, 5, 6, 7])
502

503
membership = cp.in1d(set1, set2)         # [False, False, True, True, True]
504
intersection = cp.intersect1d(set1, set2)  # [3, 4, 5]
505
difference = cp.setdiff1d(set1, set2)     # [1, 2]
506
union = cp.union1d(set1, set2)            # [1, 2, 3, 4, 5, 6, 7]
507
```