From bb552a04aff609ecbce22e41814a4a6b6f7e63a8 Mon Sep 17 00:00:00 2001
From: araujoms <maltusan@gmail.com>
Date: Fri, 17 Jan 2025 12:13:05 +0100
Subject: [PATCH] add missing docstrings

---
 README.md           |  5 +--
 docs/src/api.md     |  6 ++++
 src/Ket.jl          |  5 ++-
 src/basic.jl        | 74 -------------------------------------------
 src/measurements.jl | 76 ++++++++++++++++++++++++++++++++++++++++++++-
 src/supermaps.jl    | 10 ++++++
 6 files changed, 96 insertions(+), 80 deletions(-)

diff --git a/README.md b/README.md
index fc7ffd4..acc3eba 100644
--- a/README.md
+++ b/README.md
@@ -30,16 +30,13 @@ into the Julia REPL.
 ## Related libraries
 
 Julia:
-<!--- [BellPolytopes.jl](https://github.com/ZIB-IOL/BellPolytopes.jl)-->
+
 - [QuantumClifford.jl](https://github.com/QuantumSavory/QuantumClifford.jl)
-<!--- [QuantumInformation.jl](https://github.com/iitis/QuantumInformation.jl) (abandoned)-->
 - [QuantumOptics.jl](https://github.com/qojulia/QuantumOptics.jl)
 - [QuantumToolbox.jl](https://github.com/qutip/QuantumToolbox.jl)
 - [Yao.jl](https://github.com/QuantumBFS/Yao.jl)
 
 Python:
-<!--- [qutip](https://github.com/qutip/qutip)-->
-<!--- [qutip-qip](https://github.com/qutip/qutip-qip)-->
 - [toqito](https://github.com/vprusso/toqito)
 
 MATLAB:
diff --git a/docs/src/api.md b/docs/src/api.md
index 86847c9..3dca446 100644
--- a/docs/src/api.md
+++ b/docs/src/api.md
@@ -1,5 +1,9 @@
 # List of functions
 
+```@docs
+Ket
+```
+
 ## Basic
 
 ```@docs
@@ -45,6 +49,7 @@ ppt_mixture
 ## Measurements
 
 ```@docs
+Measurement
 sic_povm
 test_sic
 test_povm
@@ -129,6 +134,7 @@ white_noise!
 ## Supermaps
 
 ```@docs
+applykraus
 choi
 ```
 
diff --git a/src/Ket.jl b/src/Ket.jl
index a42d80f..a24decc 100644
--- a/src/Ket.jl
+++ b/src/Ket.jl
@@ -1,3 +1,6 @@
+"""
+Toolbox for quantum information, nonlocality, and entanglement.
+"""
 module Ket
 
 using LinearAlgebra
@@ -15,11 +18,11 @@ import QuantumNPA
 const MOI = JuMP.MOI
 
 include("basic.jl")
+include("measurements.jl")
 include("states.jl")
 include("nonlocal.jl")
 include("random.jl")
 include("games.jl")
-include("measurements.jl")
 include("incompatibility.jl")
 include("entropy.jl")
 include("norms.jl")
diff --git a/src/basic.jl b/src/basic.jl
index fbee23f..3c266f9 100644
--- a/src/basic.jl
+++ b/src/basic.jl
@@ -34,75 +34,6 @@ end
 proj(i::Integer, d::Integer = 2) = proj(Bool, i, d)
 export proj
 
-const Measurement{T} = Vector{Hermitian{T,Matrix{T}}}
-export Measurement
-
-"""
-    povm(B::Vector{<:AbstractMatrix{T}})
-
-Creates a set of (projective) measurements from a set of bases given as unitary matrices.
-"""
-function povm(B::Vector{<:AbstractMatrix})
-    return [[ketbra(B[x][:, a]) for a ∈ 1:size(B[x], 2)] for x ∈ eachindex(B)]
-end
-export povm
-
-"""
-    tensor_to_povm(A::Array{T,4}, o::Vector{Int})
-
-Converts a set of measurements in the common tensor format into a matrix of (hermitian) matrices.
-By default, the second argument is fixed by the size of `A`.
-It can also contain custom number of outcomes if there are measurements with less outcomes.
-"""
-function tensor_to_povm(Aax::Array{T,4}, o::Vector{Int} = fill(size(Aax, 3), size(Aax, 4))) where {T}
-    return [[Hermitian(Aax[:, :, a, x]) for a ∈ 1:o[x]] for x ∈ axes(Aax, 4)]
-end
-export tensor_to_povm
-
-"""
-    povm_to_tensor(Axa::Vector{<:Measurement})
-
-Converts a matrix of (hermitian) matrices into a set of measurements in the common tensor format.
-"""
-function povm_to_tensor(Axa::Vector{Measurement{T}}) where {T<:Number}
-    d, o, m = _measurements_parameters(Axa)
-    Aax = zeros(T, d, d, maximum(o), m)
-    for x ∈ eachindex(Axa)
-        for a ∈ eachindex(Axa[x])
-            Aax[:, :, a, x] .= Axa[x][a]
-        end
-    end
-    return Aax
-end
-export povm_to_tensor
-
-function _measurements_parameters(Axa::Vector{Measurement{T}}) where {T<:Number}
-    @assert !isempty(Axa)
-    # dimension on which the measurements act
-    d = size(Axa[1][1], 1)
-    # tuple of outcome numbers
-    o = Tuple(length.(Axa))
-    # number of inputs, i.e., of mesurements
-    m = length(Axa)
-    return d, o, m
-end
-_measurements_parameters(Aa::Measurement) = _measurements_parameters([Aa])
-
-"""
-    test_povm(A::Vector{<:AbstractMatrix{T}})
-
-Checks if the measurement defined by A is valid (hermitian, semi-definite positive, and normalized).
-"""
-function test_povm(E::Vector{<:AbstractMatrix{T}}) where {T<:Number}
-    !all(ishermitian.(E)) && return false
-    d = size(E[1], 1)
-    !(sum(E) ≈ I(d)) && return false
-    for i ∈ 1:length(E)
-        minimum(eigvals(E[i])) < -_rtol(T) && return false
-    end
-    return true
-end
-export test_povm
 
 """
     shift([T=ComplexF64,] d::Integer, p::Integer = 1)
@@ -291,11 +222,6 @@ function _cleanup!(M; tol)
     return M[abs.(M).<tol] .= 0
 end
 
-function applykraus(K, M)
-    return sum(Hermitian(Ki * M * Ki') for Ki ∈ K)
-end
-export applykraus
-
 function _orthonormal_range_svd!(
     A::AbstractMatrix{T};
     tol::Union{Real,Nothing} = nothing,
diff --git a/src/measurements.jl b/src/measurements.jl
index 5829641..81700e4 100644
--- a/src/measurements.jl
+++ b/src/measurements.jl
@@ -133,7 +133,81 @@ function test_mub(B::Vector{Matrix{T}}) where {T<:Number}
 end
 export test_mub
 
-# SIC POVMs
+# POVMs
+"""
+    Measurement{T}
+
+Alias for `Vector{Hermitian{T,Matrix{T}}}`
+"""
+const Measurement{T} = Vector{Hermitian{T,Matrix{T}}}
+export Measurement
+
+"""
+    povm(B::Vector{<:AbstractMatrix{T}})
+
+Creates a set of (projective) measurements from a set of bases given as unitary matrices.
+"""
+function povm(B::Vector{<:AbstractMatrix})
+    return [[ketbra(B[x][:, a]) for a ∈ 1:size(B[x], 2)] for x ∈ eachindex(B)]
+end
+export povm
+
+"""
+    tensor_to_povm(A::Array{T,4}, o::Vector{Int})
+
+Converts a set of measurements in the common tensor format into a matrix of (hermitian) matrices.
+By default, the second argument is fixed by the size of `A`.
+It can also contain custom number of outcomes if there are measurements with less outcomes.
+"""
+function tensor_to_povm(Aax::Array{T,4}, o::Vector{Int} = fill(size(Aax, 3), size(Aax, 4))) where {T}
+    return [[Hermitian(Aax[:, :, a, x]) for a ∈ 1:o[x]] for x ∈ axes(Aax, 4)]
+end
+export tensor_to_povm
+
+"""
+    povm_to_tensor(Axa::Vector{<:Measurement})
+
+Converts a matrix of (hermitian) matrices into a set of measurements in the common tensor format.
+"""
+function povm_to_tensor(Axa::Vector{Measurement{T}}) where {T<:Number}
+    d, o, m = _measurements_parameters(Axa)
+    Aax = zeros(T, d, d, maximum(o), m)
+    for x ∈ eachindex(Axa)
+        for a ∈ eachindex(Axa[x])
+            Aax[:, :, a, x] .= Axa[x][a]
+        end
+    end
+    return Aax
+end
+export povm_to_tensor
+
+function _measurements_parameters(Axa::Vector{Measurement{T}}) where {T<:Number}
+    @assert !isempty(Axa)
+    # dimension on which the measurements act
+    d = size(Axa[1][1], 1)
+    # tuple of outcome numbers
+    o = Tuple(length.(Axa))
+    # number of inputs, i.e., of mesurements
+    m = length(Axa)
+    return d, o, m
+end
+_measurements_parameters(Aa::Measurement) = _measurements_parameters([Aa])
+
+"""
+    test_povm(A::Vector{<:AbstractMatrix{T}})
+
+Checks if the measurement defined by A is valid (hermitian, semi-definite positive, and normalized).
+"""
+function test_povm(E::Vector{<:AbstractMatrix{T}}) where {T<:Number}
+    !all(ishermitian.(E)) && return false
+    d = size(E[1], 1)
+    !(sum(E) ≈ I(d)) && return false
+    for i ∈ 1:length(E)
+        minimum(eigvals(E[i])) < -_rtol(T) && return false
+    end
+    return true
+end
+export test_povm
 
 """
     sic_povm([T=ComplexF64,] d::Integer)
diff --git a/src/supermaps.jl b/src/supermaps.jl
index de99318..e3de699 100644
--- a/src/supermaps.jl
+++ b/src/supermaps.jl
@@ -3,6 +3,16 @@ _solver_type(::Type{T}) where {T<:AbstractFloat} = T
 _solver_type(::Type{Complex{T}}) where {T<:AbstractFloat} = T
 _solver_type(::Type{T}) where {T<:Number} = Float64
 
+"""
+    applykraus(K::Vector{<:AbstractMatrix}, M::AbstractMatrix)
+
+Applies the CP map given by the Kraus operators `K` to the matrix `M`.
+"""
+function applykraus(K::Vector{<:AbstractMatrix}, M::AbstractMatrix)
+    return sum(Hermitian(Ki * M * Ki') for Ki ∈ K)
+end
+export applykraus
+
 """
     choi(K::Vector{<:AbstractMatrix})