add docs time_ev_v1

docs/Project.toml

@@ -1,4 +1,5 @@
 [deps]
 CairoMakie = "13f3f980-e62b-5c42-98c6-ff1f3baf88f0"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
+DocumenterCitations = "daee34ce-89f3-4625-b898-19384cb65244"
 QuantumToolbox = "6c2fb7c5-b903-41d2-bc5e-5a7c320b9fab"

docs/make.jl

@@ -3,6 +3,7 @@
 
 using QuantumToolbox
 using Documenter
+using DocumenterCitations
 
 DocMeta.setdocmeta!(QuantumToolbox, :DocTestSetup, :(using QuantumToolbox); recursive = true)
 
@@ -31,7 +32,7 @@ const PAGES = [
         "Manipulating States and Operators" => "users_guide/states_and_operators.md",
         "Tensor Products and Partial Traces" => "users_guide/tensor.md",
         "Time Evolution and Dynamics" => [
-            "Introduction" => "users_guide/time_evolution/intro.md",
+            # "Introduction" => "users_guide/time_evolution/intro.md",
         ],
         "Solving for Steady-State Solutions" => [],
         "Symmetries" => [],
@@ -52,12 +53,15 @@ const PAGES = [
     # "Change Log" => "changelog.md",
 ]
 
+bib = CitationBibliography(joinpath(@__DIR__, "src", "refs.bib"))
+
 makedocs(;
     modules = [QuantumToolbox],
     authors = "Alberto Mercurio, Luca Gravina and Yi-Te Huang",
     repo = Remotes.GitHub("qutip", "QuantumToolbox.jl"),
     sitename = "QuantumToolbox.jl",
     pages = PAGES,
+    plugins=[bib],
     format = Documenter.HTML(;
         prettyurls = get(ENV, "CI", "false") == "true",
         canonical = "https://qutip.github.io/QuantumToolbox.jl",

docs/src/bibliography.md

@@ -0,0 +1,3 @@
+# References
+
+@bibliography

docs/src/refs.bib

@@ -0,0 +1,117 @@
+@article{Sinibaldi2023,
+  title = {Unbiasing time-dependent Variational Monte Carlo by projected quantum evolution},
+  volume = {7},
+  ISSN = {2521-327X},
+  url = {http://dx.doi.org/10.22331/q-2023-10-10-1131},
+  DOI = {10.22331/q-2023-10-10-1131},
+  journal = {Quantum},
+  publisher = {Verein zur Forderung des Open Access Publizierens in den Quantenwissenschaften},
+  author = {Sinibaldi,  Alessandro and Giuliani,  Clemens and Carleo,  Giuseppe and Vicentini,  Filippo},
+  year = {2023},
+  month = oct,
+  pages = {1131}
+}
+
+@article{Donatella2023,
+  title = {Dynamics with autoregressive neural quantum states: Application to critical quench dynamics},
+  author = {Donatella, Kaelan and Denis, Zakari and Le Boit\'e, Alexandre and Ciuti, Cristiano},
+  journal = {Phys. Rev. A},
+  volume = {108},
+  issue = {2},
+  pages = {022210},
+  numpages = {11},
+  year = {2023},
+  month = {Aug},
+  publisher = {American Physical Society},
+  doi = {10.1103/PhysRevA.108.022210},
+  url = {https://link.aps.org/doi/10.1103/PhysRevA.108.022210}
+}
+
+@misc{Lange2024,
+  doi = {10.48550/ARXIV.2402.09402},
+  url = {https://arxiv.org/abs/2402.09402},
+  author = {Lange,  Hannah and Van de Walle,  Anka and Abedinnia,  Atiye and Bohrdt,  Annabelle},
+  keywords = {Disordered Systems and Neural Networks (cond-mat.dis-nn),  Quantum Gases (cond-mat.quant-gas),  Strongly Correlated Electrons (cond-mat.str-el),  Quantum Physics (quant-ph),  FOS: Physical sciences,  FOS: Physical sciences},
+  title = {From Architectures to Applications: A Review of Neural Quantum States},
+  publisher = {arXiv},
+  year = {2024},
+  copyright = {arXiv.org perpetual,  non-exclusive license}
+}
+
+@article{Yuan2019,
+  title = {Theory of variational quantum simulation},
+  volume = {3},
+  ISSN = {2521-327X},
+  url = {http://dx.doi.org/10.22331/q-2019-10-07-191},
+  DOI = {10.22331/q-2019-10-07-191},
+  journal = {Quantum},
+  publisher = {Verein zur Forderung des Open Access Publizierens in den Quantenwissenschaften},
+  author = {Yuan,  Xiao and Endo,  Suguru and Zhao,  Qi and Li,  Ying and Benjamin,  Simon C.},
+  year = {2019},
+  month = oct,
+  pages = {191}
+}
+
+@article{Gutirrez2022,
+  title = {Real time evolution with neural-network quantum states},
+  volume = {6},
+  ISSN = {2521-327X},
+  url = {http://dx.doi.org/10.22331/q-2022-01-20-627},
+  DOI = {10.22331/q-2022-01-20-627},
+  journal = {Quantum},
+  publisher = {Verein zur Forderung des Open Access Publizierens in den Quantenwissenschaften},
+  author = {Gutiérrez,  Irene López and Mendl,  Christian B.},
+  year = {2022},
+  month = jan,
+  pages = {627}
+}
+
+@misc{Poletti2024,
+  doi = {10.48550/ARXIV.2406.03381},
+  url = {https://arxiv.org/abs/2406.03381},
+  author = {Zhang,  Wenxuan and Xing,  Bo and Xu,  Xiansong and Poletti,  Dario},
+  keywords = {Quantum Physics (quant-ph),  Disordered Systems and Neural Networks (cond-mat.dis-nn),  Quantum Gases (cond-mat.quant-gas),  Statistical Mechanics (cond-mat.stat-mech),  FOS: Physical sciences,  FOS: Physical sciences},
+  title = {Paths towards time evolution with larger neural-network quantum states},
+  publisher = {arXiv},
+  year = {2024},
+  copyright = {arXiv.org perpetual,  non-exclusive license}
+}
+
+
+
+@article{Havlicek2023,
+  title = {Amplitude Ratios and Neural Network Quantum States},
+  volume = {7},
+  ISSN = {2521-327X},
+  url = {http://dx.doi.org/10.22331/q-2023-03-02-938},
+  DOI = {10.22331/q-2023-03-02-938},
+  journal = {Quantum},
+  publisher = {Verein zur Forderung des Open Access Publizierens in den Quantenwissenschaften},
+  author = {Havlicek,  Vojtech},
+  year = {2023},
+  month = mar,
+  pages = {938}
+}
+
+@article{Medvidovi2021,
+  title = {Classical variational simulation of the Quantum Approximate Optimization Algorithm},
+  volume = {7},
+  ISSN = {2056-6387},
+  url = {http://dx.doi.org/10.1038/s41534-021-00440-z},
+  DOI = {10.1038/s41534-021-00440-z},
+  number = {1},
+  journal = {npj Quantum Information},
+  publisher = {Springer Science and Business Media LLC},
+  author = {Medvidović,  Matija and Carleo,  Giuseppe},
+  year = {2021},
+  month = jun 
+}
+
+@book{stanley1999,
+  title={Enumerative Combinatorics, Volume 2},
+  author={Stanley, Richard P.},
+  volume={2},
+  year={1999},
+  publisher={Cambridge University Press},
+  series={Cambridge Studies in Advanced Mathematics},
+}

docs/src/users_guide/time_evolution/intro.md

@@ -1,3 +1,41 @@
-# [Time Evolution and Quantum System Dynamics](@id doc:Time-Evolution-and-Quantum-System-Dynamics)
+# [Quantum System Dynamics](@id doc:Quantum-System-Dynamics)
 
-This page is still under construction, please visit [API](@ref doc-API) first.
+The time evolution of quantum systems lies at the heart of understanding and predicting the behavior of physical phenomena at the quantum level. Whether in theoretical research or practical applications such as quantum computing, quantum chemistry, and quantum optics, simulating the dynamics of quantum states is a fundamental task. 
+
+Quantum systems can broadly be classified into two types: closed systems and open systems. 
+
+- **Closed systems** are isolated from their environment and do not exchange energy or information with it. The dynamics of closed systems are unitary and reversible. The time evolution of a closed quantum system is governed by the Schrödinger equation.
+
+- **Open systems** interact with their environment and exchange energy and information with it. The dynamics of open systems are non-unitary and irreversible. While the average dynamics of an open quantum system is described by the Lindblad master equation, a more complete description is provided by quantum trajectory approach whereby system follows a deterministic evolution conditioned on the measurement outcomes of the environment. 
+
+The following table lists of the solvers QuantumToolbox.jl provides for dynamic quantum systems and indicates the type of solver that is returned by each function:
+
+| Solver | Problem | Description | Return Type |
+| --- | --- | --- | --- |
+| [`sesolve`](@ref) | [`sesolveProblem`](@ref) | Schrödinger equation solver | [`TimeEvolutionSol`](@ref) |
+| [`mesolve`](@ref) | [`mesolveProblem`](@ref) | Master equation solver | [`TimeEvolutionSol`](@ref) |
+| [`lr_mesolve`](@ref) | [`lr_mesolveProblem`](@ref) | Low-rank master equation solver | [`LRTimeEvolutionSol`](@ref) |
+| [`mcsolve`](@ref) | [`mcsolveProblem`](@ref) | Monte Carlo wave function solver | [`TimeEvolutionMCSol`](@ref) |
+| [`ssesolve`](@ref) | [`ssesolveProblem`](@ref) | Stochastic Schrödinger equation solver | [`TimeEvolutionSSESol`](@ref) |
+
+
+
+
+The following sections provide an overview of the different solvers and how to use them to simulate the time evolution of quantum systems. 
+
+## Main differences from QuTiP
+
+QuTip is a widely used Python library and offers grat flexibility for simulating the dynamics of quantum systems. QuantumToolbox.jl is inspired by QuTiP and aims to provide similar functionalities in Julia with close-to identical syntax. However, there are some key differences between the two libraries:
+
+- **Performance**: QuantumToolbox.jl is built on top of the Julia programming language, which is known for its high performance and efficiency. QuantumToolbox.jl leverages Julia's just-in-time (JIT) compilation and parallel computing capabilities to vastly outperform QuTip in terms of speed and scalability. We refer to the [Performance](@ref) section for a detailed comparison of the performance of QuantumToolbox.jl and QuTip.
+
+- **DifferentialEquations.jl**: QuantumToolbox.jl is based on DifferentialEquations.jl: a state of the art library for solving ordinary, partial, and stochastic differential equations. This library is the most efficient and flexible library for solving these problems constituting the backbone of most solvers in Julia and Python alike. The seamless integration with DifferentialEquations.jl allows QuantumToolbox.jl to take advantage of the latest advancements in numerical methods and scientific computing.
+
+- **GPU Support**: QuantumToolbox.jl provides built-in support for GPU acceleration, allowing users to take advantage of the computational power of GPUs for simulating quantum systems.
+
+- **Distributed Computing**: QuantumToolbox.jl supports distributed computing, enabling users with to distribute large scale problems across multiple processors or nodes for parallel execution. The structure of the solvers in QuantumToolbox.jl is designed around this feature, as discussed in the [Parallel Computing](@ref) section.
+
+- **Callbacks**: QuantumToolbox.jl allows users to define custom callbacks that are triggered during the simulation, providing flexibility in monitoring and controlling the simulation. We encourage users to use a prefixed callback structure via the `f_ops` argument in the solvers to compute complex functions of the evolving state while avoiding the need to store the full state vector at all desired times. We refer to the [Callbacks](@ref) section for more details.
+
+- **Additional Methods**: QuantumToolbox.jl provides additional methods and functionalities for the investigation of closed and open quantum systems. 
+A few examples are: the low-rank solver [`lr_mesolve`](@ref) for the dynamics of low-entropy open quantum systems, the Arnoldi-Lindblad method [`eigsolve_al`](@ref) for faster-than-the-clock estimation of the spectrum of time-independent and Floquet open quantum systems, the breath-first seach algorithm [`bdf`](@ref) for the block-diagonalization of aribitrary Hamiltonians/Liouvillians with unknown symmetries, and the U(1) symmetric Monte-Carlo solver [`mcsolve`](@ref).

docs/src/users_guide/time_evolution/mesolve.md

@@ -0,0 +1,3 @@
+
+
+## Low rank approximation

docs/src/users_guide/time_evolution/sesolve.md

@@ -0,0 +1,22 @@
+# Unitary dynamics
+
+The evolution of a closed quantum system is governed by the Schrödinger equation
+```math
+i \frac{d}{dt} \left| \psi(t) \right\rangle = \hat{H} \left| \psi(t) \right\rangle,
+```
+where $\hat{H}$ is the Hamiltonian of the system, and $\left| \psi(t) \right\rangle$ is the state vector. 
+Numerically, $\left| \psi(t) \right\rangle$ is represented as a column vector of size $N\times 1$, while $\hat{H}$ as a matrix of size $N\times N$. $N$ is the dimension of the Hilbert space scaling exponentially with the number of degrees of freedom in the system (e.g., the number of qubits in a quantum circuit). 
+ The formal solution to the Schrödinger equation is given by
+```math 
+|\psi(t)\rangle = e^{-i\hat{H}t}|\psi(0)\rangle.
+```
+The Hermiticity of $\hat{H}$, makes the evolution operation unitary and the dynamics reversible. The norm of the state vector, as well as the expectation value of $\hat{H}$ are preserved under unitary evolution.
+
+Analytic solutions to the Schrödinger equation are rare and limited to very small systems making numerical methods the only practical approach for larger systems. A direct approach is to directly compute the matrix exponential of $\hat{H}$. This scales as $O(N^3)$, similar to matrix diagonalization, making it impractical for large systems. In contrast, matrix-vector multiplication scales as $O(N^2)$.
+Integration schemes for the Schrödinger equation involve solving the equation directly using matrix-vector products with adaptive time steps and error control. The Euler method is a simple example of a numerical integration scheme that approximates the time evolution over an infinitesimal time step $\Delta t$ as
+```math
+|\psi(t+\Delta t)\rangle = (1-i\hat{H}\Delta t)|\psi(t)\rangle
+```
+More sophisticated schemes like Runge-Kutta or Crank-Nicolson methods are often used in practice to achieve better accuracy and stability.
+
+QuantumToolbox.jl provides the `sesolve` function to simulate the unitary dynamics of a quantum system. The function takes a `sesolveProblem` object as input and returns a `TimeEvolutionSol` object that contains the solution to the Schrödinger equation. The following example demonstrates how to use the `sesolve` function to simulate the time evolution of a simple quantum system.