Skip to content

Commit cad8e14

Browse files
authored
updates for documentation (#296)
* fix repo link * modify qutip hyper-link * update bib * update footer and fix toc * fix latex `eqref`
1 parent f220410 commit cad8e14

File tree

10 files changed

+70
-48
lines changed

10 files changed

+70
-48
lines changed

docs/make.jl

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@ makedocs(;
6868
sitename = "QuantumToolbox.jl",
6969
pages = PAGES,
7070
format = DocumenterVitepress.MarkdownVitepress(
71-
repo = "https://qutip.github.io/QuantumToolbox.jl",
71+
repo = "github.com/qutip/QuantumToolbox.jl",
7272
),
7373
draft = DRAFT,
7474
plugins = [bib],

docs/src/.vitepress/config.mts

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -28,6 +28,11 @@ export default defineConfig({
2828

2929
markdown: {
3030
math: true,
31+
32+
// options for @mdit-vue/plugin-toc
33+
// https://github.com/mdit-vue/mdit-vue/tree/main/packages/plugin-toc#options
34+
toc: { level: [1, 2] },
35+
3136
config(md) {
3237
md.use(tabsMarkdownPlugin),
3338
md.use(mathjax3),
@@ -54,8 +59,8 @@ export default defineConfig({
5459
{ icon: 'github', link: 'REPLACE_ME_DOCUMENTER_VITEPRESS' }
5560
],
5661
footer: {
57-
message: 'Made with <a href="https://luxdl.github.io/DocumenterVitepress.jl/dev/" target="_blank"><strong>DocumenterVitepress.jl</strong></a><br>',
58-
copyright: `© Copyright ${new Date().getUTCFullYear()}.`
62+
message: 'Made with <a href="https://documenter.juliadocs.org/stable/" target="_blank"><strong>Documenter.jl</strong></a>, <a href="https://vitepress.dev" target="_blank"><strong>VitePress</strong></a> and <a href="https://luxdl.github.io/DocumenterVitepress.jl/stable" target="_blank"><strong>DocumenterVitepress.jl</strong></a><br>Released under the BSD 3-Clause License. Powered by the <a href="https://www.julialang.org" target="_blank">Julia Programming Language</a>.<br>',
63+
copyright: `© Copyright ${new Date().getUTCFullYear()} <a href="https://qutip.org/" target="_blank"><strong>QuTiP.org</strong></a>.`
5964
}
6065
}
6166
})

docs/src/index.md

Lines changed: 4 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -22,13 +22,12 @@ hero:
2222
- theme: alt
2323
text: API
2424
link: /api
25+
- theme: alt
26+
text: Visit QuTiP.org
27+
link: https://qutip.org/
2528
2629
2730
features:
28-
- icon: <img width="64" height="64" src="https://qutip.org/images/logo.png" alt="markdown"/>
29-
title: QuTiP
30-
details: Easily handle quantum states and operators with a rich set of tools, with the same functionalities as Python QuTiP.
31-
link: https://qutip.org/
3231
- icon: <img width="64" height="64" src="https://docs.sciml.ai/DiffEqDocs/stable/assets/logo.png" alt="markdown"/>
3332
title: Dynamical Evolution
3433
details: Advanced solvers for time evolution of quantum systems, thanks to the powerful DifferentialEquations.jl package.
@@ -61,7 +60,7 @@ using Pkg
6160
Pkg.add("QuantumToolbox")
6261
```
6362
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:
64-
```julia-REPL
63+
```julia-repl
6564
(1.10) pkg> add QuantumToolbox
6665
```
6766
More information about `Julia`'s package manager can be found at [`Pkg.jl`](https://julialang.github.io/Pkg.jl/v1/).

docs/src/resources/api.md

Lines changed: 1 addition & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -4,13 +4,9 @@ CurrentModule = QuantumToolbox
44

55
# [API](@id doc-API)
66

7-
<!-- Disable this first (until we find a way to fix it)
87
**Table of contents**
98

10-
```@contents
11-
Pages = ["api.md"]
12-
```
13-
-->
9+
[[toc]]
1410

1511
## [Quantum object (Qobj) and type](@id doc-API:Quantum-object-and-type)
1612

docs/src/resources/bibliography.bib

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,25 @@
1+
@book{Nielsen-Chuang2011,
2+
Author = {Michael A. Nielsen and Isaac L. Chuang},
3+
Title = {Quantum Computation and Quantum Information: 10th Anniversary Edition},
4+
Publisher = {Cambridge University Press},
5+
Year = {2011},
6+
ISBN = {9781107002173},
7+
URL = {https://www.amazon.com/Quantum-Computation-Information-10th-Anniversary/dp/1107002176?SubscriptionId=AKIAIOBINVZYXZQZ2U3A&tag=chimbori05-20&linkCode=xm2&camp=2025&creative=165953&creativeASIN=1107002176}
8+
}
9+
10+
@article{Jozsa1994,
11+
author = {Richard Jozsa},
12+
title = {Fidelity for Mixed Quantum States},
13+
journal = {Journal of Modern Optics},
14+
volume = {41},
15+
number = {12},
16+
pages = {2315--2323},
17+
year = {1994},
18+
publisher = {Taylor \& Francis},
19+
doi = {10.1080/09500349414552171},
20+
URL = {https://doi.org/10.1080/09500349414552171},
21+
}
22+
123
@article{gravina2024adaptive,
224
title = {{Adaptive variational low-rank dynamics for open quantum systems}},
325
author = {Gravina, Luca and Savona, Vincenzo},

docs/src/users_guide/states_and_operators.md

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@ and then create a lowering operator ``\hat{a}`` corresponding to `5` number stat
2020
a = destroy(5)
2121
```
2222

23-
Now lets apply the lowering operator `\hat{a}` to our vacuum state `vac`:
23+
Now lets apply the lowering operator ``\hat{a}`` to our vacuum state `vac`:
2424

2525
```@example states_and_operators
2626
a * vac
@@ -172,7 +172,7 @@ z = thermal_dm(5, 0.125)
172172
173173
fidelity(x, y)
174174
```
175-
Note that the definition of [`fidelity`](@ref) here is from **Nielsen & Chuang, "Quantum Computation and Quantum Information"**. It is the square root of the fidelity defined in **R. Jozsa, Journal of Modern Optics, 41:12, 2315 (1994)**. We also know that for two pure states, the trace distance (``T``) and the fidelity (``F``) are related by ``T = \sqrt{1-F^2}``:
175+
Note that the definition of [`fidelity`](@ref) here is from [Nielsen-Chuang2011](@cite). It is the square root of the fidelity defined in [Jozsa1994](@cite). We also know that for two pure states, the trace distance (``T``) and the fidelity (``F``) are related by ``T = \sqrt{1-F^2}``:
176176

177177
```@example states_and_operators
178178
tracedist(x, y) ≈ sqrt(1 - (fidelity(x, y))^2)

docs/src/users_guide/time_evolution/intro.md

Lines changed: 17 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,24 @@
11
# [Time Evolution and Quantum System Dynamics](@id doc:Time-Evolution-and-Quantum-System-Dynamics)
22

3-
<!-- Disable this first (until we find a way to fix it)
43
**Table of contents**
54

6-
```@contents
7-
Pages = [
8-
"intro.md",
9-
"solution.md",
10-
"sesolve.md",
11-
"mesolve.md",
12-
"mcsolve.md",
13-
"stochastic.md",
14-
"time_dependent.md",
15-
]
16-
Depth = 1:2
17-
```
18-
-->
5+
- [Introduction](@ref doc-TE:Introduction)
6+
- [Time Evolution Solutions](@ref doc-TE:Time-Evolution-Solutions)
7+
- [Solution](@ref doc-TE:Solution)
8+
- [Multiple trajectories solution](@ref doc-TE:Multiple-trajectories-solution)
9+
- [Accessing data in solutions](@ref doc-TE:Accessing-data-in-solutions)
10+
- [Schrödinger Equation Solver](@ref doc-TE:Schrödinger-Equation-Solver)
11+
- [Unitary evolution](@ref doc-TE:Unitary-evolution)
12+
- [Example: Spin dynamics](@ref doc-TE:Example:Spin-dynamics)
13+
- [Lindblad Master Equation Solver](@ref doc-TE:Lindblad-Master-Equation-Solver)
14+
- [Von Neumann equation](@ref doc-TE:Von-Neumann-equation)
15+
- [The Lindblad master equation](@ref doc-TE:The-Lindblad-master-equation)
16+
- [Example: Dissipative Spin dynamics](@ref doc-TE:Example:Dissipative-Spin-dynamics)
17+
- [Example: Harmonic oscillator in thermal bath](@ref doc-TE:Example:Harmonic-oscillator-in-thermal-bath)
18+
- [Example: Two-level atom coupled to dissipative single-mode cavity](@ref doc-TE:Example:Two-level-atom-coupled-to-dissipative-single-mode-cavity)
19+
- [Monte-Carlo Solver](@ref doc-TE:Monte-Carlo-Solver)
20+
- [Stochastic Solver](@ref doc-TE:Stochastic-Solver)
21+
- [Solving Problems with Time-dependent Hamiltonians](@ref doc-TE:Solving-Problems-with-Time-dependent-Hamiltonians)
1922

2023
# [Introduction](@id doc-TE:Introduction)
2124

docs/src/users_guide/time_evolution/mesolve.md

Lines changed: 11 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@
44
using QuantumToolbox
55
```
66

7-
## Von Neumann equation
7+
## [Von Neumann equation](@id doc-TE:Von-Neumann-equation)
88

99
While the evolution of the state vector in a closed quantum system is deterministic (as we discussed in the previous section: [Schrödinger Equation Solver](@ref doc-TE:Schrödinger-Equation-Solver)), open quantum systems are stochastic in nature. The effect of an environment on the system of interest is to induce stochastic transitions between energy levels, and to introduce uncertainty in the phase difference between states of the system. The state of an open quantum system is therefore described in terms of ensemble averaged states using the density matrix formalism. A density matrix ``\hat{\rho}`` describes a probability distribution of quantum states ``|\psi_n\rangle`` in a matrix representation, namely
1010

@@ -18,7 +18,6 @@ The time evolution of the density matrix ``\hat{\rho}(t)`` under closed system d
1818

1919
```math
2020
\begin{equation}
21-
\label{von-Neumann-Eq}
2221
\frac{d}{dt}\hat{\rho}(t) = -\frac{i}{\hbar}\left[\hat{H}, \hat{\rho}(t)\right],
2322
\end{equation}
2423
```
@@ -62,13 +61,12 @@ sol.expect
6261
sol.states
6362
```
6463

65-
## The Lindblad master equation
64+
## [The Lindblad master equation](@id doc-TE:The-Lindblad-master-equation)
6665

67-
The standard approach for deriving the equations of motion for a system interacting with its environment is to expand the scope of the system to include the environment. The combined quantum system is then closed, and its evolution is governed by the von Neumann equation given in Eq. \eqref{von-Neumann-Eq}
66+
The standard approach for deriving the equations of motion for a system interacting with its environment is to expand the scope of the system to include the environment. The combined quantum system is then closed, and its evolution is also governed by the von Neumann equation
6867

6968
```math
7069
\begin{equation}
71-
\label{tot-von-Neumann-Eq}
7270
\frac{d}{dt}\hat{\rho}_{\textrm{tot}}(t) = -\frac{i}{\hbar}\left[\hat{H}_{\textrm{tot}}, \hat{\rho}_{\textrm{tot}}(t)\right].
7371
\end{equation}
7472
```
@@ -79,27 +77,26 @@ Here, the total Hamiltonian
7977
\hat{H}_{\textrm{tot}} = \hat{H}_{\textrm{sys}} + \hat{H}_{\textrm{env}} + \hat{H}_{\textrm{int}},
8078
```
8179

82-
includes the original system Hamiltonian ``\hat{H}_{\textrm{sys}}``, the Hamiltonian for the environment ``\hat{H}_{\textrm{env}}``, and a term representing the interaction between the system and its environment ``\hat{H}_{\textrm{int}}``. Since we are only interested in the dynamics of the system, we can, perform a partial trace over the environmental degrees of freedom in Eq. \eqref{tot-von-Neumann-Eq}, and thereby obtain a master equation for the motion of the original system density matrix ``\hat{\rho}_{\textrm{sys}}(t)=\textrm{Tr}_{\textrm{env}}[\hat{\rho}_{\textrm{tot}}(t)]``. The most general trace-preserving and completely positive form of this evolution is the Lindblad master equation for the reduced density matrix, namely
80+
includes the original system Hamiltonian ``\hat{H}_{\textrm{sys}}``, the Hamiltonian for the environment ``\hat{H}_{\textrm{env}}``, and a term representing the interaction between the system and its environment ``\hat{H}_{\textrm{int}}``. Since we are only interested in the dynamics of the system, we can, perform a partial trace over the environmental degrees of freedom, and thereby obtain a master equation for the motion of the original system density matrix ``\hat{\rho}_{\textrm{sys}}(t)=\textrm{Tr}_{\textrm{env}}[\hat{\rho}_{\textrm{tot}}(t)]``. The most general trace-preserving and completely positive form of this evolution is the Lindblad master equation for the reduced density matrix, namely
8381

8482
```math
8583
\begin{equation}
86-
\label{Lindblad-master-Eq}
8784
\frac{d}{dt}\hat{\rho}_{\textrm{sys}}(t) = -\frac{i}{\hbar}\left[\hat{H}_{\textrm{sys}}, \hat{\rho}_{\textrm{sys}}(t)\right] + \sum_n \hat{C}_n \hat{\rho}_{\textrm{sys}}(t) \hat{C}_n^\dagger - \frac{1}{2} \hat{C}_n^\dagger \hat{C}_n \hat{\rho}_{\textrm{sys}}(t) - \frac{1}{2} \hat{\rho}_{\textrm{sys}}(t) \hat{C}_n^\dagger \hat{C}_n
8885
\end{equation}
8986
```
9087

91-
where ``\hat{C}_n \equiv \sqrt{\gamma_n}\hat{A}_n`` are the collapse operators, ``\hat{A}_n`` are the operators acting on the system in ``\hat{H}_{\textrm{int}}`` which describes the system-environment interaction, and ``\gamma_n`` are the corresponding rates. The derivation of Eq. \eqref{Lindblad-master-Eq} may be found in several sources, and will not be reproduced here. Instead, we emphasize the approximations that are required to arrive at the master equation in the form of Eq. \eqref{Lindblad-master-Eq} from physical arguments, and hence perform a calculation in `QuantumToolbox`:
88+
where ``\hat{C}_n \equiv \sqrt{\gamma_n}\hat{A}_n`` are the collapse operators, ``\hat{A}_n`` are the operators acting on the system in ``\hat{H}_{\textrm{int}}`` which describes the system-environment interaction, and ``\gamma_n`` are the corresponding rates. The derivation of Lindblad master equation may be found in several sources, and will not be reproduced here. Instead, we emphasize the approximations that are required to arrive at the above Lindblad master equation from physical arguments, and hence perform a calculation in `QuantumToolbox`:
9289

9390
- **Separability:** At ``t = 0``, there are no correlations between the system and environment, such that the total density matrix can be written as a tensor product, namely ``\hat{\rho}_{\textrm{tot}}(0)=\hat{\rho}_{\textrm{sys}}(0)\otimes\hat{\rho}_{\textrm{env}}(0)``.
9491
- **Born approximation:** Requires: (i) the state of the environment does not significantly change as a result of the interaction with the system; (ii) the system and the environment remain separable throughout the evolution. These assumptions are justified if the interaction is weak, and if the environment is much larger than the system. In summary, ``\hat{\rho}_{\textrm{tot}}(t)\approx\hat{\rho}_{\textrm{sys}}(t)\otimes\hat{\rho}_{\textrm{env}}(0)``.
9592
- **Markov approximation:** The time-scale of decay for the environment ``\tau_{\textrm{env}}`` is much shorter than the smallest time-scale of the system dynamics, i.e., ``\tau_{\textrm{sys}}\gg\tau_{\textrm{env}}``. This approximation is often deemed a “short-memory environment” as it requires the environmental correlation functions decay in a fast time-scale compared to those of the system.
96-
- **Secular approximation:** Stipulates that elements in the master equation corresponding to transition frequencies satisfy ``|\omega_{ab}-\omega_{cd}| \ll 1/\tau_{\textrm{sys}}``, i.e., all fast rotating terms in the interaction picture can be neglected. It also ignores terms that lead to a small renormalization of the system energy levels. This approximation is not strictly necessary for all master-equation formalisms (e.g., the Block-Redfield master equation), but it is required for arriving at the Lindblad form in Eq. \eqref{Lindblad-master-Eq} which is used in [`mesolve`](@ref).
93+
- **Secular approximation:** Stipulates that elements in the master equation corresponding to transition frequencies satisfy ``|\omega_{ab}-\omega_{cd}| \ll 1/\tau_{\textrm{sys}}``, i.e., all fast rotating terms in the interaction picture can be neglected. It also ignores terms that lead to a small renormalization of the system energy levels. This approximation is not strictly necessary for all master-equation formalisms (e.g., the Block-Redfield master equation), but it is required for arriving at the Lindblad form in the above equation which is used in [`mesolve`](@ref).
9794

98-
For systems with environments satisfying the conditions outlined above, the Lindblad master equation in Eq. \eqref{Lindblad-master-Eq} governs the time-evolution of the system density matrix, giving an ensemble average of the system dynamics. In order to ensure that these approximations are not violated, it is important that the decay rates ``\gamma_n`` be smaller than the minimum energy splitting in the system Hamiltonian. Situations that demand special attention therefore include, for example, systems strongly coupled to their environment, and systems with degenerate or nearly degenerate energy levels.
95+
For systems with environments satisfying the conditions outlined above, the Lindblad master equation governs the time-evolution of the system density matrix, giving an ensemble average of the system dynamics. In order to ensure that these approximations are not violated, it is important that the decay rates ``\gamma_n`` be smaller than the minimum energy splitting in the system Hamiltonian. Situations that demand special attention therefore include, for example, systems strongly coupled to their environment, and systems with degenerate or nearly degenerate energy levels.
9996

10097
What is new in the master equation compared to the Schrödinger equation (or von Neumann equation) are processes that describe dissipation in the quantum system due to its interaction with an environment. For example, evolution that includes incoherent processes such as relaxation and dephasing. These environmental interactions are defined by the operators ``\hat{A}_n`` through which the system couples to the environment, and rates ``\gamma_n`` that describe the strength of the processes.
10198

102-
In `QuantumToolbox`, the function [`mesolve`](@ref) can also be used for solving the master equation. This is done by passing a list of collapse operators (`c_ops`) as the fourth argument of the [`mesolve`](@ref) function in order to define the dissipation processes of the master equation in Eq. \eqref{Lindblad-master-Eq}. As we mentioned above, each collapse operator ``\hat{C}_n`` is the product of ``\sqrt{\gamma_n}`` (the square root of the rate) and ``\hat{A}_n`` (operator which describes the dissipation process).
99+
In `QuantumToolbox`, the function [`mesolve`](@ref) can also be used for solving the master equation. This is done by passing a list of collapse operators (`c_ops`) as the fourth argument of the [`mesolve`](@ref) function in order to define the dissipation processes of the Lindblad master equation. As we mentioned above, each collapse operator ``\hat{C}_n`` is the product of ``\sqrt{\gamma_n}`` (the square root of the rate) and ``\hat{A}_n`` (operator which describes the dissipation process).
103100

104101
Furthermore, `QuantumToolbox` solves the master equation in the [`SuperOperator`](@ref) formalism. That is, a Liouvillian [`SuperOperator`](@ref) will be generated internally in [`mesolve`](@ref) by the input system Hamiltonian ``\hat{H}_{\textrm{sys}}`` and the collapse operators ``\hat{C}_n``. One can also generate the Liouvillian [`SuperOperator`](@ref) manually for special purposes, and pass it as the first argument of the [`mesolve`](@ref) function. To do so, it is useful to read the section [Superoperators and Vectorized Operators](@ref doc:Superoperators-and-Vectorized-Operators), and also the docstrings of the following functions:
105102
- [`spre`](@ref)
@@ -108,7 +105,7 @@ Furthermore, `QuantumToolbox` solves the master equation in the [`SuperOperator`
108105
- [`liouvillian`](@ref)
109106
- [`lindblad_dissipator`](@ref)
110107

111-
## Example: Spin dynamics
108+
## [Example: Dissipative Spin dynamics](@id doc-TE:Example:Dissipative-Spin-dynamics)
112109

113110
Using the example with the dynamics of spin-``\frac{1}{2}`` from the previous section ([Schrödinger Equation Solver](@ref doc-TE:Schrödinger-Equation-Solver)), we can easily add a relaxation process (describing the dissipation of energy from the spin to the environment), by adding `[sqrt(γ) * sigmax()]` in the fourth parameter of the [`mesolve`](@ref) function.
114111

@@ -143,7 +140,7 @@ axislegend(ax, position = :rt)
143140
fig
144141
```
145142

146-
## Example: Harmonic oscillator in thermal bath
143+
## [Example: Harmonic oscillator in thermal bath](@id doc-TE:Example:Harmonic-oscillator-in-thermal-bath)
147144

148145
Consider a harmonic oscillator (single-mode cavity) couples to a thermal bath. If the single-mode cavity initially is in a `10`-photon [`fock`](@ref) state, the dynamics is calculated with the following code:
149146

@@ -181,7 +178,7 @@ lines!(ax, tlist, Num)
181178
fig
182179
```
183180

184-
## Example: Two-level atom coupled to dissipative single-mode cavity
181+
## [Example: Two-level atom coupled to dissipative single-mode cavity](@id doc-TE:Example:Two-level-atom-coupled-to-dissipative-single-mode-cavity)
185182

186183
Consider a two-level atom coupled to a dissipative single-mode cavity through a dipole-type interaction, which supports a coherent exchange of quanta between the two systems. If the atom initially is in its ground state and the cavity in a `5`-photon [`fock`](@ref) state, the dynamics is calculated with the following code:
187184

0 commit comments

Comments
 (0)