Trac #23672: Improve documentation and user interface of Fourier series

As discussed in https://groups.google.com/forum/#!topic/sage-
devel/b1pWen3lrKA, the documentation of Fourier series as implemented in
piecewise-defined functions needs some improvement. This ticket provides
it, as well as a simplification of the user interface: the half-period
is now an optional argument; if not provided, it is inferred from the
domain of the piecewise-defined function:
{{{
sage: f = piecewise([((0, 2*pi), cos(x))])
sage: f.fourier_series_cosine_coefficient(1)  # results in TypeError in
Sage 8.0
1
sage: f.fourier_series_cosine_coefficient(1, pi)  # compatible with Sage
8.0
1
}}}
The ticket also corrects two bugs:
- computation of Fourier coefficients when the domain width does not
coincide with the period:
{{{
sage: f = piecewise([((0, 4*pi), cos(x))])
sage: f.fourier_series_cosine_coefficient(1, pi)  # yields 2 in Sage 8.0
1
}}}
- despite what it claimed, the method `fourier_series_partial_sum` did
not return ''S,,N,,(x)'' but ''S,,N-1,,(x)'' (this is because the
summation was governed by `srange(1, N)` instead of `srange(1, N+1)`);
we have now
{{{
sage: f = piecewise([((0, 2*pi), cos(x))])
sage: f.fourier_series_partial_sum(1, pi)  # yields 0 in Sage 8.0
cos(x)
}}}

URL: https://trac.sagemath.org/23672
Reported by: egourgoulhon
Ticket author(s): Eric Gourgoulhon
Reviewer(s): Richard L Lozes

src/doc/en/constructions/calculus.rst

@@ -3,11 +3,7 @@ Calculus
 ********
 
 Here are some examples of calculus symbolic computations using
-Sage. They use the Maxima interface.
-
-Work is being done to make the commands for the symbolic
-calculations given below more intuitive and natural. At the moment,
-we use the maxima class interface.
+Sage.
 
 
 .. index::
@@ -125,7 +121,7 @@ These are missing symbolic functions, on the other hand::
     w + 17/2*w^2 + 15/4*w^4 + O(w^6)
     sage: ps.exp()
     1 + w + 9*w^2 + 26/3*w^3 + 265/6*w^4 + 413/10*w^5 + O(w^6)
-    sage: (1+ps).log()  
+    sage: (1+ps).log()
     w + 8*w^2 - 49/6*w^3 - 193/8*w^4 + 301/5*w^5 + O(w^6)
     sage: (ps^1000).coefficients()
     [1, 8500, 36088875, 102047312625, 1729600092867375/8]
@@ -356,36 +352,47 @@ Finally, can solve linear DEs using power series:
 Fourier series of periodic functions
 ====================================
 
-If :math:`f(x)` is a piecewise-defined polynomial function on
-:math:`-L<x<L` then the Fourier series
+Let :math:`f` be a real-valued periodic function of period `2L`.
+The Fourier series of `f` is
 
-.. math::
-   f(x) \sim \frac{a_0}{2} + \sum_{n=1}^\infty \left[a_n\cos\left(\frac{n\pi x}{L}\right) +
+.. MATH::
+
+   S(x) = \frac{a_0}{2} + \sum_{n=1}^\infty \left[a_n\cos\left(\frac{n\pi x}{L}\right) +
    b_n\sin\left(\frac{n\pi x}{L}\right)\right]
 
+where
 
-converges. In addition to computing the coefficients
-:math:`a_n,b_n`, it will also compute the partial sums (as a
-string), plot the partial sums (as a function of :math:`x` over
-:math:`(-L,L)`, for comparison with the plot of :math:`f(x)`
-itself), compute the value of the FS at a point, and similar
-computations for the cosine series (if :math:`f(x)` is even) and
-the sine series (if :math:`f(x)` is odd). Also, it will plot the
-partial F.S. Cesaro mean sums (a "smoother" partial sum
-illustrating how the Gibbs phenomenon is mollified).
+.. MATH::
 
-::
+    a_n = \frac{1}{L}\int_{-L}^L
+            f(x)\cos\left(\frac{n\pi x}{L}\right) dx,
+
+and
+
+.. MATH::
+
+    b_n = \frac{1}{L}\int_{-L}^L
+            f(x)\sin\left(\frac{n\pi x}{L}\right) dx,
+
+The Fourier coefficients `a_n` and `b_n` are computed by
+declaring `f` as a piecewise-defined function over one period
+and invoking the methods ``fourier_series_cosine_coefficient``
+and ``fourier_series_sine_coefficient``, while the partial sums
+are obtained via ``fourier_series_partial_sum``::
+
+    sage: f = piecewise([((0,pi/2), -1), ((pi/2,pi), 2)])
+    sage: f.fourier_series_cosine_coefficient(0)
+    1
+    sage: f.fourier_series_sine_coefficient(5)
+    -6/5/pi
+    sage: s5 = f.fourier_series_partial_sum(5); s5
+    -6/5*sin(10*x)/pi - 2*sin(6*x)/pi - 6*sin(2*x)/pi + 1/2
+    sage: plot(f, (0,pi)) + plot(s5, (x,0,pi), color='red')
+    Graphics object consisting of 2 graphics primitives
+
+.. PLOT::
 
-    sage: f1 = lambda x: -1
-    sage: f2 = lambda x: 2
-    sage: f = piecewise([((0,pi/2),f1), ((pi/2,pi),f2)])
-    sage: f.fourier_series_cosine_coefficient(5,pi)
-    -3/5/pi
-    sage: f.fourier_series_sine_coefficient(2,pi)
-    -3/pi
-    sage: f.fourier_series_partial_sum(3,pi)
-    -3*cos(x)/pi - 3*sin(2*x)/pi + sin(x)/pi + 1/4
-
-Type ``show(f.plot_fourier_series_partial_sum(15,pi,-5,5))`` and
-``show(f.plot_fourier_series_partial_sum_cesaro(15,pi,-5,5))``
-(and be patient) to view the partial sums.
+    f = piecewise([((0,pi/2), -1), ((pi/2,pi), 2)])
+    s5 = f.fourier_series_partial_sum(5)
+    g = plot(f, (0,pi)) + plot(s5, (x,0,pi), color='red')
+    sphinx_plot(g)