ENH: Add kwarg support for vectorize (tickets #2100, #1156, and #1487)

  This is a substantial rewrite of vectorize to remove all introspection and
  caching behaviour.  This greatly simplifies the logic of the code, and allows
  for much more generalized behaviour, simultaneously fixing tickets #1156,
  #1487, and #2100.  There will probably be a performance hit because caching is
  no longer used (but should be able to be reinstated if needed).
  As vectorize is a convenience function with poor performance in general,
  perhaps this is okay.  Rather than trying to inspect the function to determine
  the number of arguments, defaults, and argument names, we just use the
  arguments passed on the call to determine the behaviour on each call.

  All tests pass and code is fully covered

Fixes:
Ticket #2100: kwarg support for vectorize
- API: Optional excluded argument to exclude some args from vectorization.
- Added documentation, examples, and coverage tests
- Added additional coverage test and base case for functions with no args
- Factored original behaviour into _vectorize_call
- Some minor documentation and error message corrections

Ticket #1156: Support vectorizing over instance methods
- No longer an issue since everything is determined by the call.

Ticket: #1487: result depends on execution order
- No longer caching, so the behaviour is as was expected.

ENH: Simple cache for vectorize

- Added simple cache to prevent vectorize from calling pyfunc twice on the first
  argument when determining the output types and added regression test.
- Added documentation for excluded positional arguments.
- Documentation cleanups.
- Cleaned up variable names.

ENH: Performance improvements for backward compatibility of vectorize.

After some simple profiling, I found that the wrapping used to
support the caching of the previous commit wasted more time than
it saved, so I added a flag to allow the user to toggle.  Moral:
caching makes sense only if the function is expensive and is off
by default.

I also compared performance with the original vectorize and opted
for keeping a cache of _ufunc if otypes is specified and there are
no kwargs/excluded vars.  This case is easy to implement, and allows
users to reproduce (almost) the old performance characteristics if
needed. (The new version is about 5% slower in this case).

It would be much more complicated to add a similar cache in the case
where kwargs are used, and since a wrapper is used here, the
performance gain would be negligible (profiling showed that wrapping
was a more significant slowdown than the extra call to frompyfunc).

- API: Added cache kwarg which allows the user to toggle caching
       of the first result.
- DOC: Added Notes section with a discussion of performance and a
       warning that vectorize should not be used for performance.
- Added private _ufunc member to implement old-style of cache for
  special case with no kwargs, excluded, and with otypes specified.
- Modified test case.

Partially address ticket #1982
- I tried to use hasattr(outputs, '__len__') rather than
  isinstance(outputs, tuple) in order to allow for functions to return
  lists.  This, however, means that strings will get vectorized over
  each character which breaks previous behaviour.  Keeping old
  behaviour for now.

1 files changed, 128 insertions, 27 deletions

diff --git a/numpy/lib/tests/test_function_base.py b/numpy/lib/tests/test_function_base.py
index 7245b8962..95b32e47c 100644
--- a/numpy/lib/tests/test_function_base.py
+++ b/numpy/lib/tests/test_function_base.py
@@ -274,7 +274,7 @@ class TestGradient(TestCase):
         assert_array_equal(gradient(v), dx)
 
     def test_badargs(self):
-        # for 2D array, gradient can take 0,1, or 2 extra args
+        # for 2D array, gradient can take 0, 1, or 2 extra args
         x = np.array([[1, 1], [3, 4]])
         assert_raises(SyntaxError, gradient, x, np.array([1., 1.]),
                       np.array([1., 1.]), np.array([1., 1.]))
@@ -394,12 +394,12 @@ class TestVectorize(TestCase):
         def foo(a, b=1):
             return a + b
         f = vectorize(foo)
-        args = np.array([1,2,3])
+        args = np.array([1, 2, 3])
         r1 = f(args)
-        r2 = np.array([2,3,4])
+        r2 = np.array([2, 3, 4])
         assert_array_equal(r1, r2)
         r1 = f(args, 2)
-        r2 = np.array([3,4,5])
+        r2 = np.array([3, 4, 5])
         assert_array_equal(r1, r2)
 
     def test_keywords_no_func_code(self):
@@ -412,6 +412,107 @@ class TestVectorize(TestCase):
         except:
             raise AssertionError()
 
+    def test_keywords2_ticket_2100(self):
+        r"""Test kwarg support: enhancement ticket 2100"""
+        import math
+        def foo(a, b=1):
+            return a + b
+        f = vectorize(foo)
+        args = np.array([1, 2, 3])
+        r1 = f(a=args)
+        r2 = np.array([2, 3, 4])
+        assert_array_equal(r1, r2)
+        r1 = f(b=1, a=args)
+        assert_array_equal(r1, r2)
+        r1 = f(args, b=2)
+        r2 = np.array([3, 4, 5])
+        assert_array_equal(r1, r2)
+
+    def test_keywords3_ticket_2100(self):
+        """Test excluded with mixed positional and kwargs: ticket 2100"""
+        def mypolyval(x, p):
+            _p = list(p)
+            res = _p.pop(0)
+            while _p:
+                res = res*x + _p.pop(0)
+            return res
+        vpolyval = np.vectorize(mypolyval, excluded=['p',1])
+        ans = [3, 6]
+        assert_array_equal(ans, vpolyval(x=[0, 1], p=[1, 2, 3]))
+        assert_array_equal(ans, vpolyval([0, 1], p=[1, 2, 3]))
+        assert_array_equal(ans, vpolyval([0, 1], [1, 2, 3]))
+
+    def test_keywords4_ticket_2100(self):
+        """Test vectorizing function with no positional args."""
+        @vectorize
+        def f(**kw):
+            res = 1.0
+            for _k in kw:
+                res *= kw[_k]
+            return res
+        assert_array_equal(f(a=[1, 2], b=[3, 4]), [3, 8])
+
+    def test_keywords5_ticket_2100(self):
+        """Test vectorizing function with no kwargs args."""
+        @vectorize
+        def f(*v):
+            return np.prod(v)
+        assert_array_equal(f([1, 2], [3, 4]), [3, 8])
+
+    def test_coverage1_ticket_2100(self):
+        def foo():
+            return 1
+        f = vectorize(foo)
+        assert_array_equal(f(), 1)
+
+    def test_assigning_docstring(self):
+        def foo(x):
+            return x
+        doc = "Provided documentation"
+        f = vectorize(foo, doc=doc)
+        assert_equal(f.__doc__, doc)
+
+    def test_UnboundMethod_ticket_1156(self):
+        """Regression test for issue 1156"""
+        class Foo:
+            b = 2
+            def bar(self, a):
+                return a**self.b
+        assert_array_equal(vectorize(Foo().bar)(np.arange(9)),
+                           np.arange(9)**2)
+        assert_array_equal(vectorize(Foo.bar)(Foo(), np.arange(9)),
+                           np.arange(9)**2)
+
+    def test_execution_order_ticket_1487(self):
+        """Regression test for dependence on execution order: issue 1487"""
+        f1 = vectorize(lambda x: x)
+        res1a = f1(np.arange(3))
+        res1b = f1(np.arange(0.1, 3))
+        f2 = vectorize(lambda x: x)
+        res2b = f2(np.arange(0.1, 3))
+        res2a = f2(np.arange(3))
+        assert_equal(res1a, res2a)
+        assert_equal(res1b, res2b)
+        
+    def test_string_ticket_1892(self):
+        """Test vectorization over strings: issue 1892."""
+        f = np.vectorize(lambda x:x)
+        s = '0123456789'*10
+        assert_equal(s, f(s))
+        #z = f(np.array([s,s]))
+        #assert_array_equal([s,s], f(s))
+
+    def test_cache(self):
+        """Ensure that vectorized func called exactly once per argument."""
+        _calls = [0]
+        @vectorize
+        def f(x):
+            _calls[0] += 1
+            return x**2
+        f.cache = True
+        x = np.arange(5)
+        assert_array_equal(f(x), x*x)
+        assert_equal(_calls[0], len(x))
 
 class TestDigitize(TestCase):
     def test_forward(self):
@@ -430,17 +531,17 @@ class TestDigitize(TestCase):
         assert_(np.all(digitize(x, bin) != 0))
 
     def test_right_basic(self):
-        x = [1,5,4,10,8,11,0]
-        bins = [1,5,10]
-        default_answer = [1,2,1,3,2,3,0]
+        x = [1, 5, 4, 10, 8, 11, 0]
+        bins = [1, 5, 10]
+        default_answer = [1, 2, 1, 3, 2, 3, 0]
         assert_array_equal(digitize(x, bins), default_answer)
-        right_answer = [0,1,1,2,2,3,0]
+        right_answer = [0, 1, 1, 2, 2, 3, 0]
         assert_array_equal(digitize(x, bins, True), right_answer)
 
     def test_right_open(self):
         x = np.arange(-6, 5)
         bins = np.arange(-6, 4)
-        assert_array_equal(digitize(x,bins,True), np.arange(11))
+        assert_array_equal(digitize(x, bins, True), np.arange(11))
 
     def test_right_open_reverse(self):
         x = np.arange(5, -6, -1)
@@ -598,10 +699,10 @@ class TestHistogram(TestCase):
     def test_one_bin(self):
         # Ticket 632
         hist, edges = histogram([1, 2, 3, 4], [1, 2])
-        assert_array_equal(hist, [2, ])
+        assert_array_equal(hist, [2,])
         assert_array_equal(edges, [1, 2])
         assert_raises(ValueError, histogram, [1, 2], bins=0)
-        h, e = histogram([1,2], bins=1)
+        h, e = histogram([1, 2], bins=1)
         assert_equal(h, np.array([2]))
         assert_allclose(e, np.array([1., 2.]))
 
@@ -630,7 +731,7 @@ class TestHistogram(TestCase):
 
         # Check with non-constant bin widths
         v = np.arange(10)
-        bins = [0,1,3,6,10]
+        bins = [0, 1, 3, 6, 10]
         a, b = histogram(v, bins, density=True)
         assert_array_equal(a, .1)
         assert_equal(np.sum(a*diff(b)), 1)
@@ -638,13 +739,13 @@ class TestHistogram(TestCase):
         # Variale bin widths are especially useful to deal with
         # infinities.
         v = np.arange(10)
-        bins = [0,1,3,6,np.inf]
+        bins = [0, 1, 3, 6, np.inf]
         a, b = histogram(v, bins, density=True)
-        assert_array_equal(a, [.1,.1,.1,0.])
+        assert_array_equal(a, [.1, .1, .1, 0.])
 
         # Taken from a bug report from N. Becker on the numpy-discussion
         # mailing list Aug. 6, 2010.
-        counts, dmy = np.histogram([1,2,3,4], [0.5,1.5,np.inf], density=True)
+        counts, dmy = np.histogram([1, 2, 3, 4], [0.5, 1.5, np.inf], density=True)
         assert_equal(counts, [.25, 0])
 
     def test_outliers(self):
@@ -709,12 +810,12 @@ class TestHistogram(TestCase):
         assert_array_almost_equal(wa, np.array([4, 5, 0, 1]) / 10. / 3. * 4)
 
         # Check weights with non-uniform bin widths
-        a,b = histogram(np.arange(9), [0,1,3,6,10], \
-                        weights=[2,1,1,1,1,1,1,1,1], density=True)
+        a, b = histogram(np.arange(9), [0, 1, 3, 6, 10], \
+                        weights=[2, 1, 1, 1, 1, 1, 1, 1, 1], density=True)
         assert_almost_equal(a, [.2, .1, .1, .075])
 
     def test_empty(self):
-        a, b = histogram([], bins=([0,1]))
+        a, b = histogram([], bins=([0, 1]))
         assert_array_equal(a, np.array([0]))
         assert_array_equal(b, np.array([0, 1]))
 
@@ -792,7 +893,7 @@ class TestHistogramdd(TestCase):
         assert_array_equal(edges[0], np.array([-0.5, 0. , 0.5]))
 
     def test_empty(self):
-        a, b = histogramdd([[], []], bins=([0,1], [0,1]))
+        a, b = histogramdd([[], []], bins=([0, 1], [0, 1]))
         assert_array_max_ulp(a, np.array([[ 0.]]))
         a, b = np.histogramdd([[], [], []], bins=2)
         assert_array_max_ulp(a, np.zeros((2, 2, 2)))
@@ -1011,7 +1112,7 @@ class TestCorrCoef(TestCase):
 class TestCov(TestCase):
     def test_basic(self):
         x = np.array([[0, 2], [1, 1], [2, 0]]).T
-        assert_allclose(np.cov(x), np.array([[ 1.,-1.], [-1.,1.]]))
+        assert_allclose(np.cov(x), np.array([[ 1., -1.], [-1., 1.]]))
 
     def test_empty(self):
         assert_equal(cov(np.array([])).size, 0)
@@ -1162,7 +1263,7 @@ class TestBincount(TestCase):
     def test_empty(self):
         x = np.array([], dtype=int)
         y = np.bincount(x)
-        assert_array_equal(x,y)
+        assert_array_equal(x, y)
 
     def test_empty_with_minlength(self):
         x = np.array([], dtype=int)
@@ -1182,10 +1283,10 @@ class TestInterp(TestCase):
         assert_almost_equal(np.interp(x0, x, y), x0)
 
     def test_right_left_behavior(self):
-        assert_equal(interp([-1, 0, 1], [0], [1]), [1,1,1])
-        assert_equal(interp([-1, 0, 1], [0], [1], left=0), [0,1,1])
-        assert_equal(interp([-1, 0, 1], [0], [1], right=0), [1,1,0])
-        assert_equal(interp([-1, 0, 1], [0], [1], left=0, right=0), [0,1,0])
+        assert_equal(interp([-1, 0, 1], [0], [1]), [1, 1, 1])
+        assert_equal(interp([-1, 0, 1], [0], [1], left=0), [0, 1, 1])
+        assert_equal(interp([-1, 0, 1], [0], [1], right=0), [1, 1, 0])
+        assert_equal(interp([-1, 0, 1], [0], [1], left=0, right=0), [0, 1, 0])
 
     def test_scalar_interpolation_point(self):
         x = np.linspace(0, 1, 5)
@@ -1255,10 +1356,10 @@ class TestAdd_newdoc_ufunc(TestCase):
 
     def test_ufunc_arg(self):
         assert_raises(TypeError, add_newdoc_ufunc, 2, "blah")
-        assert_raises(ValueError, add_newdoc_ufunc,np.add, "blah")
+        assert_raises(ValueError, add_newdoc_ufunc, np.add, "blah")
 
     def test_string_arg(self):
-        assert_raises(TypeError, add_newdoc_ufunc,np.add, 3)
+        assert_raises(TypeError, add_newdoc_ufunc, np.add, 3)