From c6a52bb5dac7bab0e58f8ddaf496e615ba6a78f7 Mon Sep 17 00:00:00 2001
From: lkdvos <lukas.devos@ugent.be>
Date: Sat, 2 Dec 2023 10:22:43 +0100
Subject: [PATCH] Update docstrings

---
 src/algorithms/expval.jl  | 5 +++++
 src/algorithms/toolbox.jl | 5 +++--
 src/utility/plotting.jl   | 4 ++--
 3 files changed, 10 insertions(+), 4 deletions(-)

diff --git a/src/algorithms/expval.jl b/src/algorithms/expval.jl
index 9b5c7855..eca8bf62 100644
--- a/src/algorithms/expval.jl
+++ b/src/algorithms/expval.jl
@@ -5,6 +5,11 @@ Compute the expectation value of an operator `O` on a state `ψ`. If `location`
 operator is applied at that location. If `environments` is given, the expectation value
 might be computed more efficiently by re-using previously calculated environments.
 
+!!! note
+    For `MPOHamiltonian`, the expectation value is not uniquely defined, as it is unclear to
+    what site a given term belongs. For this reason, the returned value is half the
+    expectation value of all terms that start and end on the site.
+
 # Arguments
 * `ψ::AbstractMPS` : the state on which to compute the expectation value
 * `O` : the operator to compute the expectation value of. This can either be an `AbstractMPO`, a single `AbstractTensorMap` or an array of `AbstractTensorMap`s.
diff --git a/src/algorithms/toolbox.jl b/src/algorithms/toolbox.jl
index 23a49c47..38b94293 100644
--- a/src/algorithms/toolbox.jl
+++ b/src/algorithms/toolbox.jl
@@ -56,10 +56,11 @@ function transfer_spectrum(above::InfiniteMPS; below=above, tol=Defaults.tol, nu
 end
 
 """
-    entanglement_spectrum(ψ, site::Int=0) -> SectorDict{sectortype(ψ),Vector{<:Real}}
+    entanglement_spectrum(ψ; site::Int=0) -> SectorDict{sectortype(ψ),Vector{<:Real}}
 
 Compute the entanglement spectrum at a given site, i.e. the singular values of the gauge
-matrix at that site. This is a dictionary mapping the charge to the singular value.
+matrix to the right of a given site. This is a dictionary mapping the charge to the singular
+value.
 """
 function entanglement_spectrum(st::Union{InfiniteMPS,FiniteMPS,WindowMPS}, site::Int=0)
     @assert site <= length(st)
diff --git a/src/utility/plotting.jl b/src/utility/plotting.jl
index fdf7fc73..02a2dbd1 100644
--- a/src/utility/plotting.jl
+++ b/src/utility/plotting.jl
@@ -1,10 +1,10 @@
 """
     entanglementplot(state; site=0[, kwargs])
 
-Plot the entanglement spectrum of a given InfiniteMPS.
+Plot the entanglement spectrum of a given InfiniteMPS. 
 
 # Arguments
-- `site::Int=0`: mps index for multisite unit cells.
+- `site::Int=0`: mps index for multisite unit cells. Spectrum is computed for the bond between `site` and `site + 1`.
 - `expand_symmetry::Logical=false`: add quantum dimension degeneracies.
 - `sortby=maximum`: the method of sorting the sectors.
 - `sector_margin=1//10`: the amount of whitespace between sectors.