plot(*args, **kwds)
Use plot by writing
 
``plot(X, ...)``
 
where `X` is a Sage object (or list of Sage objects) that
either is callable and returns numbers that can be coerced to
floats, or has a plot method that returns a
``GraphicPrimitive`` object.
 
There are many other specialized 2D plot commands available
in Sage, such as ``plot_slope_field``, as well as various 
graphics primitives like Arrow; type ``sage.plot.plot?`` for 
a current list.
 
Type ``plot.options`` for a dictionary of the default
options for plots. You can change this to change the defaults for
all future plots. Use ``plot.reset()`` to reset to the
default options.
 
PLOT OPTIONS: 
 
- ``plot_points`` - (default: 200) the minimal number of plot points.
 
- ``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`` - (default: 0.01) how large a difference should be
  before the adaptive refinement code considers it significant.  See the
  documentation further below for more information, starting at "the 
  algorithm used to insert".
 
- ``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 a color name as a string (e.g., 'purple'), or an HTML color 
  such as '#aaff0b'.
 
- ``detect_poles`` - (Default: False) If set to True poles are detected.
  If set to "show" vertical asymptotes are drawn.
 
APPEARANCE OPTIONS: 
 
The following options affect the appearance of
the line through the points on the graph of `X` (these are
the same as for the line function):
 
INPUT:
 
- ``alpha`` - How transparent the line is
 
- ``thickness`` - How thick the line is
    
- ``rgbcolor`` - The color as an RGB tuple
    
- ``hue`` - The color given as a hue
 
Any MATPLOTLIB line option may also be passed in.  E.g.,
 
- ``linestyle`` - The style of the line, which is one of
  '--' (dashed), '-.' (dash dot), '-' (solid),
  'steps', ':' (dotted)
    
- ``marker``  - "'0' (tickleft), '1' (tickright), '2' (tickup), '3' (tickdown),
  '' (nothing), ' ' (nothing), '+' (plus), ',' (pixel), '.' (point),
  '1' (tri_down), '3' (tri_left), '2' (tri_up), '4' (tri_right),
  '<' (triangle_left), '>' (triangle_right), 'None' (nothing),
  'D' (diamond), 'H' (hexagon2), '_' (hline), '\^' (triangle_up),
  'd' (thin_diamond), 'h' (hexagon1), 'o' (circle), 'p' (pentagon),
  's' (square), 'v' (triangle_down), 'x' (x), '|' (vline)"
   
- ``markersize`` - the size of the marker in points
 
- ``markeredgecolor`` - the markerfacecolor can be any color arg
 
- ``markeredgewidth`` - the size of the marker edge in points
 
- ``exclude`` - (Default: None) values which are excluded from the plot range.
  Either a list of real numbers, or an equation in one variable.
 
FILLING OPTIONS:
INPUT:
    
 
- ``fill`` - (Default: None) One of:
            
  - "axis" or True: Fill the area between the function and the x-axis.
            
  - "min": Fill the area between the function and its minimal value.
  
  - "max": Fill the area between the function and its maximal value.
  
  - a number c: Fill the area between the function and the horizontal line y = c.
  
  - a function g: Fill the area between the function that is plotted and g.
  
  - a dictionary d (only if a list of functions are plotted):
    The keys of the dictionary should be integers.
    The value of d[i] specifies the fill options for the i-th function in the list.
    If d[i] == [j]: Fill the area between the i-th and the j-th function in the list.
    (But if d[i] == j: Fill the area between the i-th function in the list and the
    horizontal line y = j.)
 
- ``fillcolor`` - (default: 'automatic') The color of the fill.
  Either 'automatic' or a color.
    
- ``fillalpha`` - (default: 0.5) How transparent the fill is.
  A number between 0 and 1.
 
Note that this function does NOT simply sample equally spaced
points between xmin and xmax. Instead it computes equally spaced
points and add small perturbations to them. This reduces the
possibility of, e.g., sampling sin only at multiples of
`2\pi`, which would yield a very misleading graph.
 
EXAMPLES: We plot the sin function::
 
    sage: P = plot(sin, (0,10)); print P
    Graphics object consisting of 1 graphics primitive
    sage: len(P)     # number of graphics primitives
    1
    sage: len(P[0])  # how many points were computed (random)
    225
    sage: P          # render
 
::
 
    sage: P = plot(sin, (0,10), plot_points=10); print P
    Graphics object consisting of 1 graphics primitive
    sage: len(P[0])  # random output
    32
    sage: P          # render
 
We plot with ``randomize=False``, which makes the initial sample points
evenly spaced (hence always the same). Adaptive plotting might
insert other points, however, unless ``adaptive_recursion=0``.
 
