start adding docs

Author: MikaelSlevinsky

README.md

@@ -126,8 +126,10 @@ As with other fast transforms, `plan_sph2fourier` saves effort by caching the pr
 
    [2]  N. Hale and A. Townsend. <a href="http://dx.doi.org/10.1137/130932223">A fast, simple, and stable Chebyshev—Legendre transform using and asymptotic formula</a>, *SIAM J. Sci. Comput.*, **36**:A148—A167, 2014.
 
-   [3]  R. M. Slevinsky. <a href="https://doi.org/10.1093/imanum/drw070">On the use of Hahn's asymptotic formula and stabilized recurrence for a fast, simple, and stable Chebyshev—Jacobi transform</a>, published online in *IMA J. Numer. Anal.*, 2017.
+   [3] J. Keiner. <a href="http://dx.doi.org/10.1137/070703065">Computing with expansions in Gegenbauer polynomials</a>, *SIAM J. Sci. Comput.*, **31**:2151—2171, 2009.
 
-   [4]  R. M. Slevinsky. <a href="https://arxiv.org/abs/">Fast and backward stable transforms between spherical harmonic expansions and bivariate Fourier series</a>, arXiv, 2017.
+   [4]  R. M. Slevinsky. <a href="https://doi.org/10.1093/imanum/drw070">On the use of Hahn's asymptotic formula and stabilized recurrence for a fast, simple, and stable Chebyshev—Jacobi transform</a>, in press at *IMA J. Numer. Anal.*, 2017.
 
-   [5]  A. Townsend, M. Webb, and S. Olver. <a href="http://arxiv.org/abs/1604.07486">Fast polynomial transforms based on Toeplitz and Hankel matrices</a>, arXiv:1604.07486, 2016.
+   [5]  R. M. Slevinsky. <a href="https://arxiv.org/abs/">Fast and backward stable transforms between spherical harmonic expansions and bivariate Fourier series</a>, arXiv, 2017.
+
+   [6]  A. Townsend, M. Webb, and S. Olver. <a href="https://doi.org/10.1090/mcom/3277">Fast polynomial transforms based on Toeplitz and Hankel matrices</a>, in press at *Math. Comp.*, 2017.

docs/make.jl

@@ -18,6 +18,6 @@ deploydocs(
     julia  = "0.5",
     osname = "linux",
     target = "build",
-    deps   = nothing,
+    deps   = Deps.pip("pygments", "mkdocs", "python-markdown-math"),
     make   = nothing
     )

docs/src/index.md

@@ -1,8 +1,46 @@
 # FastTransforms.jl Documentation
 
+## Introduction
+
+In numerical analysis, it is customary to expand a function in a basis:
+```math
+f(x) = \sum_{\ell = 0}^{n} f_{\ell} \phi_{\ell}(x).
+```
+Orthogonal polynomials are examples of convenient bases for sufficiently smooth functions. To perform some operation, it may be necessary to convert our representation to one in a new basis, say, ``\{\psi_m(x)\}_{m\ge0}``.
+
+If each function ``\phi_{\ell}`` is expanded in the basis ``\psi_m``, such as:
+```math
+\phi_{\ell}(x) \sim \sum_{m=0}^{\infty} c_{m,\ell}\psi_{m}(x),
+```
+then our original function has the alternative representation:
+```math
+f(x) \sim \sum_{m = 0}^{\infty} g_m \psi_m(x),
+```
+where ``g_m`` are defined by the sum:
+```math
+g_m = \sum_{\ell = 0}^{n} c_{m,\ell} f_{\ell}.
+```
+
+This is the classical connection problem. In many cases of interest, the both representations are finite and we seek a fast method (faster than ``\mathcal{O}(n^2)``) to transform the coefficients ``f_{\ell}`` to ``g_m``. These are the fast transforms.
 
 ## Fast Transforms
 
+```@docs
+leg2cheb
+```
+
+```@docs
+cheb2leg
+```
+
+```@docs
+plan_leg2cheb
+```
+
+```@docs
+plan_cheb2leg
+```
+
 ```@docs
 cjt
 ```
@@ -39,6 +77,18 @@ plan_paduatransform!
 plan_ipaduatransform!
 ```
 
+```@docs
+sph2fourier
+```
+
+```@docs
+fourier2sph
+```
+
+```@docs
+plan_sph2fourier
+```
+
 ## Other Exported Methods
 
 ```@docs

src/SphericalHarmonics/SphericalHarmonics.jl

@@ -36,3 +36,76 @@ end
 
 sph2fourier(A::AbstractMatrix; opts...) = plan_sph2fourier(A; opts...)*A
 fourier2sph(A::AbstractMatrix; opts...) = plan_sph2fourier(A; opts...)\A
