Change documentation structure

qutip · May 27, 2024 · b6c007c · b6c007c
1 parent 1d5df9c
commit b6c007c
Show file tree

Hide file tree

Showing 10 changed files with 60 additions and 42 deletions.
diff --git a/.JuliaFormatter.toml b/.JuliaFormatter.toml
@@ -5,8 +5,7 @@ long_to_short_function_def=true
 always_use_return=true
 format_docstrings=true
 indent_submodule=true
-format_markdown=true
+format_markdown=false
 ignore = [
-    "README.md", 
-    "CODE_OF_CONDUCT.md"
+    "docs/make.jl",
 ]
diff --git a/docs/make.jl b/docs/make.jl
@@ -4,9 +4,8 @@ using Documenter
 DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive = true)
 
 const PAGES = [
-    "Front Matter" => [
+    "Getting Started" => [
         "Introduction" => "index.md",
-        "Installation" => "install.md",
         "Key differences from QuTiP" => "qutip_differences.md",
         # "Cite QuantumToolbox.jl" => "cite.md",
     ],
@@ -15,21 +14,13 @@ const PAGES = [
             "users_guide/QuantumObject/QuantumObject.md",
             "users_guide/QuantumObject/QuantumObject_functions.md",
         ],
-        "Manipulating States and Operators" => [
-            "users_guide/states_and_operators/state_vectors.md",
-            "users_guide/states_and_operators/density_matrices.md",
-            "users_guide/states_and_operators/qubit_systems.md",
-            "users_guide/states_and_operators/expectation_values.md",
-            "users_guide/states_and_operators/superoperators.md",
-        ],
-        "Tensor Products and Partial Traces" => [
-            "users_guide/tensor_product/tensor.md",
-            "users_guide/tensor_product/partial_trace.md",
-        ],
+        "Manipulating States and Operators" => "users_guide/states_and_operators/states_and_operators.md",
+        "Tensor Products and Partial Traces" => "users_guide/tensor_product/tensor.md",
         "Time Evolution and Dynamics" => [
-            "users_guide/time_evolution/intro.md"
+            "Introduction" => "users_guide/time_evolution/intro.md"
         ],
         "Solving for Steady-State Solutions" => [],
+        "Symmetries" => [],
         "Two-time correlation functions" => [],
         "Extensions" => [
             "users_guide/extensions/cuda.md",

diff --git a/docs/src/index.md b/docs/src/index.md
@@ -2,7 +2,7 @@
 CurrentModule = QuantumToolbox
 ```
 
-# [Introduction](@id doc: Introduction)
+# QuantumToolbox.jl Documentation
 
 [QuantumToolbox.jl](https://github.com/qutip/QuantumToolbox.jl) is a cutting-edge Julia package designed for quantum physics simulations, closely emulating the popular Python [QuTiP](https://github.com/qutip/qutip) package. It uniquely combines the simplicity and power of Julia with advanced features like GPU acceleration and distributed computing, making simulation of quantum systems more accessible and efficient.
 
@@ -18,7 +18,30 @@ QuantumToolbox.jl is equipped with a robust set of features:
 - **Distributed Computing:** Distribute the computation over multiple nodes (e.g., a cluster). For example, you can run undreds of quantum trajectories in parallel on a cluster, with, again, the same syntax as the simple case.
 - **Easy Extension:** Easily extend the package, taking advantage of the Julia language features, like multiple dispatch and metaprogramming.
 
-## Brief example
+## [Installation](@id doc: Installation)
+
+!!! note "Requirements"
+    `QuantumToolbox.jl` requires `Julia 1.7+`.
+
+To install `QuantumToolbox.jl`, run the following commands inside Julia's interactive session (also known as REPL):
+```julia
+using Pkg
+Pkg.add("QuantumToolbox")
+```
+Alternatively, this can also be done in Julia's [Pkg REPL](https://julialang.github.io/Pkg.jl/v1/getting-started/) by pressing the key `]` in the REPL to use the package mode, and then type the following command:
+```julia-REPL
+(1.7) pkg> add QuantumToolbox
+```
+More information about `Julia`'s package manager can be found at [`Pkg.jl`](https://julialang.github.io/Pkg.jl/v1/).
+
+To load the package and check the version information, use either [`QuantumToolbox.versioninfo()`](@ref) or [`QuantumToolbox.about()`](@ref), namely
+```julia
+using QuantumToolbox
+QuantumToolbox.versioninfo()
+QuantumToolbox.about()
+```
+
+## Brief Example
 
 We now provide a brief example to demonstrate the similarity between [QuantumToolbox.jl](https://github.com/qutip/QuantumToolbox.jl) and [QuTiP](https://github.com/qutip/qutip).
 
@@ -53,7 +76,7 @@ where ``\hat{\rho}`` is the density matrix, ``\gamma`` is the damping rate, and
 \mathcal{D}[\hat{a}]\hat{\rho} = \hat{a}\hat{\rho}\hat{a}^\dagger - \frac{1}{2}\hat{a}^\dagger\hat{a}\hat{\rho} - \frac{1}{2}\hat{\rho}\hat{a}^\dagger\hat{a}
 ```
 
-We nowm compute the time evolution of the system using the [`mesolve`](@ref) function, starting from the initial state ``\ket{\psi (0)} = \ket{3}``:
+We now compute the time evolution of the system using the [`mesolve`](@ref) function, starting from the initial state ``\ket{\psi (0)} = \ket{3}``:
 
 ```julia
 γ = 0.1 # damping rate
@@ -65,16 +88,20 @@ tlist = range(0, 10, 100) # time list
 c_ops = [sqrt(γ) * a]
 e_ops = [a' * a]
 
-sol = mesolve(H, ψ0, tlist, c_ops, e_ops=e_ops)
+sol = mesolve(H, ψ0, tlist, c_ops, e_ops = e_ops)
 ```
 
 We can extract the expectation value of the number operator ``\hat{a}^\dagger \hat{a}`` with the command `sol.expect`, and the states with the command `sol.states`.
 
-### Passing in the GPU
+### Support for GPU calculation
 
 We can easily pass the computation to the GPU, by simply passing all the `Qobj`s to the GPU:
 
+!!! compat "Compat"
+    The described feature requires `Julia 1.9+`. See [CUDA extension](@ref "doc: CUDA") for more details.
+
 ```julia
+using QuantumToolbox
 using CUDA
 
 a_gpu = cu(destroy(N)) # The only difference in the code is the cu() function
@@ -86,5 +113,5 @@ H_gpu = ω * a_gpu' * a_gpu
 c_ops = [sqrt(γ) * a_gpu]
 e_ops = [a_gpu' * a_gpu]
 
-sol = mesolve(H_gpi, ψ0_gpu, tlist, c_ops, e_ops=e_ops)
-```
+sol = mesolve(H_gpu, ψ0_gpu, tlist, c_ops, e_ops = e_ops)
+```
diff --git a/docs/src/users_guide/states_and_operators/density_matrices.md b/docs/src/users_guide/states_and_operators/density_matrices.md
diff --git a/docs/src/users_guide/states_and_operators/expectation_values.md b/docs/src/users_guide/states_and_operators/expectation_values.md
diff --git a/docs/src/users_guide/states_and_operators/qubit_systems.md b/docs/src/users_guide/states_and_operators/qubit_systems.md
diff --git a/docs/src/users_guide/states_and_operators/state_vectors.md b/docs/src/users_guide/states_and_operators/state_vectors.md
diff --git a/docs/src/users_guide/states_and_operators/states_and_operators.md b/docs/src/users_guide/states_and_operators/states_and_operators.md
@@ -0,0 +1,19 @@
+# [States and Operators](@id doc: States and Operators)
+
+This page is still under construction, please visit [API](@ref doc-API) first.
+
+## Introduction
+
+This page is still under construction, please visit [API](@ref doc-API) first.
+
+## [State Vectors (kets or bras)](@id doc: State vectors)
+
+## [Density matrices](@id doc: Density matrices)
+
+## [Two-level systems (qubits)](@id doc: Two-level systems)
+
+## [Expectation values](@id doc: Expectation values)
+
+## [Superoperators and Vectorized Operators](@id doc: Superoperators and Vectorized Operators)
+
+## [Generating Random States and Operators](@id doc: Generating Random States and Operators)
diff --git a/docs/src/users_guide/states_and_operators/superoperators.md b/docs/src/users_guide/states_and_operators/superoperators.md
diff --git a/docs/src/users_guide/tensor_product/partial_trace.md b/docs/src/users_guide/tensor_product/partial_trace.md