::
 
    sage: p=plot(1, (x,0,3), plot_points=4, randomize=False, adaptive_recursion=0)
    sage: list(p[0])
    [(0.0, 1.0), (1.0, 1.0), (2.0, 1.0), (3.0, 1.0)]
 
Some colored functions::
 
    sage: plot(sin, 0, 10, color='purple')
    sage: plot(sin, 0, 10, color='#ff00ff')
 
We plot several functions together by passing a list of functions
as input::
 
    sage: plot([sin(n*x) for n in [1..4]], (0, pi))
 
The function `\sin(1/x)` wiggles wildly near `0`.
Sage adapts to this and plots extra points near the origin.
 
::
 
    sage: plot(sin(1/x), (x, -1, 1))
 
Via the matplotlib library, Sage makes it easy to tell whether
a graph is on both sides of both axes, as the axes only cross
if the origin is actually part of the viewing area::
 
    sage: plot(x^3,(x,0,2))  # this one has the origin
    sage: plot(x^3,(x,1,2))  # this one does not
 
Another thing to be aware of with axis labeling is that when
the labels have quite different orders of magnitude or are very
large, scientific notation (the `e` notation for powers of ten) is used::
 
    sage: plot(x^2,(x,480,500))  # this one has no scientific notation
    sage: plot(x^2,(x,300,500))  # this one has scientific notation on y-axis
 
Note that the independent variable may be omitted if there is no
ambiguity::
 
    sage: plot(sin(1/x), (-1, 1))
 
The algorithm used to insert extra points is actually pretty
simple. On the picture drawn by the lines below::
 
    sage: p = plot(x^2, (-0.5, 1.4)) + line([(0,0), (1,1)], color='green')
    sage: p += line([(0.5, 0.5), (0.5, 0.5^2)], color='purple')
    sage: p += point(((0, 0), (0.5, 0.5), (0.5, 0.5^2), (1, 1)), color='red', pointsize=20)
    sage: p += text('A', (-0.05, 0.1), color='red')
    sage: p += text('B', (1.01, 1.1), color='red')
    sage: p += text('C', (0.48, 0.57), color='red')
    sage: p += text('D', (0.53, 0.18), color='red')
    sage: p.show(axes=False, xmin=-0.5, xmax=1.4, ymin=0, ymax=2)
 
You have the function (in blue) and its approximation (in green)
passing through the points A and B. The algorithm finds the
midpoint C of AB and computes the distance between C and D. If that
distance exceeds the ``adaptive_tolerance`` threshold (*relative* to
the size of the initial plot subintervals), the point D is
added to the curve.  If D is added to the curve, then the
algorithm is applied recursively to the points A and D, and D and
B. It is repeated ``adaptive_recursion`` times (5, by default).
 
The actual sample points are slightly randomized, so the above
plots may look slightly different each time you draw them.
 
We draw the graph of an elliptic curve as the union of graphs of 2
functions.
 
::
 
    sage: def h1(x): return abs(sqrt(x^3  - 1))
    sage: def h2(x): return -abs(sqrt(x^3  - 1))
    sage: P = plot([h1, h2], 1,4)
    sage: P          # show the result
 
We can also directly plot the elliptic curve::
 
    sage: E = EllipticCurve([0,-1])
    sage: plot(E, (1, 4), color=hue(0.6))
 
We can change the line style to one of ``'--'`` (two hyphens, yielding
dashed), ``'-.'`` (dash dot), ``'-'`` (solid), ``'steps'``, ``':'`` (dotted)::
 
    sage: plot(sin(x), 0, 10, linestyle='-.')
 
Sage currently ignores points that cannot be evaluated
 
::
 
    sage: set_verbose(-1)
    sage: plot(-x*log(x), (x,0,1))  # this works fine since the failed endpoint is just skipped.
    sage: set_verbose(0)
 
This prints out a warning and plots where it can (we turn off the
warning by setting the verbose mode temporarily to -1.)
 
::
 
    sage: set_verbose(-1)
    sage: plot(x^(1/3), (x,-1,1))
    sage: set_verbose(0)
 
To plot the negative real cube root, use something like the following::
 
    sage: plot(lambda x : RR(x).nth_root(3), (x,-1, 1))
 
We can detect the poles of a function::
 
    sage: plot(gamma, (-3, 4), detect_poles = True).show(ymin = -5, ymax = 5)
 
We draw the Gamma-Function with its poles highlighted::
 
    sage: plot(gamma, (-3, 4), detect_poles = 'show').show(ymin = -5, ymax = 5)
 
