Docs additions (#12)

* Docs additions

* Formatter

---------

Co-authored-by: lkdvos <[email protected]>

docs/src/man/operators.md

@@ -14,11 +14,13 @@ The special keyword argument `side` can be used for operators that require an ad
 
 ## Spin operators
 
-The spin operators `S_x`, `S_y` and `S_z` are defined such that they obey the spin commutation relations ``[Sⱼ, Sₖ] = i ɛⱼₖₗ Sₗ``.
-Additionally, the ladder operators are defined as ``S± = Sˣ ± i Sʸ``.
+The spin operators `S_x`, `S_y` and `S_z` are defined such that they obey the spin commutation relations ``[S^j, S^k] = i \varepsilon_{jkl} S^l``.
+Additionally, the ladder operators are defined as ``S^{\pm} = S^x \pm i S^y``.
 Several combinations are defined that act on two spins.
 
-When imposing symmetries, by convention we choose `S_z` as the diagonal operator for U₁, and `S_x` as the diagonal operator for ℤ₂.
+Supported values of `symmetry` for spin operators are `Trivial`, `Z2Irrep` and `U1Irrep`. 
+When imposing symmetries, by convention we choose `S_z` as the diagonal operator for
+``\mathrm{U}(1)``, and `S_x` as the diagonal operator for ``\mathbb{Z}_2``.
 
 ```@docs
 S_x
@@ -52,21 +54,23 @@ For convenience, the Pauli matrices can also be recovered as ``σⁱ = 2 Sⁱ``.
 
 ## Bosonic operators
 
-The bosonic creation and annihilation operators `a_plus` ($$a^\dagger$$) and `a_min` ($$a$$) are defined such that the following holds:
+The bosonic creation and annihilation operators `a_plus` ($$a^+$$) and `a_min` ($$a^-$$) are defined such that the following holds:
 
-$$a^\dagger \left|n\right> = \sqrt(n + 1) \left|n+1\right>$$
-$$a \left|n\right> = \sqrt(n) \left|n-1\right>$$
+$$a^+ \left|n\right> = \sqrt{n + 1} \left|n+1\right>$$
+$$a^- \left|n\right> = \sqrt{n} \left|n-1\right>$$
 
-From these, a number operator ``a_number`` ($$N$$) can be defined:
+From these, a number operator `a_number` ($$N$$) can be defined:
 
-$$N = a^\dagger a$$
+$$N = a^+ a^-$$
 $$N\left|n\right> = n \left|n\right>$$
 
 With these, the following commutators can be obtained:
 
-$$\left[a, a^\dagger\right] = 1$$
-$$\left[N,a^\dagger\right] = a^\dagger$$
-$$\left[N,a\right] = -a$$
+$$\left[a^-, a^+\right] = 1$$
+$$\left[N, a^+\right] = a^+$$
+$$\left[N, a^-\right] = -a^-$$
+
+Supported values of `symmetry` for bosonic operators are `Trivial` and `U1Irrep`.
 
 ```@docs
 a_plus
@@ -76,10 +80,17 @@ a_number
 
 ## Fermionic operators
 
+Spinless fermions.
+
 ```@docs
 c_plus
 c_min
 c_number
+```
+
+Spinful fermions.
+
+```@docs
 e_plus
 e_min
 e_number

src/MPSKitModels.jl

@@ -23,6 +23,7 @@ export spinmatrices, nonsym_spintensors, nonsym_bosonictensors
 
 export S_x, S_y, S_z, S_plus, S_min
 export S_xx, S_yy, S_zz, S_plusmin, S_minplus, S_exchange
+export Sˣ, Sʸ, Sᶻ, S⁺, S⁻, Sˣˣ, Sʸʸ, Sᶻᶻ, S⁺⁻, S⁻⁺, SS
 export σˣ, σʸ, σᶻ, σ⁺, σ⁻, σˣˣ, σʸʸ, σᶻᶻ, σ⁺⁻, σ⁻⁺, σσ
 
 export a_plus, a_min, a_plusmin, a_minplus, a_number

src/models/hamiltonians.jl

@@ -7,14 +7,17 @@ ising_kwargs = (; J=1.0, g=1.0)
     transverse_field_ising([elt::Type{<:Number}], [symmetry::Type{<:Sector}],
                            [lattice::AbstractLattice]; J=1.0, g=1.0)
 
-MPO for the hamiltonian of the
+MPO for the hamiltonian of the one-dimensional
 [Transverse-field Ising model](https://en.wikipedia.org/wiki/Transverse-field_Ising_model),
 as defined by
 ```math
-H = -J\\left(∑_{<i,j>} Z_i Z_j + g ∑_{<i>} X_i\\right)
+H = -J\\left(\\sum_{\\langle i,j \\rangle} \\sigma^z_i \\sigma^z_j + g \\sum_{i} \\sigma^x_i \\right)
 ```
+where the ``\\sigma^i`` are the spin-1/2 Pauli operators. Possible values for the `symmetry`
+are `Trivial`, `Z2Irrep` or `FermionParity`.
 
-By default, the model is defined on an infinite chain with unit lattice spacing, without any symmetries and with `ComplexF64` entries of the tensors.
+By default, the model is defined on an infinite chain with unit lattice spacing, with
+`Trivial` symmetry and with `ComplexF64` entries of the tensors.
 """
 function transverse_field_ising end
 function transverse_field_ising(lattice::AbstractLattice; kwargs...)
@@ -28,8 +31,14 @@ end
 function transverse_field_ising(T::Type{<:Number}, lattice::AbstractLattice; kwargs...)
     return transverse_field_ising(T, Trivial, lattice; kwargs...)
 end
+function transverse_field_ising(T::Type{<:Number},
+                                S::Type{<:Sector},
+                                lattice::AbstractLattice;
+                                kwargs...)
+    throw(ArgumentError("`symmetry` must be either `Trivial`, `Z2Irrep` or `FermionParity`"))
+end
 function transverse_field_ising(T::Type{<:Number}=ComplexF64,
-                                S::Type{<:Sector}=Trivial,
+                                S::Union{Type{Trivial},Type{Z2Irrep}}=Trivial,
                                 lattice::AbstractLattice=InfiniteChain(1);
                                 J=1.0, g=1.0)
     ZZ = rmul!(σᶻᶻ(T, S), -J)
@@ -42,8 +51,8 @@ function transverse_field_ising(T::Type{<:Number}=ComplexF64,
         end
     end
 end
-
-function transverse_field_ising(T::Type{<:Number}, ::Type{fℤ₂}, lattice::AbstractLattice;
+function transverse_field_ising(T::Type{<:Number}, ::Type{fℤ₂},
+                                lattice::AbstractLattice=InfiniteChain(1);
                                 J=1.0, g=1.0)
     twosite = axpby!(-J, c_plusmin(T) + c_minplus(T), J, c_plusplus(T) + c_minmin(T))
     onesite = axpby!(2g * J, c_number(T), -g * J, id(Matrix{T}, space(twosite, 1)))
@@ -67,7 +76,7 @@ end
 
 MPO for the hamiltonian of the Kitaev model, as defined by
 ```math
-H = ∑_{<i,j>} \\left(-\\frac{t}{2}(c⁺ᵢcⱼ + c⁺ⱼcᵢ) + \\frac{Δ}{2}(c⁺ᵢc⁺ⱼ + cⱼcᵢ) \\right) - μ ∑_{<i>} c⁺ᵢcᵢ
+H = \\sum_{\\langle i,j \\rangle} \\left(-\\frac{t}{2}(c_i^+ c_j^- + c_j^+c_i^-) + \\frac{Δ}{2}(c_i^+c_j^+ + c_j^-c_i^-) \\right) - \\mu \\sum_{i} c_i^+ c_i^-
 ```
 
 By default, the model is defined on an infinite chain with unit lattice spacing and with `ComplexF64` entries of the tensors.
@@ -102,8 +111,9 @@ end
 
 MPO for the hamiltonian of the isotropic Heisenberg model, as defined by
 ```math
-H = J ∑_{<i,j>} S⃗ᵢ⋅S⃗ⱼ
+H = J \\sum_{\\langle i,j \\rangle} \\vec{S}_i \\cdot \\vec{S}_j
 ```
+where ``\\vec{S} = (S^x, S^y, S^z)``.
 
 By default, the model is defined on an infinite chain with unit lattice spacing, without any symmetries and with `ComplexF64` entries of the tensors.
 
@@ -136,7 +146,7 @@ end
 
 MPO for the hamiltonian of the XXZ Heisenberg model, as defined by
 ```math
-H = J(∑_{<i,j>} XᵢXⱼ + YᵢYⱼ + Δ ZᵢZⱼ)
+H = J \\left( \\sum_{\\langle i,j \\rangle} S_i^x S_j^x + S_i^y S_j^y + \\Delta S_i^z S_j^z \\right)
 ```
 
 By default, the model is defined on an infinite chain with unit lattice spacing, without any symmetries and with `ComplexF64` entries of the tensors.
@@ -168,9 +178,9 @@ end
     heisenberg_XYZ([elt::Type{<:Number}], [lattice::AbstractLattice];
         Jx=1.0, Jy=1.0, Jz=1.0, spin=1)
 
-MPO for the hamiltonian of the xyz Heisenberg model, defined by
+MPO for the hamiltonian of the XYZ Heisenberg model, defined by
 ```math
-H = ∑_{<i,j>} (JˣXᵢXⱼ + JʸYᵢYⱼ + JᶻZᵢZⱼ)
+H = \\sum_{\\langle i,j \\rangle} \\left( J^x S_i^x S_j^x + J^y S_i^y S_j^y + J^z S_i^z S_j^z \\right)
 ```
 
 By default, the model is defined on an infinite chain with unit lattice spacing and with `ComplexF64` entries of the tensors.
@@ -196,8 +206,9 @@ end
 
 MPO for the hamiltonian of the bilinear biquadratic Heisenberg model, as defined by
 ```math
-H = J ∑_{<i,j>} (\\cos(θ) S⃗ᵢ⋅S⃗ⱼ + \\sin(θ) (⃗S⃗ᵢ⋅S⃗ⱼ)²)
+H = J \\sum_{\\langle i,j \\rangle} \\left(\\cos(\\theta) \\vec{S}_i \\cdot \\vec{S}_j + \\sin(\\theta) \\left( \\vec{S}_i \\cdot \\vec{S}_j \\right)^2 \\right)
 ```
+where ``\\vec{S} = (S^x, S^y, S^z)``.
 
 By default, the model is defined on an infinite chain with unit lattice spacing, without any symmetries and with `ComplexF64` entries of the tensors.
 """
@@ -234,8 +245,10 @@ end
 
 MPO for the hamiltonian of the Hubbard model, as defined by
 ```math
-H = -t∑_{<i,j>} (c⁺_{σ,i}c⁻_{σ,j} + c⁻_{σ,i}c⁺_{σ,j}) + U ∑_i n_{i,↑}n_{i,↓} - ∑_i μnᵢ
+H = -t \\sum_{\\langle i,j \\rangle} \\sum_{\\sigma} \\left( e_{i,\\sigma}^+ e_{j,\\sigma}^- + c_{i,\\sigma}^- c_{j,\\sigma}^+ \\right) + U \\sum_i n_{i,\\uparrow}n_{i,\\downarrow} - \\sum_i \\mu n_i
 ```
+where ``\\sigma`` is a spin index that can take the values ``\\uparrow`` or ``\\downarrow``
+and ``n`` is the fermionic number operator [`e_number`](@ref).
 
 By default, the model is defined on an infinite chain with unit lattice spacing, without any symmetries and with `ComplexF64` entries of the tensors. If the `particle_symmetry` is not `Trivial`, a fixed particle number density `n` can be imposed.
 """
@@ -276,8 +289,9 @@ end
 
 MPO for the hamiltonian of the Bose-Hubbard model, as defined by
 ```math
-H = -t∑_{<i,j>} (a⁺_{i}a⁻_{j} + a⁻_{i}a⁺_{j}) - ∑_i μnᵢ + U / 2 ∑_i nᵢ(nᵢ - 1)
+H = -t \\sum_{\\langle i,j \\rangle} \\left( a_{i}^+ a_{j}^- + a_{i}^- a_{j}^+ \\right) - \\sum_i \\mu N_i + \\frac{U}{2} \\sum_i N_i(N_i - 1).
 ```
+where ``N`` is the bosonic number operator [`a_number`](@ref).
 
 By default, the model is defined on an infinite chain with unit lattice spacing, without any symmetries and with `ComplexF64` entries of the tensors. The Hilbert space is truncated such that at maximum of `cutoff` bosons can be at a single site. If the `symmetry` is not `Trivial`, a fixed particle number density `n` can be imposed.
 """

src/models/quantum_chemistry.jl

@@ -15,11 +15,13 @@ Base.:*(_, ::EmptyVal) = EmptyVal()
 """
     quantum_chemistry_hamiltonian(E0::Number, K::AbstractMatrix{<:Number}, V::AbstractArray{<:Number,4}, [elt::Type{<:Number}=ComplexF64])
 
-MPO for the quantum chemistry Hamiltonian, with kinetic energy K and potential energy V. The Hamiltonian is given by
+MPO for the quantum chemistry Hamiltonian, with kinetic energy ``K`` and potential energy ``V``. The Hamiltonian is given by
+
 ```math
-H = E0 + ∑ᵢⱼ ∑ₛ K[i,j] c^{s,+}_i c^{s,-}_j + ∑ᵢⱼₖₗ ∑ₛₜ V[i,j,k,l] c^{s,+}_i c^{t,+}_j c^{t,-}_k c^{s,-}_l
+H = E0 + \\sum_{i,j} \\sum_s K[i,j] e_{i,s}^{+} e_{j,s}^{-} + \\sum_{i,j,k,l} \\sum_{s,t} V[i,j,k,l] e_{i,s}^{+} e_{j,t}^{+} e_{k,t}^{-} e_{l,s}^{-}
 ```
-where `s` and `t` are spin indices, which can be `↑` or `↓`. The full hamiltonian has U₁ × SU₂ × FermionParity symmetry.
+
+where ``s`` and ``t`` are spin indices, which can be ``\\uparrow`` or ``\\downarrow``. The full hamiltonian has `U₁ ⊠ SU₂ ⊠ FermionParity` symmetry.
 
 !!! note
     This should not be regarded as state-of-the-art quantum chemistry DMRG code. It is only meant to demonstrate the use of MPSKit for quantum chemistry. In particular:

src/models/transfermatrices.jl

@@ -5,9 +5,13 @@
     classical_ising([elt::Type{<:Number}=ComplexF64], [symmetry::Type{<:Sector}=Trivial];
                     beta=log(1+sqrt(2))/2)
 
-MPO for the classical Ising partition function, defined by
-    
-``Z(β) = ∑_s exp(-βH(s))`` with ``H(s) = ∑_{<i,j>}σ_i σ_j``
+MPO for the partition function of the two-dimensional classical Ising model, defined as
+
+```math
+\\mathcal{Z}(\\beta) = \\sum_{\\{s\\}} \\exp(-\\beta H(s)) \\text{ with } H(s) = \\sum_{\\langle i, j \\rangle} s_i s_j
+
+```
+where each classical spin can take the values ``s = \\pm 1``.
 """
 function classical_ising end
 function classical_ising(symmetry::Type{<:Sector}; kwargs...)
@@ -49,7 +53,7 @@ end
     sixvertex([elt::Type{<:Number}=ComplexF64], [symmetry::Type{<:Sector}=Trivial];
               a=1.0, b=1.0, c=1.0)
 
-MPO for the six vertex model.
+MPO for the partition function of the two-dimensional six vertex model.
 """
 function sixvertex end
 sixvertex(symmetry::Type{<:Sector}; kwargs...) = sixvertex(ComplexF64, symmetry; kwargs...)
@@ -85,7 +89,7 @@ end
 """
     hard_hexagon([elt::Type{<:Number}=ComplexF64])
 
-MPO for the hard hexagon model.
+MPO for the partition function of the two-dimensional hard hexagon model.
 """
 function hard_hexagon(elt::Type{<:Number}=ComplexF64)
     P = Vect[FibonacciAnyon](:τ => 1)
@@ -101,7 +105,7 @@ end
 """
     qstate_clock([elt::Type{<:Number}=ComplexF64], [symmetry::Type{<:Sector}=Trivial]; beta::Number=1.0, q::Integer=3)
 
-MPO for the discrete clock model with ``q`` states.
+MPO for the partition function of the two-dimensional discrete clock model with ``q`` states.
 """
 function qstate_clock(elt::Type{<:Number}=ComplexF64, ::Type{Trivial}=Trivial;
                       beta::Number=1.0, q::Integer=3)

src/operators/bosonoperators.jl

@@ -1,5 +1,6 @@
 """
     a_plus([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; cutoff=5)
+    a⁺([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; cutoff=5)
 
 The truncated bosonic creation operator, with a maximum of `cutoff` bosons per site.
 """
@@ -46,6 +47,7 @@ const a⁺ = a_plus
 
 """
     a_min([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; cutoff=5)
+    a⁻([eltype::Type{<:Number}], [symmetry::Type{<:Sector}]; cutoff=5)    
 
 The truncated bosonic annihilation operator, with a maximum of `cutoff` bosons per site.
 """

src/operators/fermionoperators.jl

@@ -4,8 +4,9 @@
 
 """
     c_plus([elt::Type{<:Number}=ComplexF64]; side=:L)
+    c⁺([elt::Type{<:Number}=ComplexF64]; side=:L)
 
-fermionic creation operator.
+Fermionic creation operator.
 """
 function c_plus(elt::Type{<:Number}=ComplexF64; side=:L)
     vspace = Vect[fℤ₂](1 => 1)
@@ -26,8 +27,9 @@ const c⁺ = c_plus
 
 """
     c_min([elt::Type{<:Number}=ComplexF64]; side=:L)
+    c⁻([elt::Type{<:Number}=ComplexF64]; side=:L)
 
-fermionic annihilation operator.
+Fermionic annihilation operator.
 """
 function c_min(elt::Type{<:Number}=ComplexF64; side=:L)
     if side === :L
@@ -56,7 +58,7 @@ const c⁻c⁻ = c_minmin
 """
     c_number([elt::Type{<:Number}=ComplexF64])
 
-fermionic number operator.
+Fermionic number operator.
 """
 function c_number(elt::Type{<:Number}=ComplexF64)
     pspace = Vect[fℤ₂](0 => 1, 1 => 1)
@@ -71,6 +73,7 @@ end
 
 """
     e_plus([elt::Type{<:Number}=ComplexF64], particle_symmetry, spin_symmetry; side=:L)
+    e⁺([elt::Type{<:Number}=ComplexF64], particle_symmetry, spin_symmetry; side=:L)
 
 The creation operator for electron-like fermions.
 """
@@ -116,6 +119,7 @@ const e⁺ = e_plus
 
 """
     e_min([elt::Type{<:Number}=ComplexF64], particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector}; side=:L)
+    e⁻([elt::Type{<:Number}=ComplexF64], particle_symmetry::Type{<:Sector}, spin_symmetry::Type{<:Sector}; side=:L)
 
 The annihilation operator for electron-like fermions.
 """