Improvement of documentation.

* More explanation for arguments of MCWF.
* Fix mistakes found by Valo.

docs/source/_templates/layout.html

@@ -0,0 +1,4 @@
+{% extends "!layout.html" %}
+{% block extrabody %}
+
+{% endblock %}

docs/source/conf.py

@@ -59,9 +59,9 @@
 # built documents.
 #
 # The short X.Y version.
-version = '0.2'
+version = '0.3'
 # The full version, including alpha/beta/rc tags.
-release = '0.2'
+release = '0.3'
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/source/documentation/quantumobjects/states.rst

@@ -13,7 +13,7 @@ and the conjugate equation
 
 .. math::
 
-    \langle\Psi| = \sum_i \psi_i^* \langle u_i|
+    \langle\psi| = \sum_i \psi_i^* \langle u_i|.
 
 The distinction between coefficients in respect to bra or ket states is strictly enforced which guarantees that algebraic mistakes raise an explicit error::
 

docs/source/documentation/quantumsystems/nlevel.rst

@@ -10,7 +10,7 @@ N-Level system
     psi2 = nlevelstate(b, 2)
     psi1 = transition(b, 1, 2)
 
-N-Level systems are mostly used as idealized model when the relevant physics can be captured in a small subspace of the complete Hilbert space. For example an atom often can be represented by a few relevant levels.
+N-Level systems are mostly used as idealized model when the relevant physics can be captured in a small subspace of the complete Hilbert space. For example an atom can often be represented by a few relevant levels.
 
 For these kinds of systems the :jl:type:`NLevelBasis` can be used. Essentially it is defined just as::
 

docs/source/documentation/steadystate.rst

@@ -3,7 +3,7 @@
 Steady state
 ============
 
-**QuantumOptics.jl** implements two different ways to calculate steady states. The first one is to perform a time evolution according to a master equation until a adequate accuracy is reached:
+**QuantumOptics.jl** implements two different ways to calculate steady states. The first one is to perform a time evolution according to a master equation until an adequate accuracy is reached:
 
 .. epigraph::
 

docs/source/documentation/timeevolution/mcwf.rst

@@ -54,15 +54,19 @@ avoiding explicit calculations of density matrices.
 
 The function computing a time evolution with the MCWF method can be called analogously to :jl:func:`master`, namely with::
 
-  mcwf(tspan, psi0::Ket, H::Operator, J::Vector)
+    tout, psit = mcwf(tspan, psi0::Ket, H::Operator, J::Vector)
 
-Since this function only calculates state vectors (as explained above), it requires the initial state in the form of a ket.
+Since this function only calculates state vectors (as explained above), it requires the initial state in the form of a ket. Without any additional keyword arguments the :jl:func:`mcwf` function returns two vectors, the first contains the times identical to tspan and the second the state of the system at these points of time. However, finer control of the output is possible by using the keyword arguments ``display_beforeevent`` and ``display_afterevent``. If they are set to **true** the state of the system immediately before and after a jump is added to these vectors. To avoid keeping all the states in memory when only certain expectation values are needed, one can optionally pass a function ``fout(t, psi)`` which is called at every specified point of time::
 
-As shown above, the concept of the MCWF method requires jumps of the form :math:`J_i|\psi\rangle` to be applied at certain times. Therefore, it is not possible
-to calculate the time evolution according to a MCWF for Lindblad terms of the form :math:`\sum_{i,j}\gamma_{ij}\left(J_i\rho J_j^\dagger - J_i^\dagger J_j\rho/2 - \rho J_i^\dagger J_j/2\right)`,
-since such a Lindblad term relies on the the multiplication of two different jump operators :math:`J_i` and :math:`J_j` from the left and right, respectively, with the density matrix :math:`\rho`.
-However, it is possible to write such a Lindblad term in diagonal form :math:`\sum_i d_i \left(D_i\rho D_i^\dagger - D_i^\dagger D_i\rho - \rho D_i^\dagger D_i\right)`.
-Here, :math:`d_i` are the eigenvalues of the matrix with entries :math:`\gamma_{ij}` and the diagonal jump operators :math:`D_i` are defined by
+    exp_a = []
+    function fout(t, psi)
+      push!(exp_a, expect(a, psi)/norm(psi))
+    end
+    mcwf(tspan, psi0::Ket, H::Operator, J::Vector; tout=tout)
+
+Note, that the given state is not normalized and is still in use by the ode solver. Therefore it should not be changed and if one wants to store the state at a certain point of time it has to be copied explicitly.
+
+As shown above, the concept of the MCWF method requires jumps of the form :math:`J_i|\psi\rangle` to be applied at certain times. Therefore, it is not possible to calculate the time evolution according to a MCWF for Lindblad terms of the form :math:`\sum_{i,j}\gamma_{ij}\left(J_i\rho J_j^\dagger - J_i^\dagger J_j\rho/2 - \rho J_i^\dagger J_j/2\right)`, since such a Lindblad term relies on the the multiplication of two different jump operators :math:`J_i` and :math:`J_j` from the left and right, respectively, with the density matrix :math:`\rho`. However, it is possible to write such a Lindblad term in diagonal form :math:`\sum_i d_i \left(D_i\rho D_i^\dagger - D_i^\dagger D_i\rho - \rho D_i^\dagger D_i\right)`. Here, :math:`d_i` are the eigenvalues of the matrix with entries :math:`\gamma_{ij}` and the diagonal jump operators :math:`D_i` are defined by
 
 .. math::
 
