0
# Binary Operations
1

2
Bitwise operations for integer and boolean arrays including AND, OR, XOR, NOT operations and bit shifting. These functions are essential for low-level data manipulation, boolean logic, and efficient computation with integer data types on GPU.
3

4
## Capabilities
5

6
### Bitwise Logical Operations
7

8
Element-wise bitwise logical operations on integer arrays.
9

10
```python { .api }
11
def bitwise_and(x1, x2, out=None, **kwargs):
12
    """
13
    Compute the bit-wise AND of two arrays element-wise.
14
    
15
    Parameters:
16
    - x1, x2: array_like, input arrays (integers or booleans)
17
    - out: cupy.ndarray, optional output array
18
    - **kwargs: additional keyword arguments
19
    
20
    Returns:
21
    cupy.ndarray: result of bitwise AND operation
22
    """
23

24
def bitwise_or(x1, x2, out=None, **kwargs):
25
    """
26
    Compute the bit-wise OR of two arrays element-wise.
27
    
28
    Parameters:
29
    - x1, x2: array_like, input arrays (integers or booleans)
30
    - out: cupy.ndarray, optional output array
31
    - **kwargs: additional keyword arguments
32
    
33
    Returns:
34
    cupy.ndarray: result of bitwise OR operation
35
    """
36

37
def bitwise_xor(x1, x2, out=None, **kwargs):
38
    """
39
    Compute the bit-wise XOR of two arrays element-wise.
40
    
41
    Parameters:
42
    - x1, x2: array_like, input arrays (integers or booleans)
43
    - out: cupy.ndarray, optional output array
44
    - **kwargs: additional keyword arguments
45
    
46
    Returns:
47
    cupy.ndarray: result of bitwise XOR operation
48
    """
49

50
def bitwise_not(x, out=None, **kwargs):
51
    """
52
    Compute bit-wise inversion, or bit-wise NOT, element-wise.
53
    
54
    Parameters:
55
    - x: array_like, input array (integers or booleans)
56
    - out: cupy.ndarray, optional output array
57
    - **kwargs: additional keyword arguments
58
    
59
    Returns:
60
    cupy.ndarray: result of bitwise NOT operation
61
    """
62

63
def invert(x, out=None, **kwargs):
64
    """
65
    Compute bit-wise inversion, or bit-wise NOT, element-wise.
66
    
67
    Alias for bitwise_not.
68
    
69
    Parameters:
70
    - x: array_like, input array (integers or booleans) 
71
    - out: cupy.ndarray, optional output array
72
    - **kwargs: additional keyword arguments
73
    
74
    Returns:
75
    cupy.ndarray: result of bitwise NOT operation
76
    """
77
```
78

79
### Bit Shifting Operations
80

81
Functions for shifting bits left or right in integer arrays.
82

83
```python { .api }
84
def left_shift(x1, x2, out=None, **kwargs):
85
    """
86
    Shift the bits of an integer to the left.
87
    
88
    Parameters:
89
    - x1: array_like of int, input array of integers
90
    - x2: array_like of int, number of bits to shift left
91
    - out: cupy.ndarray, optional output array
92
    - **kwargs: additional keyword arguments
93
    
94
    Returns:
95
    cupy.ndarray: result of left shift operation
96
    """
97

98
def right_shift(x1, x2, out=None, **kwargs):
99
    """
100
    Shift the bits of an integer to the right.
101
    
102
    Parameters:
103
    - x1: array_like of int, input array of integers
104
    - x2: array_like of int, number of bits to shift right  
105
    - out: cupy.ndarray, optional output array
106
    - **kwargs: additional keyword arguments
107
    
108
    Returns:
109
    cupy.ndarray: result of right shift operation
110
    """
111
```
112

113
### Bit Packing and Unpacking
114

115
Functions for packing and unpacking binary representations.
116

