Merge pull request #97 from ytdHuang/fix/docs2

Fix documentation examples (2 try)
qutip · Sep 9, 2024 · 476f65d · 476f65d · ytdHuang · Sep 9, 2024
2 parents 6e449ae + bb954fa
commit 476f65d
Show file tree

Hide file tree

Showing 9 changed files with 102 additions and 19 deletions.
diff --git a/.github/workflows/CompatHelper.yml b/.github/workflows/CompatHelper.yml
@@ -21,7 +21,7 @@ jobs:
       - name: "Run CompatHelper"
         run: |
           import CompatHelper;
-          CompatHelper.main(;subdirs=["", "docs"])
+          CompatHelper.main(;subdirs=[""])
         shell: julia --color=yes {0}
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

diff --git a/Project.toml b/Project.toml
@@ -1,7 +1,7 @@
 name = "HierarchicalEOM"
 uuid = "a62dbcb7-80f5-4d31-9a88-8b19fd92b128"
 authors = ["Yi-Te Huang <[email protected]>"]
-version = "2.1.0"
+version = "2.1.1"
 
 [deps]
 DiffEqCallbacks = "459566f4-90b8-5000-8ac3-15dfb0a30def"

diff --git a/docs/Project.toml b/docs/Project.toml
@@ -1,11 +1,7 @@
 [deps]
-BenchmarkTools = "6e4b80f9-dd63-53aa-95a3-0cdb28fa8baf"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 HierarchicalEOM = "a62dbcb7-80f5-4d31-9a88-8b19fd92b128"
 LaTeXStrings = "b964fa9f-0449-5b57-a5c2-d3ea65f4040f"
-LinearSolve = "7ed4a6bd-45f5-4d41-b270-4a48e9bafcae"
 Literate = "98b081ad-f1c9-55d3-8b20-4c87d4299306"
-OrdinaryDiffEq = "1dea7af3-3e70-54e6-95c3-0bf5283fa5ed"
-Pardiso = "46dd5b70-b6fb-5a00-ae2d-e8fea33afaf2"
 Plots = "91a5bcdd-55d7-5caf-9e0b-520d859cae80"
 QuantumToolbox = "6c2fb7c5-b903-41d2-bc5e-5a7c320b9fab"
diff --git a/docs/make.jl b/docs/make.jl
@@ -7,7 +7,7 @@ using Documenter, HierarchicalEOM
 
 DocMeta.setdocmeta!(HierarchicalEOM, :DocTestSetup, :(using HierarchicalEOM); recursive = true)
 
-const DRAFT = true # set `true` to disable cell evaluation
+const DRAFT = false # set `true` to disable cell evaluation
 
 ENV["GKSwstype"] = "100" # enable headless mode for GR to suppress warnings when plotting
 
@@ -41,14 +41,6 @@ for file in EX_source_files
     Literate.markdown(file, doc_output_path)
 end
 
