Update and fix docs (#47)

Author: marius311

.gitignore

@@ -19,4 +19,7 @@ scripts/
 test/benchmarks
 !.github/**
 docs/src/*.ipynb
+docs/build
+docs/src-staging/0*
+profiling
 posts

Dockerfile

@@ -28,7 +28,7 @@ RUN apt-get update \
 
 ## install julia
 RUN mkdir /opt/julia \
-    && curl -L https://julialang-s3.julialang.org/bin/linux/x64/1.5/julia-1.5.1-linux-x86_64.tar.gz | tar zxf - -C /opt/julia --strip=1 \
+    && curl -L https://julialang-s3.julialang.org/bin/linux/x64/1.5/julia-1.5.3-linux-x86_64.tar.gz | tar zxf - -C /opt/julia --strip=1 \
     && chown -R 1000 /opt/julia \
     && ln -s /opt/julia/bin/julia /usr/local/bin
 
@@ -53,14 +53,13 @@ RUN curl https://pyenv.run | bash \
 RUN pip install --no-cache-dir \
         cython \
         julia \
-        jupyterlab \
+        jupyterlab==3 \
         jupytext \
         matplotlib \
         "nbconvert<6" \
         numpy \
         scipy \
         setuptools \
-    && jupyter labextension install @jupyterlab/toc \
     && rm -rf $HOME/.cache
 
 ## install CAMB
@@ -89,7 +88,7 @@ COPY --chown=1000 Project.toml $HOME/CMBLensing/
 COPY --chown=1000 docs/Project.toml $HOME/CMBLensing/docs/
 RUN mkdir $HOME/CMBLensing/src && touch $HOME/CMBLensing/src/CMBLensing.jl
 ENV JULIA_PROJECT=$HOME/CMBLensing/docs
-RUN julia -e 'using Pkg; pkg"dev ~/CMBLensing; instantiate; precompile"' \
+RUN julia -e 'using Pkg; pkg"dev ~/CMBLensing; instantiate"' \
     && rm -rf $HOME/.julia/conda/3/pkgs
 COPY --chown=1000 src $HOME/CMBLensing/src
 RUN (test $PRECOMPILE = 0 || julia -e 'using Pkg; pkg"precompile"')

README.md

@@ -41,6 +41,7 @@ You can also clone the repostiory and open the notebooks in [docs/src](https://g
 * _(recommended)_ FFTW.jl built with [`JULIA_FFTW_PROVIDER=MKL`](https://juliamath.github.io/FFTW.jl/stable/#Installation-1) for faster CPU FFTs 
 * _(recommended)_ Python 3 + matplotlib (used for plotting)
 * _(recommended)_ [pycamb](https://github.com/cmbant/CAMB) to generate $C_\ell$'s
+* _(recommended)_ [JuliaMono](https://github.com/cormullion/juliamono/releases) font to ensure characters like `f̃, ϕ, ∇, ℓ`, etc... are rendered correctly
 * _(optional)_ [healpy](https://github.com/healpy/healpy) for experimental curved sky support
 
 ### Native installation

docker-compose.yml

@@ -10,3 +10,8 @@ services:
     hostname: localhost
     environment:
      - PORT=${PORT:-8888}
+    # uncomment to mount local files into container for easier development:
+    # volumes: 
+    #  - "./src:/home/cosmo/CMBLensing/src"
+    #  - "./docs/src:/home/cosmo/CMBLensing/docs/src"
+    #  - "/home/cosmo/.julia"

docs/make.jl

@@ -30,9 +30,10 @@ for file in readdir("src")
     if endswith(file, "ipynb")
         file |> convert_to_markdown |> convert_equations
     elseif !startswith(file, ".")
-        cp("src/$file", "src-staging/$file")
+        cp("src/$file", "src-staging/$file", force=true)
     end
 end
+rm("src-staging/index.md",force=true)
 symlink("../../README.md","src-staging/index.md")
 
 
@@ -152,11 +153,12 @@ makedocs(
     ],
 )
 
-open("build/Dockerfile","w") do io
-    write(io,"FROM $(ENV["IMAGE_NAME"])")
+if haskey(ENV, "IMAGE_NAME")
+    open("build/Dockerfile","w") do io
+        write(io,"FROM $(ENV["IMAGE_NAME"])")
+    end
 end
 
-
 deploydocs(
     repo = "github.com/marius311/CMBLensing.jl.git",
     push_preview = true,

docs/src-staging/api.md

@@ -1,6 +1,88 @@
 # API 
 
+```@contents
+Pages = ["api.md"]
+```
+
+## Simulation
+```@docs
+load_sim
+resimulate
+resimulate!
+```
+
+## Lensing estimation
+
+```@docs
+MAP_joint
+MAP_marg
+sample_joint
+argmaxf_lnP
+quadratic_estimate
+```
+
+## Field constructors
+
+```@docs
+FlatMap
+FlatFourier
+FlatQUMap
+FlatQUFourier
+FlatEBMap
+FlatEBFourier
+FlatIQUMap
+FlatIQUFourier
+FlatIEBMap
+FlatIEBFourier
+```
+
+## Lensing operators
+
+```@docs
+LenseFlow
+BilinearLens
+Taylens
+PowerLens
+CMBLensing.antilensing
+```
+
+## Configuration options
+
+```@docs
+CMBLensing.FFTW_NUM_THREADS
+CMBLensing.FFTW_TIMELIMIT
+```
+
+## Other
+
 ```@autodocs
 Modules = [CMBLensing]
 Order   = [:function, :type, :macro, :constant]
+Filter  = x -> !(x in [
+    load_sim,
+    resimulate,
+    resimulate!,
+    MAP_joint,
+    MAP_marg,
+    sample_joint,
+    argmaxf_lnP,
+    quadratic_estimate,
+    FlatMap,
+    FlatFourier,
+    FlatQUMap,
+    FlatQUFourier,
+    FlatEBMap,
+    FlatEBFourier,
+    FlatIQUMap,
+    FlatIQUFourier,
+    FlatIEBMap,
+    FlatIEBFourier,
+    LenseFlow,
+    BilinearLens,
+    Taylens,
+    PowerLens,
+    CMBLensing.antilensing,
+    CMBLensing.FFTW_NUM_THREADS,
+    CMBLensing.FFTW_TIMELIMIT,
+])
 ```

docs/src-staging/assets/DejaVuSansMono.ttf

@@ -3,11 +3,10 @@ pre.language-output {
 }
 
 @font-face {
-    font-family: 'DejaVuSansMono';
-    src: url("DejaVuSansMono.ttf");
+    font-family: 'JuliaMono-Regular';
+    src: url("JuliaMono-Regular.ttf");
 }
 
-pre, code, kbd {
-  font-family: 'DejaVuSansMono', Monaco, courier, monospace;
-  font-size: 0.90em;
+code, pre {
+  font-family: 'JuliaMono-Regular', Monaco, courier, monospace !important;
 }

docs/src-staging/assets/JuliaMono-Regular.ttf

@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.2'
       jupytext_version: 1.4.1
   kernelspec:
-    display_name: Julia 1.5.1
+    display_name: Julia 1.5.3
     language: julia
     name: julia-1.5
 ---
@@ -113,8 +113,10 @@ using BenchmarkTools
 @benchmark cache(LenseFlow(ϕ),f)
 ```
 
-Once cached, it's very fast and memory non-intensive to repeatedly apply the operator:
+Once cached, it's faster and less memory intensive to repeatedly apply the operator:
 
 ```julia
 @benchmark Lϕ * f setup=(Lϕ=cache(LenseFlow(ϕ),f))
 ```
+
+Note that this documentation is generated on limited-performance cloud servers. Actual benchmarks are likely much faster locally or on a cluster, and yet (much) faster on [GPU](../06_gpu/).

docs/src-staging/assets/cmblensing.css

@@ -8,7 +8,7 @@ jupyter:
       format_version: '1.2'
       jupytext_version: 1.4.1
   kernelspec:
-    display_name: Julia 1.5.1
+    display_name: Julia 1.5.3
     language: julia
     name: julia-1.5
 ---
@@ -40,14 +40,13 @@ $$ d =  \mathbb{A} \, \mathbb{L}(\phi) \, f + n, $$
 
 where
 
-$$ \mathbb{A} = \mathbb{P} \, \mathbb{M} \, \mathbb{B} $$
+$$ \mathbb{A} = \mathbb{M} \, \mathbb{B} $$
 
 and 
 
 * $\mathbb{L}(\phi)$ is the lensing operation
 * $\mathbb{B}$ is an instrumental transfer function or "beam"
 * $\mathbb{M}$ is a user-chosen mask
-* $\mathbb{P}$ is a pixelization operation which allows one to estimate $f$ on a higher resolution than the data
 * $n$ is the instrumental noise. 
 
 
@@ -93,7 +92,7 @@ To evaluate this posterior, we need the arguments of the probability distributio
 First lets load up some simulated data. The function `load_sim` handles constructing a `DataSet` and is the recommended way to create the various fields and covariances needed. In this case, let's use 1$\mu$K-arcmin noise and a border mask:
 
 ```julia
-@unpack f, f̃, ϕ, ds, L = load_sim(
+@unpack f, f̃, ϕ, ds = load_sim(
     θpix      = 2,
     Nside     = 256,
     T         = Float64,
@@ -142,7 +141,7 @@ For the unlensed and lensed parametrizations, pass `0` and `1` as the first argu
 For example, the following is the same point in parameter space that we evaluated above, just in a different parametrization (any differences to the above value are numerical):
 
 ```julia
--2*lnP(1, L(ϕ)*f, ϕ, ds)
+-2*lnP(1, ds.L(ϕ)*f, ϕ, ds)
 ```
 
 We expect minus twice the posterior evaluated at the truth to be distributed like a $\chi^2$ distribution where the degrees of freedom equals the number of pixels in $d$, $f$, and $\phi$ (i.e. in each of the three Gaussian terms in the posterior). Since these maps are 256x256 and $d$ and $f$ have both Q and U maps, this is:

docs/src/01_lense_a_map.md

@@ -7,7 +7,7 @@ jupyter:
       format_version: '1.2'
       jupytext_version: 1.4.1
   kernelspec:
-    display_name: Julia 1.5.1
+    display_name: Julia 1.5.3
     language: julia
     name: julia-1.5
 ---
@@ -111,7 +111,7 @@ plot(ds.d, title = "data " .* ["E" "B"]);
 Now we compute the maximum of the joint posterior, $\mathcal{P}\big(f, \phi \,\big|\,d\big)$
 
 ```julia
-fbf, ϕbf, history = MAP_joint(ds, nsteps=30, progress=true);
+fJ, ϕJ, history = MAP_joint(ds, nsteps=30, progress=true);
 ```
 
 # Examine results
@@ -136,16 +136,16 @@ Here's how far away our final $\chi^2$ is from this expectation, in units of $\s
 Here's the best-fit $\phi$ relative to the truth,
 
 ```julia
-plot(10^6*[ϕ ϕbf], title=["true" "best-fit"] .* raw" $\phi$", vlim=17);
+plot(10^6*[ϕ ϕJ], title=["true" "best-fit"] .* raw" $\phi$", vlim=17);
 ```
 
 Here is the difference in terms of the power spectra. Note the best-fit has high-$\ell$ power suppressed, like a Wiener filter solution (in fact what we're doing here is akin to a non-linear Wiener filter). In the high S/N region ($\ell\lesssim1000$), the difference is approixmately equal to the noise, which you can see is almost two orders of magnitude below the signal.
 
 ```julia
 loglog(ℓ⁴ * Cℓ.total.ϕϕ, "k")
 loglog(get_ℓ⁴Cℓ(ϕ))
-loglog(get_ℓ⁴Cℓ(ϕbf))
-loglog(get_ℓ⁴Cℓ(ϕbf-ϕ))
+loglog(get_ℓ⁴Cℓ(ϕJ))
+loglog(get_ℓ⁴Cℓ(ϕJ-ϕ))
 xlim(80,3000)
 ylim(5e-9,2e-6)
 legend(["theory",raw"true $\phi$", raw"best-fit $\phi$", "difference"])
@@ -156,11 +156,11 @@ ylabel(raw"$\ell^4 C_\ell$");
 The best-fit unlensed fields relative to truth,
 
 ```julia
-plot([f,fbf], title = ["true", "best-fit"] .* " unlensed " .* ["E" "B"]);
+plot([f,fJ], title = ["true", "best-fit"] .* " unlensed " .* ["E" "B"]);
 ```
 
 The best-fit lensed field (bottom row) relative to truth (top row),
 
 ```julia
-plot([f̃, LenseFlow(ϕbf)*fbf], title = ["true", "best-fit"] .* " lensed " .* ["E" "B"]);
+plot([f̃, LenseFlow(ϕJ)*fJ], title = ["true", "best-fit"] .* " lensed " .* ["E" "B"]);
 ```

docs/src/02_posterior.md

@@ -5,7 +5,7 @@ jupyter:
       extension: .md
       format_name: markdown
       format_version: '1.2'
-      jupytext_version: 1.4.1
+      jupytext_version: 1.9.1
   kernelspec:
     display_name: Python 3
     language: python

docs/src/03_joint_MAP_example.md

@@ -7,7 +7,7 @@ jupyter:
       format_version: '1.2'
       jupytext_version: 1.4.1
   kernelspec:
-    display_name: Julia 1.5.1
+    display_name: Julia 1.5.3
     language: julia
     name: julia-1.5
 ---