feat(docs): use literate to make the examples

.gitignore

@@ -1,6 +1,6 @@
 docs/build
-/examples/
 /.vscode/
 Manifest.toml
 docs/src/examples/jupyter_notebooks/.ipynb_checkpoints
 docs/Manifest.toml
+*.ipynb

docs/Project.toml

@@ -1,6 +1,8 @@
 [deps]
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
+Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
 MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09"
 ModelingToolkit = "961ee093-0014-501f-94e3-6117800e7a78"
 OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
@@ -20,7 +22,7 @@ MacroTools = "0.5"
 OrdinaryDiffEq = "6"
 Plots = "1"
 QuantumOptics = "1"
-QuantumOpticsBase = "0.4.21"
+QuantumOpticsBase = "0.4"
 StochasticDiffEq = "6"
 SymbolicUtils = "3.26.0"
 Symbolics = "6"

docs/make.jl

@@ -3,6 +3,8 @@ using QuantumCumulants, SecondQuantizedAlgebra
 
 ENV["GKSwstype"] = "100" # enable headless mode for GR to suppress warnings when plotting
 
+include("make_md_examples.jl")
+
 pages = [
     "index.md",
     "theory.md",

docs/make_md_examples.jl

@@ -0,0 +1,43 @@
+using Literate
+
+### Process examples
+# Always rerun examples
+const EXAMPLES_IN = joinpath(@__DIR__, "..", "examples")
+const OUTPUT_MD_DIR = joinpath(@__DIR__, "src", "examples")
+
+examples = filter!(file -> file[(end-2):end] == ".jl", readdir(EXAMPLES_IN; join = true))
+filter!(
+    file -> !contains(file, "make_nb_examples") && !contains(file, "heterodyne"),
+    examples,
+)
+
+if isempty(get(ENV, "CI", ""))
+    # only needed when building docs locally; set automatically when built under CI
+    # https://fredrikekre.github.io/Literate.jl/v2/outputformats/#Configuration
+    extra_literate_config = Dict(
+        "repo_root_path" => abspath(joinpath(@__DIR__, "..")),
+        "repo_root_url" => "file://" * abspath(joinpath(@__DIR__, "..")),
+    )
+else
+    extra_literate_config = Dict()
+end
+
+function preprocess(content)
+    sub = SubstitutionString("""
+                             """)
+    content = replace(content, r"^# # [^\n]*"m => sub; count = 1)
+
+    # remove VSCode `##` block delimiter lines
+    content = replace(content, r"^##$."ms => "")
+    return content
+end
+
+for example in examples
+    Literate.markdown(
+        example,
+        OUTPUT_MD_DIR;
+        flavor = Literate.DocumenterFlavor(),
+        config = extra_literate_config,
+        # preprocess=preprocess,
+    )
+end

docs/src/examples/cavity_antiresonance_indexed.md

@@ -1,3 +1,7 @@
+```@meta
+EditURL = "../../../examples/cavity_antiresonance_indexed.jl"
+```
+
 # Cavity Antiresonance
 
 In this example we investigate a system of $N$ closely spaced quantum emitters inside a coherently driven single mode cavity. The model is described in [D. Plankensteiner, et. al., Phys. Rev. Lett. 119, 093601 (2017)](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.119.093601).
@@ -17,43 +21,38 @@ Additionally the system features two decay channels, the lossy cavity with photo
 
 We start by loading the packages.
 
-
-```@example antiresonance_indexed
+````@example cavity_antiresonance_indexed
 using QuantumCumulants
 using OrdinaryDiffEq, ModelingToolkit
 using Plots
-```
+````
 
 The Hilbert space for this system is given by one cavity mode and $N$ two-level atoms. Here we use symbolic indices, sums and double sums to define the system.
 The parameters $g_j, \, \Gamma_{ij}$ and $\Omega_{ij}$ are defined as indexed variables of atom $i$ and $j$. We will describe the system in first order mean-field.
 
-
-```@example antiresonance_indexed
-# Hilbert space
-hc = FockSpace(:cavity)
-ha = NLevelSpace(Symbol(:atom),2)
+````@example cavity_antiresonance_indexed
+hc = FockSpace(:cavity) # Hilbert space
+ha = NLevelSpace(Symbol(:atom), 2)
 h = hc ⊗ ha
 
-# Parameter
-@cnumbers N Δc η Δa κ
-g(i) = IndexedVariable(:g,i)
-Γ(i,j) = IndexedVariable(:Γ,i,j)
-Ω(i,j) = IndexedVariable(:Ω,i,j;identical=false)
+@cnumbers N Δc η Δa κ # Parameters
+g(i) = IndexedVariable(:g, i)
+Γ(i, j) = IndexedVariable(:Γ, i, j)
+Ω(i, j) = IndexedVariable(:Ω, i, j; identical = false)
 
-# Indices
-i = Index(h,:i,N,ha)
-j = Index(h,:j,N,ha)
-```
+
+i = Index(h, :i, N, ha) # Indices
+j = Index(h, :j, N, ha)
+````
 
 The kwarg ’identical=false’ for the double indexed variable specifies that $\Omega_{ij} = 0$ for $i = j$.
 Now we create the operators on the composite Hilbert space using the $\texttt{IndexedOperator}$ constructor, which assigns each $\texttt{Transition}$ operator an $\texttt{Index}$.
 
-
-```@example antiresonance_indexed
+````@example cavity_antiresonance_indexed
 @qnumbers a::Destroy(h)
-σ(x,y,k) = IndexedOperator(Transition(h,:σ,x,y),k)
+σ(x, y, k) = IndexedOperator(Transition(h, :σ, x, y), k)
 nothing # hide
-```
+````
 
 We define the Hamiltonian and Liouvillian. For the collective atomic decay we write the corresponding dissipative processes with a double indexed variable $R_{ij}$ and an indexed jump operator $J_j$, such that an operator average $\langle \mathcal{O} \rangle$ follows the equation
 
@@ -63,27 +62,24 @@ We define the Hamiltonian and Liouvillian. For the collective atomic decay we wr
 \end{equation}
 ```
 
-```@example antiresonance_indexed
-# Hamiltonian
-Hc = Δc*a'a + η*(a' + a)
-Ha = Δa*Σ(σ(2,2,i),i) + Σ(Ω(i,j)*σ(2,1,i)*σ(1,2,j),j,i)
-Hi = Σ(g(i)*(a'*σ(1,2,i) + a*σ(2,1,i)),i)
+````@example cavity_antiresonance_indexed
+Hc = Δc*a'a + η*(a' + a) # Hamiltonian
+Ha = Δa*Σ(σ(2, 2, i), i) + Σ(Ω(i, j)*σ(2, 1, i)*σ(1, 2, j), j, i)
+Hi = Σ(g(i)*(a'*σ(1, 2, i) + a*σ(2, 1, i)), i)
 H = Hc + Ha + Hi
 
-# Jump operators & and rates
-J = [a, σ(1,2,i)]
-rates = [κ, Γ(i,j)]
+J = [a, σ(1, 2, i)] # Jump operators
+rates = [κ, Γ(i, j)]
 nothing # hide
-```
+````
 
 We derive the system of equations in first order mean-field.
 
-
-```@example antiresonance_indexed
-eqs = meanfield(a,H,J;rates=rates,order=1)
+````@example cavity_antiresonance_indexed
+eqs = meanfield(a, H, J; rates = rates, order = 1)
 complete!(eqs)
 nothing # hide
-```
+````
 
 ```math
 \begin{align}
@@ -93,74 +89,86 @@ nothing # hide
 \end{align}
 ```
 
-
-
 To create the equations for a specific number of atoms we use the function $\texttt{evaluate}$.
 
-
-```@example antiresonance_indexed
+````@example cavity_antiresonance_indexed
 N_ = 2
-eqs_ = evaluate(eqs;limits=(N=>N_))
+eqs_ = evaluate(eqs; limits = (N=>N_))
 @named sys = System(eqs_)
 nothing # hide
-```
+````
 
 Finally we need to define the initial state of the system and the numerical parameters. In the end we want to obtain the transmission rate $T$ of our system. For this purpose we calculate the steady state photon number in the cavity $|\langle a \rangle|^2$ for different laser frequencies.
 
-
-```@example antiresonance_indexed
+````@example cavity_antiresonance_indexed
 u0 = zeros(ComplexF64, length(eqs_))
-# parameter
-Γ_ = 1.0
+Γ_ = 1.0 # parameter
 d = 2π*0.08 #0.08λ
 θ = π/2
 
-Ωij(i,j) = i==j ? 0 : Γ_*(-3/4)*( (1-(cos(θ))^2)*cos(d)/d-(1-3*(cos(θ))^2)*(sin(d)/(d^2)+(cos(d)/(d^3))) )
-Γij(i,j) = i==j ? Γ_ : Γ_*(3/2)*( (1-(cos(θ))^2)*sin(d)/d+(1-3*(cos(θ))^2)*((cos(d)/(d^2))-(sin(d)/(d^3))))
+Ωij(i, j) =
+    i==j ? 0 :
+    Γ_*(-3/4)*((1-(cos(θ))^2)*cos(d)/d-(1-3*(cos(θ))^2)*(sin(d)/(d^2)+(cos(d)/(d^3))))
+Γij(i, j) =
+    i==j ? Γ_ :
+    Γ_*(3/2)*((1-(cos(θ))^2)*sin(d)/d+(1-3*(cos(θ))^2)*((cos(d)/(d^2))-(sin(d)/(d^3))))
 
 g_ = 2Γ_
 κ_ = 20Γ_
 Δa_ = 0Γ_
 Δc_ = 0Γ_
 η_ = κ_/100
 
-gi_ls = [g(i) for i=1:N_]
-Γij_ls = [Γ(i,j) for i = 1:N_ for j=1:N_]
-Ωij_ls = [Ω(i,j) for i = 1:N_ for j=1:N_ if i≠j]
+gi_ls = [g(i) for i = 1:N_]
+Γij_ls = [Γ(i, j) for i = 1:N_ for j = 1:N_]
+Ωij_ls = [Ω(i, j) for i = 1:N_ for j = 1:N_ if i≠j]
 
-# list of symbolic indexed parameters
-gi_ = [g_*(-1)^i for i=1:N_]
-Γij_ = [Γij(i,j) for i = 1:N_ for j=1:N_]
-Ωij_ = [Ωij(i,j) for i = 1:N_ for j=1:N_ if i≠j]
+gi_ = [g_*(-1)^i for i = 1:N_] # list of symbolic indexed parameters
+Γij_ = [Γij(i, j) for i = 1:N_ for j = 1:N_]
+Ωij_ = [Ωij(i, j) for i = 1:N_ for j = 1:N_ if i≠j]
 
 ps = [Δc; η; Δa; κ; gi_ls; Γij_ls; Ωij_ls]
 p0 = [Δc_; η_; Δa_; κ_; gi_; Γij_; Ωij_]
 nothing # hide
-```
-
+````
 
-```@example antiresonance_indexed
+````@example cavity_antiresonance_indexed
 Δ_ls = [-10:0.05:10;]Γ_
 n_ls = zeros(length(Δ_ls))
 
-for i=1:length(Δ_ls)
+for i = 1:length(Δ_ls)
     Δc_i = Δ_ls[i]
-    Δa_i = Δc_i + Ωij(1,2) # cavity on resonace with the shifted collective emitter
+    Δa_i = Δc_i + Ωij(1, 2) # cavity on resonace with the shifted collective emitter
     p0_ = [Δc_i; η_; Δa_i; κ_; gi_; Γij_; Ωij_]
-
-    # create (remake) new ODEProblem
-    dict = merge(Dict(unknowns(sys) .=> u0), Dict(ps .=> p0_))
-    prob_  = ODEProblem(sys,dict,(0.0, 20))
+
+    dict = merge(Dict(unknowns(sys) .=> u0), Dict(ps .=> p0_)) # create (remake) new ODEProblem
+    prob_ = ODEProblem(sys, dict, (0.0, 20))
     sol_ = solve(prob_, Tsit5())
     n_ls[i] = abs2(sol_[a][end])
 end
 nothing #hide
-```
+````
 
 The transmission rate $T$ with respect to the pump laser detuning is given by the relative steady state intra-cavity photon number $n(\Delta)/n_\mathrm{max}$. We qualitatively reproduce the antiresonance from [D. Plankensteiner, et. al., Phys. Rev. Lett. 119, 093601 (2017)](https://journals.aps.org/prl/abstract/10.1103/PhysRevLett.119.093601) for two atoms.
 
-
-```@example antiresonance_indexed
+````@example cavity_antiresonance_indexed
 T = n_ls ./ maximum(n_ls)
-plot(Δ_ls, T, xlabel="Δ/Γ", ylabel="T", legend=false)
-```
+plot(Δ_ls, T, xlabel = "Δ/Γ", ylabel = "T", legend = false)
+````
+
+## Package versions
+
+These results were obtained using the following versions:
+
+````@example cavity_antiresonance_indexed
+using InteractiveUtils
+versioninfo()
+
+using Pkg
+Pkg.status(["QuantumCumulants", "OrdinaryDiffEq", "ModelingToolkit", "Plots"], mode = PKGMODE_MANIFEST)
+````
+
+---
+
+*This page was generated using [Literate.jl](https://github.com/fredrikekre/Literate.jl).*
+