Skip to content

Commit 5939388

Browse files
roaffixroaffix
committed
Add docstrings for operators
1 parent 2d91b04 commit 5939388

File tree

1 file changed

+224
-14
lines changed

1 file changed

+224
-14
lines changed

‎arrayfire/array_api/array_object.py‎

Lines changed: 224 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -130,38 +130,124 @@ def __init__(
130130

131131
def __pos__(self) -> Array:
132132
"""
133-
Return +self
133+
Evaluates +self_i for each element of an array instance.
134+
135+
Parameters
136+
----------
137+
self : Array
138+
Array instance. Should have a numeric data type.
139+
140+
Returns
141+
-------
142+
out : Array
143+
An array containing the evaluated result for each element. The returned array must have the same data type
144+
as self.
134145
"""
135146
return self
136147

137148
def __neg__(self) -> Array:
138149
"""
139-
Return -self
150+
Evaluates +self_i for each element of an array instance.
151+
152+
Parameters
153+
----------
154+
self : Array
155+
Array instance. Should have a numeric data type.
156+
157+
Returns
158+
-------
159+
out : Array
160+
An array containing the evaluated result for each element in self. The returned array must have a data type
161+
determined by Type Promotion Rules.
162+
140163
"""
141164
return 0 - self # type: ignore[no-any-return, operator] # FIXME
142165

143166
def __add__(self, other: int | float | Array, /) -> Array:
144167
# TODO discuss either we need to support complex and bool as other input type
145168
"""
146-
Return self + other.
169+
Calculates the sum for each element of an array instance with the respective element of the array other.
170+
171+
Parameters
172+
----------
173+
self : Array
174+
Array instance (augend array). Should have a numeric data type.
175+
other: int | float | Array
176+
Addend array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
177+
178+
Returns
179+
-------
180+
out : Array
181+
An array containing the element-wise sums. The returned array must have a data type determined
182+
by Type Promotion Rules.
147183
"""
148184
return _process_c_function(self, other, backend.get().af_add)
149185

150186
def __sub__(self, other: int | float | Array, /) -> Array:
151187
"""
152-
Return self - other.
188+
Calculates the difference for each element of an array instance with the respective element of the array other.
189+
190+
The result of self_i - other_i must be the same as self_i + (-other_i) and must be governed by the same
191+
floating-point rules as addition (see array.__add__()).
192+
193+
Parameters
194+
----------
195+
self : Array
196+
Array instance (minuend array). Should have a numeric data type.
197+
other: int | float | Array
198+
Subtrahend array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
199+
200+
Returns
201+
-------
202+
out : Array
203+
An array containing the element-wise differences. The returned array must have a data type determined
204+
by Type Promotion Rules.
153205
"""
154206
return _process_c_function(self, other, backend.get().af_sub)
155207

156208
def __mul__(self, other: int | float | Array, /) -> Array:
157209
"""
158-
Return self * other.
210+
Calculates the product for each element of an array instance with the respective element of the array other.
211+
212+
Parameters
213+
----------
214+
self : Array
215+
Array instance. Should have a numeric data type.
216+
other: int | float | Array
217+
Other array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
218+
219+
Returns
220+
-------
221+
out : Array
222+
An array containing the element-wise products. The returned array must have a data type determined
223+
by Type Promotion Rules.
159224
"""
160225
return _process_c_function(self, other, backend.get().af_mul)
161226

162227
def __truediv__(self, other: int | float | Array, /) -> Array:
163228
"""
164-
Return self / other.
229+
Evaluates self_i / other_i for each element of an array instance with the respective element of the
230+
array other.
231+
232+
Parameters
233+
----------
234+
self : Array
235+
Array instance. Should have a numeric data type.
236+
other: int | float | Array
237+
Other array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
238+
239+
Returns
240+
-------
241+
out : Array
242+
An array containing the element-wise results. The returned array should have a floating-point data type
243+
determined by Type Promotion Rules.
244+
245+
Note
246+
----
247+
- If one or both of self and other have integer data types, the result is implementation-dependent, as type
248+
promotion between data type “kinds” (e.g., integer versus floating-point) is unspecified.
249+
Specification-compliant libraries may choose to raise an error or return an array containing the element-wise
250+
results. If an array is returned, the array must have a real-valued floating-point data type.
165251
"""
166252
return _process_c_function(self, other, backend.get().af_div)
167253

@@ -171,13 +257,57 @@ def __floordiv__(self, other: int | float | Array, /) -> Array:
171257

172258
def __mod__(self, other: int | float | Array, /) -> Array:
173259
"""
174-
Return self % other.
260+
Evaluates self_i % other_i for each element of an array instance with the respective element of the
261+
array other.
262+
263+
Parameters
264+
----------
265+
self : Array
266+
Array instance. Should have a real-valued data type.
267+
other: int | float | Array
268+
Other array. Must be compatible with self (see Broadcasting). Should have a real-valued data type.
269+
270+
Returns
271+
-------
272+
out : Array
273+
An array containing the element-wise results. Each element-wise result must have the same sign as the
274+
respective element other_i. The returned array must have a real-valued floating-point data type determined
275+
by Type Promotion Rules.
276+
277+
Note
278+
----
279+
- For input arrays which promote to an integer data type, the result of division by zero is unspecified and
280+
thus implementation-defined.
175281
"""
176282
return _process_c_function(self, other, backend.get().af_mod)
177283

178284
def __pow__(self, other: int | float | Array, /) -> Array:
179285
"""
180-
Return self ** other.
286+
Calculates an implementation-dependent approximation of exponentiation by raising each element (the base) of
287+
an array instance to the power of other_i (the exponent), where other_i is the corresponding element of the
288+
array other.
289+
290+
Parameters
291+
----------
292+
self : Array
293+
Array instance whose elements correspond to the exponentiation base. Should have a numeric data type.
294+
other: int | float | Array
295+
Other array whose elements correspond to the exponentiation exponent. Must be compatible with self
296+
(see Broadcasting). Should have a numeric data type.
297+
298+
Returns
299+
-------
300+
out : Array
301+
An array containing the element-wise results. The returned array must have a data type determined
302+
by Type Promotion Rules.
303+
304+
Note
305+
----
306+
- If both self and other have integer data types, the result of __pow__ when other_i is negative
307+
(i.e., less than zero) is unspecified and thus implementation-dependent.
308+
If self has an integer data type and other has a floating-point data type, behavior is
309+
implementation-dependent, as type promotion between data type “kinds” (e.g., integer versus floating-point)
310+
is unspecified.
181311
"""
182312
return _process_c_function(self, other, backend.get().af_pow)
183313

@@ -191,39 +321,119 @@ def __matmul__(self, other: Array, /) -> Array:
191321

192322
def __invert__(self) -> Array:
193323
"""
194-
Return ~self.
324+
Evaluates ~self_i for each element of an array instance.
325+
326+
Parameters
327+
----------
328+
self : Array
329+
Array instance. Should have an integer or boolean data type.
330+
331+
Returns
332+
-------
333+
out : Array
334+
An array containing the element-wise results. The returned array must have the same data type as self.
195335
"""
196336
out = Array()
197337
safe_call(backend.get().af_bitnot(ctypes.pointer(out.arr), self.arr))
198338
return out
199339

200340
def __and__(self, other: int | bool | Array, /) -> Array:
201341
"""
202-
Return self & other.
342+
Evaluates self_i & other_i for each element of an array instance with the respective element of the
343+
array other.
344+
345+
Parameters
346+
----------
347+
self : Array
348+
Array instance. Should have a numeric data type.
349+
other: int | float | Array
350+
Other array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
351+
352+
Returns
353+
-------
354+
out : Array
355+
An array containing the element-wise results. The returned array must have a data type determined
356+
by Type Promotion Rules.
203357
"""
204358
return _process_c_function(self, other, backend.get().af_bitand)
205359

206360
def __or__(self, other: int | bool | Array, /) -> Array:
207361
"""
208-
Return self | other.
362+
Evaluates self_i | other_i for each element of an array instance with the respective element of the
363+
array other.
364+
365+
Parameters
366+
----------
367+
self : Array
368+
Array instance. Should have a numeric data type.
369+
other: int | float | Array
370+
Other array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
371+
372+
Returns
373+
-------
374+
out : Array
375+
An array containing the element-wise results. The returned array must have a data type determined
376+
by Type Promotion Rules.
209377
"""
210378
return _process_c_function(self, other, backend.get().af_bitor)
211379

212380
def __xor__(self, other: int | bool | Array, /) -> Array:
213381
"""
214-
Return self ^ other.
382+
Evaluates self_i ^ other_i for each element of an array instance with the respective element of the
383+
array other.
384+
385+
Parameters
386+
----------
387+
self : Array
388+
Array instance. Should have a numeric data type.
389+
other: int | float | Array
390+
Other array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
391+
392+
Returns
393+
-------
394+
out : Array
395+
An array containing the element-wise results. The returned array must have a data type determined
396+
by Type Promotion Rules.
215397
"""
216398
return _process_c_function(self, other, backend.get().af_bitxor)
217399

218400
def __lshift__(self, other: int | Array, /) -> Array:
219401
"""
220-
Return self << other.
402+
Evaluates self_i << other_i for each element of an array instance with the respective element of the
403+
array other.
404+
405+
Parameters
406+
----------
407+
self : Array
408+
Array instance. Should have a numeric data type.
409+
other: int | float | Array
410+
Other array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
411+
Each element must be greater than or equal to 0.
412+
413+
Returns
414+
-------
415+
out : Array
416+
An array containing the element-wise results. The returned array must have the same data type as self.
221417
"""
222418
return _process_c_function(self, other, backend.get().af_bitshiftl)
223419

224420
def __rshift__(self, other: int | Array, /) -> Array:
225421
"""
226-
Return self >> other.
422+
Evaluates self_i >> other_i for each element of an array instance with the respective element of the
423+
array other.
424+
425+
Parameters
426+
----------
427+
self : Array
428+
Array instance. Should have a numeric data type.
429+
other: int | float | Array
430+
Other array. Must be compatible with self (see Broadcasting). Should have a numeric data type.
431+
Each element must be greater than or equal to 0.
432+
433+
Returns
434+
-------
435+
out : Array
436+
An array containing the element-wise results. The returned array must have the same data type as self.
227437
"""
228438
return _process_c_function(self, other, backend.get().af_bitshiftr)
229439

0 commit comments

Comments
 (0)