117
```python { .api }
118
def packbits(a, axis=None, bitorder='big'):
119
    """
120
    Pack the elements of a binary-valued array into bits in a uint8 array.
121
    
122
    Parameters:
123
    - a: array_like, input array with values of 0 or 1
124
    - axis: int, dimension over which bit-packing is done
125
    - bitorder: str, bit order within bytes ('big' or 'little')
126
    
127
    Returns:
128
    cupy.ndarray: packed uint8 array
129
    """
130

131
def unpackbits(a, axis=None, count=None, bitorder='big'):
132
    """
133
    Unpacks elements of a uint8 array into a binary-valued output array.
134
    
135
    Parameters:
136
    - a: cupy.ndarray of uint8, input array to unpack
137
    - axis: int, dimension over which bit-unpacking is done
138
    - count: int, number of elements to unpack along axis
139
    - bitorder: str, bit order within bytes ('big' or 'little')
140
    
141
    Returns:
142
    cupy.ndarray: unpacked binary array
143
    """
144
```
145

146
### Binary Utility Functions
147

148
Utility functions for binary representation and manipulation.
149

150
```python { .api }
151
def binary_repr(num, width=None):
152
    """
153
    Return the binary representation of the input number as a string.
154
    
155
    Parameters:
156
    - num: int, input integer
157
    - width: int, minimum number of digits in output
158
    
159
    Returns:
160
    str: binary representation string
161
    """
162
```
163

164
## Usage Examples
165

166
### Basic Bitwise Operations
167

168
```python
169
import cupy as cp
170

171
# Create integer arrays
172
a = cp.array([1, 2, 3, 4, 5], dtype=cp.int32)
173
b = cp.array([5, 4, 3, 2, 1], dtype=cp.int32)
174

175
# Bitwise AND
176
result_and = cp.bitwise_and(a, b)
177
print(result_and)  # [1 0 3 0 1]
178

179
# Bitwise OR  
180
result_or = cp.bitwise_or(a, b)
181
print(result_or)  # [5 6 3 6 5]
182

183
# Bitwise XOR
184
result_xor = cp.bitwise_xor(a, b)
185
print(result_xor)  # [4 6 0 6 4]
186

187
# Bitwise NOT
188
result_not = cp.bitwise_not(a)
189
print(result_not)  # [-2 -3 -4 -5 -6]
190
```
191

192
### Bit Shifting Operations
193

194
```python
195
import cupy as cp
196

197
# Create array of integers
198
values = cp.array([1, 2, 4, 8, 16], dtype=cp.int32)
199

200
# Left shift by 2 bits (multiply by 4)
201
left_shifted = cp.left_shift(values, 2)
202
print(left_shifted)  # [4 8 16 32 64]
203

204
# Right shift by 1 bit (divide by 2)
205
right_shifted = cp.right_shift(values, 1)
206
print(right_shifted)  # [0 1 2 4 8]
207
```
208

209
### Bit Packing Example
210

211
```python
212
import cupy as cp
213

214
# Create binary array
215
binary_data = cp.array([[1, 0, 1, 1, 0, 0, 1, 0],
216
                        [0, 1, 1, 0, 1, 0, 1, 1]], dtype=cp.uint8)
217

218
# Pack bits into bytes
219
packed = cp.packbits(binary_data, axis=1)
220
print(packed)  # [[178] [107]]
221

222
# Unpack back to binary
223
unpacked = cp.unpackbits(packed, axis=1)
224
print(unpacked)  # [[1 0 1 1 0 0 1 0] [0 1 1 0 1 0 1 1]]
225
```
226

227
### Boolean Array Operations
228

229
```python
230
import cupy as cp
231

232
# Boolean arrays
233
bool_a = cp.array([True, False, True, False])
234
bool_b = cp.array([True, True, False, False])
235

236
# Bitwise operations work on boolean arrays too
237
and_result = cp.bitwise_and(bool_a, bool_b)
238
print(and_result)  # [True False False False]
239

240
or_result = cp.bitwise_or(bool_a, bool_b)  
241
print(or_result)  # [True True True False]
242

243
xor_result = cp.bitwise_xor(bool_a, bool_b)
244
print(xor_result)  # [False True True False]
245
```