Adding documentation for bcast.py

pavanky · pavanky · commit e66f2997e6c1 · 2015-09-01T19:26:26.000-04:00
- Renamed broadcast.py to bcast.py
- Renamed variable bcast to bacst_var
diff --git a/arrayfire/__init__.py b/arrayfire/__init__.py
@@ -50,7 +50,7 @@
 from .features   import *
 from .vision     import *
 from .graphics   import *
-from .broadcast  import *
+from .bcast      import *
 from .index      import *
 
 # do not export default modules as part of arrayfire
@@ -60,6 +60,6 @@
 del os
 
 #do not export internal functions
-del bcast
+del bcast_var
 del is_number
 del safe_call
diff --git a/arrayfire/arith.py b/arrayfire/arith.py
@@ -13,7 +13,7 @@
 
 from .library import *
 from .array import *
-from .broadcast import *
+from .bcast import *
 
 def _arith_binary_func(lhs, rhs, c_func):
     out = Array()
@@ -25,21 +25,21 @@ def _arith_binary_func(lhs, rhs, c_func):
         raise TypeError("Atleast one input needs to be of type arrayfire.array")
 
     elif (is_left_array and is_right_array):
-        safe_call(c_func(ct.pointer(out.arr), lhs.arr, rhs.arr, bcast.get()))
+        safe_call(c_func(ct.pointer(out.arr), lhs.arr, rhs.arr, bcast_var.get()))
 
     elif (is_number(rhs)):
         ldims = dim4_to_tuple(lhs.dims())
         rty = implicit_dtype(rhs, lhs.type())
         other = Array()
         other.arr = constant_array(rhs, ldims[0], ldims[1], ldims[2], ldims[3], rty)
-        safe_call(c_func(ct.pointer(out.arr), lhs.arr, other.arr, bcast.get()))
+        safe_call(c_func(ct.pointer(out.arr), lhs.arr, other.arr, bcast_var.get()))
 
     else:
         rdims = dim4_to_tuple(rhs.dims())
         lty = implicit_dtype(lhs, rhs.type())
         other = Array()
         other.arr = constant_array(lhs, rdims[0], rdims[1], rdims[2], rdims[3], lty)
-        safe_call(c_func(ct.pointer(out.arr), other.arr, rhs.arr, bcast.get()))
+        safe_call(c_func(ct.pointer(out.arr), other.arr, rhs.arr, bcast_var.get()))
 
     return out
 
diff --git a/arrayfire/array.py b/arrayfire/array.py
@@ -14,7 +14,7 @@
 import inspect
 from .library import *
 from .util import *
-from .broadcast import *
+from .bcast import *
 from .base import *
 from .index import *
 
@@ -82,7 +82,7 @@ def _binary_func(lhs, rhs, c_func):
     elif not isinstance(rhs, Array):
         raise TypeError("Invalid parameter to binary function")
 
-    safe_call(c_func(ct.pointer(out.arr), lhs.arr, other.arr, bcast.get()))
+    safe_call(c_func(ct.pointer(out.arr), lhs.arr, other.arr, bcast_var.get()))
 
     return out
 
@@ -98,7 +98,7 @@ def _binary_funcr(lhs, rhs, c_func):
     elif not isinstance(lhs, Array):
         raise TypeError("Invalid parameter to binary function")
 
-    c_func(ct.pointer(out.arr), other.arr, rhs.arr, bcast.get())
+    c_func(ct.pointer(out.arr), other.arr, rhs.arr, bcast_var.get())
 
     return out
 
diff --git a/arrayfire/bcast.py b/arrayfire/bcast.py
@@ -0,0 +1,96 @@
+#######################################################
+# Copyright (c) 2015, ArrayFire
+# All rights reserved.
+#
+# This file is distributed under 3-clause BSD license.
+# The complete license agreement can be obtained at:
+# http://arrayfire.com/licenses/BSD-3-Clause
+########################################################
+
+"""
+Function to perform broadcasting operations.
+"""
+
+class _bcast(object):
+    _flag = False
+    def get(self):
+        return _bcast._flag
+
+    def set(self, flag):
+        _bcast._flag = flag
+
+    def toggle(self):
+        _bcast._flag ^= True
+
+bcast_var = _bcast()
+
+def broadcast(func, *args):
+    """
+    Function to perform broadcast operations.
+
+    This function can be used directly or as an annotation in the following manner.
+
+    Example
+    -------
+
+    Using broadcast as an annotation
+
+    >>> import arrayfire as af
+    >>> @af.broadcast
+    ... def add(a, b):
+    ...     return a + b
+    ...
+    >>> a = af.randu(2,3)
+    >>> b = af.randu(2,1) # b is a different size
+    >>> # Trying to add arrays of different sizes raises an exceptions
+    >>> c = add(a, b) # This call does not raise an exception because of the annotation
+    >>> af.display(a)
+    [2 3 1 1]
+        0.4107     0.9518     0.4198
+        0.8224     0.1794     0.0081
+
+    >>> af.display(b)
+    [2 1 1 1]
+        0.7269
+        0.7104
+
+    >>> af.display(c)
+    [2 3 1 1]
+        1.1377     1.6787     1.1467
+        1.5328     0.8898     0.7185
+
+    Using broadcast as function
+
+    >>> import arrayfire as af
+    >>> add = lambda a,b: a + b
+    >>> a = af.randu(2,3)
+    >>> b = af.randu(2,1) # b is a different size
+    >>> # Trying to add arrays of different sizes raises an exceptions
+    >>> c = af.broadcast(add, a, b) # This call does not raise an exception
+    >>> af.display(a)
+    [2 3 1 1]
+        0.4107     0.9518     0.4198
+        0.8224     0.1794     0.0081
+
+    >>> af.display(b)
+    [2 1 1 1]
+        0.7269
+        0.7104
+
+    >>> af.display(c)
+    [2 3 1 1]
+        1.1377     1.6787     1.1467
+        1.5328     0.8898     0.7185
+
+    """
+
+    def wrapper(*func_args):
+        bcast_var.toggle()
+        res = func(*func_args)
+        bcast_var.toggle()
+        return res
+
+    if len(args) == 0:
+        return wrapper
+    else:
+        return wrapper(*args)
diff --git a/arrayfire/broadcast.py b/arrayfire/broadcast.py
diff --git a/arrayfire/index.py b/arrayfire/index.py
@@ -9,7 +9,7 @@
 from .library import *
 from .util import *
 from .base import *
-from .broadcast import *
+from .bcast import *
 import math
 
 class Seq(ct.Structure):
@@ -52,11 +52,11 @@ def __iter__(self):
         return self
 
     def next(self):
-        if bcast.get() is True:
-            bcast.toggle()
+        if bcast_var.get() is True:
+            bcast_var.toggle()
             raise StopIteration
         else:
-            bcast.toggle()
+            bcast_var.toggle()
             return self
 
     def __next__(self):