@@ -74,9 +78,7 @@ This diagonalization is implemented with the function
 
 * :func:`diagonaljumps(Gamma::Array{Float64}, J::Vector)`
 
-which returns the eigenvalues (new decay rates) and the corresponding set of jump operators.
-As a quick example, say you have three spin-1/2 particles that decay collectively. When using the master equation solver you can simply pass the matrix containing the collective decay rates
-as a keyword argument. To do the same with the MCWF we need to do::
+which returns the eigenvalues (new decay rates) and the corresponding set of jump operators. As a quick example, say you have three spin-1/2 particles that decay collectively. When using the master equation solver you can simply pass the matrix containing the collective decay rates as a keyword argument. To do the same with the MCWF we need to do::
 
   spinbasis = SpinBasis(1//2)
   threespinbasis = spinbasis ⊗ spinbasis ⊗ spinbasis
@@ -93,6 +95,7 @@ Now, we can call the solver with the acquired jump operators ``D`` multiplied by
   tout, ψₜ = timeevolution.mcwf(tspan, ψ₀, H, [sqrt(d[i])*D[i] for i=1:3])
 
 
+
 Examples
 --------
 

docs/source/introduction.rst

@@ -7,8 +7,8 @@ Introduction
 
 One of the core concepts of **QuantumOptics.jl** is that all quantum objects, i.e. state vectors and operators have knowledge about which Hilbert space they live in. This prevents many common mistakes when working with composite systems and at the same time improves readability. The Hilbert spaces are defined implicitly by specifying appropriate bases like :ref:`fock <section-fock>` bases and :ref:`spin <section-spin>` bases. These bases can in turn be combined to describe composite systems like e.g. a particle in a cavity or a multi-spin system. The different kinds of bases implemented are introduced in the :ref:`Quantum systems <section-quantumsystems>` section.
 
-After choosing a basis **QuantumOptics.jl** provides many useful functions to create common :ref:`section-operators` and :ref:`section-states` which can be combined in all the expected ways. Consequently, constructing arbitrary Hamiltonians and Liouvillians and specifying initial states is straight forward. These objects can be used to perform time evolutions according to :ref:`Schroedinger <section-schroedinger>`, :ref:`Master <section-master>` and :ref:`Monte Carlo wave function <section-mcwf>` equations.
+After choosing a basis **QuantumOptics.jl** provides many useful functions to create common :ref:`section-operators` and :ref:`section-states` which can be combined in all the expected ways. Consequently, constructing arbitrary Hamiltonians and Liouvillians and specifying initial states is straightforward. These objects can be used to perform time evolutions according to :ref:`Schroedinger <section-schroedinger>`, :ref:`Master <section-master>` and :ref:`Monte Carlo wave function <section-mcwf>` equations.
 
-Although the main focus is on simulating dynamics of (open) quantum systems, there are nevertheless many additional features available to calculate :ref:`steadystates <section-steadystate>`, the :ref:`energy spectrum, eigenstates <section-spectralanalysis>`, and :ref:`correlation functions <section-correlationfunctions>`.
+Although the main focus is on simulating dynamics of (open) quantum systems, there are nevertheless many additional features available to calculate :ref:`steady states <section-steadystate>`, the :ref:`energy spectrum, eigenstates <section-spectralanalysis>`, and :ref:`correlation functions <section-correlationfunctions>`.
 
 For a quick introduction it is probably best to start reading the :ref:`tutorial`. It shows a typical approach to study a quantum system and provides links to the :ref:`documentation` and to the :ref:`examples` which give a more detailed explanation.

docs/source/tutorial/tutorial.rst

@@ -3,7 +3,7 @@
 Tutorial
 ========
 
-In this tutorial we will step through the common tasks necessary to simulate a quantum system. At each step links to the corresponding documentation and to similar examples, that explain the topic at hand in more detail, will be provided.
+In this tutorial we will step through the common tasks necessary to simulate a quantum system. At each step links to the corresponding documentation and to similar examples explaining the topic at hand in more detail, will be provided.
 
 In order to use the **QuantumOptics.jl** library it has to be loaded into the current workspace.