Ticket #3813: 3813-diff.patch

sage/plot/plot.py

@@ -3419 +3419 @@
         adaptive_recursion -- (default: 5) how many levels of recursion to go 
                               before giving up when doing adaptive refinement.
                               Setting this to 0 disables adaptive refinement.
-        adaptive_tolerance -- how large a difference should be before the
-                              adaptive refinement code considers it significant.
-                              This depends on the interval you use by default.
+        adaptive_tolerance -- (default: 0.01) how large a difference should be
+                              before the adaptive refinement code considers it
+                              significant.  Use a smaller value for smoother
+                              plots and a larger value for coarser plots.  In
+                              general, adjust adaptive_recursion before
+                              adaptive_tolerance, and consult the code of
+                              adaptive_refinement for the details.
+
         xmin -- starting x value
         xmax -- ending x value
         color -- an rgb-tuple (r,g,b) with each of r,g,b between 0 and 1, or
@@ -3559 +3564 @@
     def _reset(self):
         o = self.options
         o['plot_points'] = 200
+        o['adaptive_tolerance'] = 0.01
         o['adaptive_recursion'] = 5
         o['rgbcolor'] = (0,0,1)   
 
@@ -3695 +3701 @@
             warnings.warn("plot_division is deprecated. See adaptive_recursion in the documentation for plot()", DeprecationWarning, stacklevel=3)
         # adaptive refinement
         i, j = 0, 0
-        if 'adaptive_tolerance' in options:
-            adaptive_tolerance = float(options['adaptive_tolerance'])
-            del options['adaptive_tolerance']
-        else:
-            adaptive_tolerance = delta * 0.01
+        adaptive_tolerance = delta * float(options['adaptive_tolerance'])
+        del options['adaptive_tolerance']
         adaptive_recursion = int(options['adaptive_recursion'])
         del options['adaptive_recursion']
         
         while i < len(data) - 1:
             for p in adaptive_refinement(f, data[i], data[i+1], 
-                            adaptive_tolerance, adaptive_recursion):
+                                         adaptive_tolerance=adaptive_tolerance,
+                                         adaptive_recursion=adaptive_recursion):
                 data.insert(i+1, p)
                 i += 1
             i += 1
@@ -4498 +4502 @@
         adaptive_recursion -- (default: 10) how many levels of recursion to go 
                               before giving up when doing adaptive refinement.
                               Setting this to 0 disables adaptive refinement.
-        adaptive_tolerance -- (default 0.01) how large a difference should be 
+        adaptive_tolerance -- (default: 0.01) how large a difference should be
                               before the adaptive refinement code considers 
-                              it significant.
+                              it significant.  See the documentation for
+                              plot() for more information.
     
     OUTPUT:
         list -- a list of points to insert between p1 and p2 to get
@@ -4508 +4513 @@
 
     TESTS:
         sage: from sage.plot.plot import adaptive_refinement
-        sage: adaptive_refinement(sin, (0,0), (pi,0), 0.01, level=10)
+        sage: adaptive_refinement(sin, (0,0), (pi,0), adaptive_tolerance=0.01, level=10)
         []
-        sage: adaptive_refinement(sin, (0,0), (pi,0), 0.01)
-        [(0.125000000000000*pi, 0.38268343236508978), (0.187500000000000*pi, 0.55557023301960218), (0.250000000000000*pi, 0.70710678118654757), (0.312500000000000*pi, 0.83146961230254524), (0.375000000000000*pi, 0.92387953251128674), (0.437500000000000*pi, 0.98078528040323043), (0.500000000000000*pi, 1.0), (0.562500000000000*pi, 0.98078528040323043), (0.625000000000000*pi, 0.92387953251128674), (0.687500000000000*pi, 0.83146961230254546), (0.750000000000000*pi, 0.70710678118654757), (0.812500000000000*pi, 0.55557023301960218), (0.875000000000000*pi, 0.38268343236508989)]
+        sage: adaptive_refinement(sin, (0,0), (pi,0), adaptive_tolerance=0.01)
+        [(0.125000000000000*pi, 0.38268343236508978), (0.187500000000000*pi, 0.55557023301960218), (0.250000000000000*pi, 0.707106781186547...), (0.312500000000000*pi, 0.83146961230254524), (0.375000000000000*pi, 0.92387953251128674), (0.437500000000000*pi, 0.98078528040323043), (0.500000000000000*pi, 1.0), (0.562500000000000*pi, 0.98078528040323043), (0.625000000000000*pi, 0.92387953251128674), (0.687500000000000*pi, 0.83146961230254546), (0.750000000000000*pi, 0.70710678118654757), (0.812500000000000*pi, 0.55557023301960218), (0.875000000000000*pi, 0.38268343236508989)]
+
+        This shows that lowering adaptive_tolerance and raising
+        adaptive_recursion both increase the number of subdivision points:
+
+        sage: x = var('x')
+        sage: f = sin(1/x)
+        sage: n1 = len(adaptive_refinement(f, (0,0), (pi,0), adaptive_tolerance=0.01)); n1
+        79
+        sage: n2 = len(adaptive_refinement(f, (0,0), (pi,0), adaptive_recursion=5, adaptive_tolerance=0.01)); n2
+        15
+        sage: n1 > n2
+        True
+
+        sage: n3 = len(adaptive_refinement(f, (0,0), (pi,0), adaptive_tolerance=0.005)); n3
+        88
+        sage: n1 < n3
+        True
     """
     if level >= adaptive_recursion:
         return []