The basic options for filling a plot::
 
    sage: p1 = plot(sin(x), -pi, pi, fill = 'axis')
    sage: p2 = plot(sin(x), -pi, pi, fill = 'min')
    sage: p3 = plot(sin(x), -pi, pi, fill = 'max')
    sage: p4 = plot(sin(x), -pi, pi, fill = 0.5)
    sage: graphics_array([[p1, p2], [p3, p4]]).show(frame=True, axes=False)
 
    sage: plot([sin(x), cos(2*x)*sin(4*x)], -pi, pi, fill = {0: 1}, fillcolor = 'red', fillalpha = 1)
 
A example about the growth of prime numbers::
 
    sage: plot(1.13*log(x), 1, 100, fill = lambda x: nth_prime(x)/floor(x), fillcolor = 'red')
 
Fill the area between a function and its asymptote::
 
    sage: f = (2*x^3+2*x-1)/((x-2)*(x+1))
    sage: plot([f, 2*x+2], -7,7, fill = {0: [1]}, fillcolor='#ccc').show(ymin=-20, ymax=20)
 
Fill the area between a list of functions and the x-axis::
 
    sage: def b(n): return lambda x: bessel_J(n, x)
    sage: plot([b(n) for n in [1..5]], 0, 20, fill = 'axis')
 
Note that to fill between the ith and jth functions, you
must use dictionary key-value pairs i:[j]; key-value pairs
like i:j will fill between the ith function and the line y=j::
 
    sage: def b(n): return lambda x: bessel_J(n, x) + 0.5*(n-1)
    sage: plot([b(c) for c in [1..5]], 0, 40, fill = dict([(i, [i+1]) for i in [0..3]]))
    sage: plot([b(c) for c in [1..5]], 0, 40, fill = dict([(i, i+1) for i in [0..3]]))
 
Extra options will get passed on to show(), as long as they are valid::
 
    sage: plot(sin(x^2), (x, -3, 3), axes_labels=['$x$','$y$']) # These labels will be nicely typeset
    sage: plot(sin(x^2), (x, -3, 3), axes_labels=['x','y']) # These will not
 
::
 
    sage: plot(sin(x^2), (x, -3, 3), figsize=[8,2])
    sage: plot(sin(x^2), (x, -3, 3)).show(figsize=[8,2]) # These are equivalent
 
A example with excluded values::
 
    sage: plot(floor(x), (x, 1, 10), exclude = [1..10])
 
We exclude all points where prime_pi makes a jump::
 
    sage: jumps = [n for n in [1..100] if prime_pi(n) != prime_pi(n-1)]
    sage: plot(lambda x: prime_pi(x), (x, 1, 100), exclude = jumps)
 
Excluded points can also be given by an equation::
 
    sage: g(x) = x^2-2*x-2
    sage: plot(1/g(x), (x, -3, 4), exclude = g(x) == 0, ymin = -5, ymax = 5)
 
``exclude`` and ``detect_poles`` can be used together::
    sage: f(x) = (floor(x)+0.5) / (1-(x-0.5)^2)
    sage: plot(f, (x, -3.5, 3.5), detect_poles = 'show', exclude = [-3..3], ymin = -5, ymax = 5)
 
TESTS:
 
We do not randomize the endpoints::
 
    sage: p = plot(x, (x,-1,1))
    sage: p[0].xdata[0] == -1
    True
    sage: p[0].xdata[-1] == 1
    True
 
We check to make sure that the x/y min/max data get set correctly
when there are multiple functions.
 
::
 
    sage: d = plot([sin(x), cos(x)], 100, 120).get_minmax_data()
    sage: d['xmin']
    100.0
    sage: d['xmax']
    120.0   
 
We check various combinations of tuples and functions, ending with
tests that lambda functions work properly with explicit variable
declaration, without a tuple.
 
::
 
    sage: p = plot(lambda x: x,(x,-1,1))
    sage: p = plot(lambda x: x,-1,1)
    sage: p = plot(x,x,-1,1)
    sage: p = plot(x,-1,1)
    sage: p = plot(x^2,x,-1,1)
    sage: p = plot(x^2,xmin=-1,xmax=2)
    sage: p = plot(lambda x: x,x,-1,1)
    sage: p = plot(lambda x: x^2,x,-1,1)
    sage: p = plot(lambda x: 1/x,x,-1,1)
    sage: f(x) = sin(x+3)-.1*x^3
    sage: p = plot(lambda x: f(x),x,-1,1)
 
We check to handle cases where the function gets evaluated at a
point which causes an 'inf' or '-inf' result to be produced.
 
::
 
    sage: p = plot(1/x, 0, 1)
    sage: p = plot(-1/x, 0, 1)
 
Bad options now give better errors::
 
    sage: P = plot(sin(1/x), (x,-1,3), foo=10)
    Traceback (most recent call last):
    ...
    RuntimeError: Error in line(): option 'foo' not valid.