-# Generate benchmark pages
-BENCHMARKS = ["benchmark_ODE_solvers", "benchmark_LS_solvers"]
-BM_source_files = [abspath(joinpath(@__DIR__, "..", "examples", "$(bm_name).jl")) for bm_name in BENCHMARKS]
-BM_output_files = ["examples/$(bm_name).md" for bm_name in BENCHMARKS]
-for file in BM_source_files
-    Literate.markdown(file, doc_output_path)
-end
-
 const PAGES = Any[
     "Home"=>Any[
         "Introduction"=>"index.md",
@@ -81,7 +73,10 @@ const PAGES = Any[
         "Stationary State"=>"stationary_state.md",
         "Spectrum"=>"spectrum.md",
         "Examples"=>EX_output_files,
-        "Benchmark Solvers"=>BM_output_files,
+        "Solvers Lists"=>Any[
+            "ODE_solvers.md",
+            "LS_solvers.md",
+        ],
         "Extensions"=>Any["CUDA.jl"=>"extensions/CUDA.md"],
     ],
     "Library API"=>"libraryAPI.md",

diff --git a/docs/src/LS_solvers.md b/docs/src/LS_solvers.md
@@ -0,0 +1,43 @@
+# [LinearSolve solvers](@id LS-solvers)
+
+In this page, we list several recommended solvers provided by [LinearSolve.jl](https://docs.sciml.ai/LinearSolve/stable/) for solving SteadyState and spectrum in hierarchical equations of motion approach.  
+
+Remember to import `LinearSolve.jl`
+
+```julia
+using LinearSolve
+```
+
+(click [here](https://docs.sciml.ai/LinearSolve/stable/solvers/solvers/) to see the full solver list provided by `LinearSolve.jl`)
+
+### UMFPACKFactorization (Default solver)
+This solver performs better when there is more structure to the sparsity pattern (depends on the complexity of your system and baths).
+
+```julia
+UMFPACKFactorization()
+```
+
+### KLUFactorization
+This solver performs better when there is less structure to the sparsity pattern (depends on the complexity of your system and baths).
+
+```julia
+KLUFactorization()
+```
+
+### A generic BICGSTAB implementation from Krylov
+
+```julia
+KrylovJL_BICGSTAB()
+```
+
+### Pardiso
+This solver is based on Intel openAPI Math Kernel Library (MKL) Pardiso
+!!! note "Note"
+    Using this solver requires adding the package [Pardiso.jl](https://github.com/JuliaSparse/Pardiso.jl), i.e. `using Pardiso`
+
+```julia
+using Pardiso
+using LinearSolve
+MKLPardisoFactorize()
+MKLPardisoIterate()
+```
diff --git a/docs/src/ODE_solvers.md b/docs/src/ODE_solvers.md
@@ -0,0 +1,49 @@
+# [DifferentialEquations solvers](@id ODE-solvers)
+
+In this page, we list several recommended solvers provided by [DifferentialEquations.jl](https://docs.sciml.ai/DiffEqDocs/stable/) for solving time evolution in hierarchical equations of motion approach.  
+
+Remember to import `OrdinaryDiffEq.jl` (or `DifferentialEquations.jl`)
+
+```julia
+using OrdinaryDiffEq ## or "using DifferentialEquations" 
+```
+
+(click [here](https://docs.sciml.ai/DiffEqDocs/stable/solvers/ode_solve/) to see the full solver list provided by `DifferentialEquations.jl`)
+
+For any extra solver options, we can add it in the function `evolution` with keyword arguments. These keyword arguments will be directly pass to the solvers in `DifferentialEquations`
+(click [here](https://docs.sciml.ai/DiffEqDocs/stable/basics/common_solver_opts/) to see the documentation for the common solver options)
+
+### DP5 (Default solver)
+Dormand-Prince's 5/4 Runge-Kutta method. (free 4th order interpolant)
+
+```julia
+DP5()
+```
+
+### RK4
+The canonical Runge-Kutta Order 4 method. Uses a defect control for adaptive stepping using maximum error over the whole interval.
+
+```julia
+RK4()
+```
+
+### Tsit5
+Tsitouras 5/4 Runge-Kutta method. (free 4th order interpolant).
+
+```julia
+Tsit5()
+```
+
+### Vern7
+Verner's “Most Efficient” 7/6 Runge-Kutta method. (lazy 7th order interpolant).
+
+```julia
+Vern7()
+```
+
+### Vern9
+Verner's “Most Efficient” 9/8 Runge-Kutta method. (lazy 9th order interpolant)
+
+```julia
+Vern9()
+```
diff --git a/docs/src/spectrum.md b/docs/src/spectrum.md
@@ -8,7 +8,7 @@ We briefly summarize how to numerically compute the spectrum associated with the
  - [Power Spectrum](@ref doc-PS)
  - [Density of States](@ref doc-DOS)
 
-`HierarchicalEOM.jl` wraps some of the functions in [LinearSolve.jl](http://linearsolve.sciml.ai/stable/), which is a very rich numerical library for solving the linear problems and provides many solvers. It offers quite a few options for the user to tailor the solver to their specific needs. The default solver (and its corresponding settings) are chosen to suit commonly encountered problems and should work fine for most of the cases. If you require more specialized methods, such as the choice of algorithm, please refer to [benchmark for LinearSolve solvers](@ref benchmark-LS-solvers) and also the documentation of [LinearSolve.jl](http://linearsolve.sciml.ai/stable/).
+`HierarchicalEOM.jl` wraps some of the functions in [LinearSolve.jl](http://linearsolve.sciml.ai/stable/), which is a very rich numerical library for solving the linear problems and provides many solvers. It offers quite a few options for the user to tailor the solver to their specific needs. The default solver (and its corresponding settings) are chosen to suit commonly encountered problems and should work fine for most of the cases. If you require more specialized methods, such as the choice of algorithm, please refer to [LinearSolve solvers](@ref LS-solvers) and also the documentation of [LinearSolve.jl](http://linearsolve.sciml.ai/stable/).
 
 !!! compat "Extension for CUDA.jl"
     `HierarchicalEOM.jl` provides an extension to support GPU ([`CUDA.jl`](https://github.com/JuliaGPU/CUDA.jl)) acceleration for solving the spectrum, but this feature requires `Julia 1.9+` and `HierarchicalEOM 1.1+`. See [here](@ref doc-ext-CUDA) for more details.

diff --git a/docs/src/stationary_state.md b/docs/src/stationary_state.md
@@ -9,7 +9,7 @@ The first method is implemented by solving the linear problem
 0=\hat{\mathcal{M}}\rho^{(m,n,p)}_{\textbf{j} \vert \textbf{q}}(t)
 ```
 
-`HierarchicalEOM.jl` wraps some of the functions in [LinearSolve.jl](http://linearsolve.sciml.ai/stable/), which is a very rich numerical library for solving the linear problems and provides many solvers. It offers quite a few options for the user to tailor the solver to their specific needs. The default solver (and its corresponding settings) are chosen to suit commonly encountered problems and should work fine for most of the cases. If you require more specialized methods, such as the choice of algorithm, please refer to [benchmark for LinearSolve solvers](@ref benchmark-LS-solvers) and also the documentation of [LinearSolve.jl](http://linearsolve.sciml.ai/stable/).
+`HierarchicalEOM.jl` wraps some of the functions in [LinearSolve.jl](http://linearsolve.sciml.ai/stable/), which is a very rich numerical library for solving the linear problems and provides many solvers. It offers quite a few options for the user to tailor the solver to their specific needs. The default solver (and its corresponding settings) are chosen to suit commonly encountered problems and should work fine for most of the cases. If you require more specialized methods, such as the choice of algorithm, please refer to [LinearSolve solvers](@ref LS-solvers) and also the documentation of [LinearSolve.jl](http://linearsolve.sciml.ai/stable/).
 
 See the docstring of this method:  
 

diff --git a/docs/src/time_evolution.md b/docs/src/time_evolution.md
@@ -51,7 +51,7 @@ end
 ```
 
 ## Ordinary Differential Equation Method
-The first method is implemented by solving the ordinary differential equation (ODE) as shown above. `HierarchicalEOM.jl` wraps some of the functions in [`DifferentialEquations.jl`](https://diffeq.sciml.ai/stable/), which is a very rich numerical library for solving the differential equations and provides many ODE solvers. It offers quite a few options for the user to tailor the solver to their specific needs. The default solver (and its corresponding settings) are chosen to suit commonly encountered problems and should work fine for most of the cases. If you require more specialized methods, such as the choice of algorithm, please refer to [benchmarks for DifferentialEquations solvers](@ref benchmark-ODE-solvers) and also the documentation of [`DifferentialEquations.jl`](https://diffeq.sciml.ai/stable/).
+The first method is implemented by solving the ordinary differential equation (ODE) as shown above. `HierarchicalEOM.jl` wraps some of the functions in [`DifferentialEquations.jl`](https://diffeq.sciml.ai/stable/), which is a very rich numerical library for solving the differential equations and provides many ODE solvers. It offers quite a few options for the user to tailor the solver to their specific needs. The default solver (and its corresponding settings) are chosen to suit commonly encountered problems and should work fine for most of the cases. If you require more specialized methods, such as the choice of algorithm, please refer to [DifferentialEquations solvers](@ref ODE-solvers) and also the documentation of [`DifferentialEquations.jl`](https://diffeq.sciml.ai/stable/).
 
 !!! compat "Extension for CUDA.jl"
     `HierarchicalEOM.jl` provides an extension to support GPU ([`CUDA.jl`](https://github.com/JuliaGPU/CUDA.jl)) acceleration for solving the time evolution (only for ODE method with time-independent system Hamiltonian), but this feature requires `Julia 1.9+` and `HierarchicalEOM 1.1+`. See [here](@ref doc-ext-CUDA) for more details.