+
+doc"""
+Computes the bivariate Fourier series given by the spherical harmonic expansion:
+
+```math
+{\rm SHT} : \sum_{\ell=0}^n\sum_{m=-\ell}^{\ell} f_{\ell}^m Y_{\ell}^m(\theta,\varphi) \to \sum_{\ell=0}^n\sum_{m=-n}^{n} g_{\ell}^m \frac{e^{{\rm i} m \varphi}}{\sqrt{2\pi}} \left\{\begin{array}{c}\cos\ell\theta\\ \sin(\ell+1)\theta\end{array}\right\},
+```
+
+where the cosines are used when ``m`` is even and the sines are used when ``m`` is odd. The spherical harmonic expansion coefficients are organized as follows:
+
+```math
+F = \begin{pmatrix}
+f_0^0 & f_1^{-1} & f_1^1 & f_2^{-2} & f_2^2 & \cdots & f_n^{-n} & f_n^n\\
+f_1^0 & f_2^{-1} & f_2^1 & f_3^{-2} & f_3^2 & \cdots & 0 & 0\\
+\vdots & \vdots & \vdots &  \vdots &  \vdots & \ddots & \vdots & \vdots\\
+f_{n-2}^0 & f_{n-1}^{-1} & f_{n-1}^1 & f_n^{-2} & f_n^2 &  & \vdots & \vdots\\
+f_{n-1}^0 & f_n^{-1} & f_n^1 & 0 & 0 & \cdots & 0 & 0\\
+f_n^0 & 0 & 0 & 0 & 0 & \cdots & 0 & 0\\
+\end{pmatrix},
+```
+
+and the Fourier coefficients are organized similarly:
+
+```math
+G = \begin{pmatrix}
+g_0^0 & g_0^{-1} & g_0^1 & \cdots & g_0^{-n} & g_0^n\\
+g_1^0 & g_1^{-1} & g_1^1 & \cdots & g_1^{-n} & g_1^n\\
+\vdots & \vdots & \vdots & \ddots & \vdots & \vdots\\
+g_{n-1}^0 & g_{n-1}^{-1} & g_{n-1}^1& \cdots & g_{n-1}^{-n} & g_{n-1}^n\\
+g_n^0 & 0 & 0 & \cdots & g_n^{-n} & g_n^n\\
+\end{pmatrix}.
+```
+"""
+sph2fourier(::AbstractMatrix; opts...)
+
+doc"""
+Computes the spherical harmonic expansion given by the bivariate Fourier series:
+
+```math
+{\rm iSHT} : \sum_{\ell=0}^n\sum_{m=-n}^{n} g_{\ell}^m \frac{e^{{\rm i} m \varphi}}{\sqrt{2\pi}} \left\{\begin{array}{c}\cos\ell\theta\\ \sin(\ell+1)\theta\end{array}\right\} \to \sum_{\ell=0}^n\sum_{m=-\ell}^{\ell} f_{\ell}^m Y_{\ell}^m(\theta,\varphi),
+```
+
+where the cosines are used when ``m`` is even and the sines are used when ``m`` is odd. The spherical harmonic expansion coefficients are organized as follows:
+
+```math
+F = \begin{pmatrix}
+f_0^0 & f_1^{-1} & f_1^1 & f_2^{-2} & f_2^2 & \cdots & f_n^{-n} & f_n^n\\
+f_1^0 & f_2^{-1} & f_2^1 & f_3^{-2} & f_3^2 & \cdots & 0 & 0\\
+\vdots & \vdots & \vdots &  \vdots &  \vdots & \ddots & \vdots & \vdots\\
+f_{n-2}^0 & f_{n-1}^{-1} & f_{n-1}^1 & f_n^{-2} & f_n^2 &  & \vdots & \vdots\\
+f_{n-1}^0 & f_n^{-1} & f_n^1 & 0 & 0 & \cdots & 0 & 0\\
+f_n^0 & 0 & 0 & 0 & 0 & \cdots & 0 & 0\\
+\end{pmatrix},
+```
+
+and the Fourier coefficients are organized similarly:
+
+```math
+G = \begin{pmatrix}
+g_0^0 & g_0^{-1} & g_0^1 & \cdots & g_0^{-n} & g_0^n\\
+g_1^0 & g_1^{-1} & g_1^1 & \cdots & g_1^{-n} & g_1^n\\
+\vdots & \vdots & \vdots & \ddots & \vdots & \vdots\\
+g_{n-1}^0 & g_{n-1}^{-1} & g_{n-1}^1& \cdots & g_{n-1}^{-n} & g_{n-1}^n\\
+g_n^0 & 0 & 0 & \cdots & g_n^{-n} & g_n^n\\
+\end{pmatrix}.
+```
+"""
+fourier2sph(::AbstractMatrix; opts...)
+
+doc"""
+Pre-computes the spherical harmonic transform.
+"""
+plan_sph2fourier(::AbstractMatrix; opts...)

src/hierarchical.jl

@@ -439,3 +439,31 @@ ChebyshevToNormalizedLegendrePlan(v::VecOrMat) = ChebyshevToNormalizedLegendrePl
 
 NormalizedLegendre1ToChebyshev2Plan(v::VecOrMat) = NormalizedLegendre1ToChebyshev2Plan(plan_even_normleg12cheb2(v), plan_odd_normleg12cheb2(v), eltype(v)[sqrt((j+0.5)/(j*(j+1))) for j in 1:size(v, 1)])
 Chebyshev2ToNormalizedLegendre1Plan(v::VecOrMat) = Chebyshev2ToNormalizedLegendre1Plan(plan_even_cheb22normleg1(v), plan_odd_cheb22normleg1(v), eltype(v)[sqrt(i*(i+1)/(i+0.5)) for i in 1:size(v, 1)])
+
+doc"""
+Computes the Chebyshev expansion coefficients given the Legendre expansion coefficients:
+
+```math
+{\rm CLT} : \sum_{n=0}^N c_n^{\rm leg}P_n(x) \to \sum_{n=0}^N c_n^{\rm cheb}T_n(x).
+```
+"""
+leg2cheb(::Vector)
+
+doc"""
+Computes the Legendre expansion coefficients given the Chebyshev expansion coefficients:
+
+```math
+{\rm iCLT} : \sum_{n=0}^N c_n^{\rm cheb}T_n(x) \to \sum_{n=0}^N c_n^{\rm leg}P_n(x).
+```
+"""
+cheb2leg(::Vector)
+
+doc"""
+Pre-computes the Legendre--Chebyshev transform.
+"""
+plan_leg2cheb(::Vector)
+
+doc"""
+Pre-computes the Chebyshev--Legendre transform.
+"""
+plan_cheb2leg(::Vector)