From 622471a78b97e9d8061d4d9207fbf2d99e25c1ff Mon Sep 17 00:00:00 2001 From: Stefan Krastanov Date: Sun, 11 Aug 2024 02:05:39 -0400 Subject: [PATCH] fixup and better doc verification --- Project.toml | 2 + docs/make.jl | 10 +++-- docs/src/API.md | 2 +- src/QSymbolicsBase/QSymbolicsBase.jl | 6 ++- src/QSymbolicsBase/linalg.jl | 66 +++++++++++++++++++++++++--- 5 files changed, 73 insertions(+), 13 deletions(-) diff --git a/Project.toml b/Project.toml index 8090b9c..dac63da 100644 --- a/Project.toml +++ b/Project.toml @@ -4,6 +4,7 @@ authors = ["QuantumSymbolics.jl contributors"] version = "0.4.1" [deps] +DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae" Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316" LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e" MacroTools = "1914dd2f-81c6-5fcd-8719-6d5c9610ff09" @@ -23,6 +24,7 @@ QuantumCliffordExt = "QuantumClifford" QuantumOpticsExt = "QuantumOpticsBase" [compat] +DocStringExtensions = "0.9" Latexify = "0.16" LinearAlgebra = "1.9" MacroTools = "0.5.13" diff --git a/docs/make.jl b/docs/make.jl index 6bce4c3..365aa09 100644 --- a/docs/make.jl +++ b/docs/make.jl @@ -5,12 +5,13 @@ using Documenter using DocumenterCitations using QuantumSymbolics using QuantumInterface +using LinearAlgebra -DocMeta.setdocmeta!(QuantumSymbolics, :DocTestSetup, :(using QuantumSymbolics, QuantumOptics, QuantumClifford); recursive=true) +DocMeta.setdocmeta!(QuantumSymbolics, :DocTestSetup, :(using QuantumSymbolics, QuantumOptics, QuantumClifford, QuantumInterface, LinearAlgebra); recursive=true) function main() bib = CitationBibliography(joinpath(@__DIR__,"src/references.bib"), style=:authoryear) - + makedocs( plugins=[bib], doctest = false, @@ -19,8 +20,9 @@ function main() format = Documenter.HTML( assets=["assets/init.js"] ), - modules = [QuantumSymbolics], - warnonly = [:missing_docs], + modules = [QuantumSymbolics, QuantumInterface], + checkdocs = :exports, + warnonly = false, authors = "Stefan Krastanov", pages = [ "QuantumSymbolics.jl" => "index.md", diff --git a/docs/src/API.md b/docs/src/API.md index 1073e11..7f3aa7d 100644 --- a/docs/src/API.md +++ b/docs/src/API.md @@ -12,6 +12,6 @@ ## Autogenerated API list ```@autodocs -Modules = [QuantumSymbolics] +Modules = [QuantumSymbolics, QuantumInterface] Private = false ``` diff --git a/src/QSymbolicsBase/QSymbolicsBase.jl b/src/QSymbolicsBase/QSymbolicsBase.jl index 915f28b..1d6165e 100644 --- a/src/QSymbolicsBase/QSymbolicsBase.jl +++ b/src/QSymbolicsBase/QSymbolicsBase.jl @@ -6,6 +6,8 @@ using TermInterface import TermInterface: isexpr,head,iscall,children,operation,arguments,metadata,maketerm import MacroTools: namify, @capture +using DocStringExtensions + using LinearAlgebra import LinearAlgebra: eigvecs,ishermitian,conj,transpose,inv,exp,vec,tr @@ -47,7 +49,7 @@ export SymQObj,QObj, qexpand, isunitary, KrausRepr,kraus - + ## # Metadata cache helpers ## @@ -96,7 +98,7 @@ const QObj = Union{AbstractBra,AbstractKet,AbstractOperator,AbstractSuperOperato const SymQObj = Symbolic{<:QObj} # TODO Should we use Sym or Symbolic... Sym has a lot of predefined goodies, including metadata support Base.:(-)(x::SymQObj) = (-1)*x Base.:(-)(x::SymQObj,y::SymQObj) = x + (-y) -Base.hash(x::SymQObj, h::UInt) = isexpr(x) ? hash((head(x), arguments(x)), h) : +Base.hash(x::SymQObj, h::UInt) = isexpr(x) ? hash((head(x), arguments(x)), h) : hash((typeof(x),symbollabel(x),basis(x)), h) maketerm(::Type{<:SymQObj}, f, a, t, m) = f(a...) diff --git a/src/QSymbolicsBase/linalg.jl b/src/QSymbolicsBase/linalg.jl index 48e9400..77c1762 100644 --- a/src/QSymbolicsBase/linalg.jl +++ b/src/QSymbolicsBase/linalg.jl @@ -2,6 +2,12 @@ # Linear algebra operations on quantum objects. ## +#TODO upstream to QuantumInterface +"""The commutator of two operators.""" +function commutator end +"""The anticommutator of two operators.""" +function anticommutator end + """Symbolic commutator of two operators. ```jldoctest @@ -94,6 +100,14 @@ arguments(x::SConjugate) = [x.obj] operation(x::SConjugate) = conj head(x::SConjugate) = :conj children(x::SConjugate) = [:conj, x.obj] +""" + conj(x::Symbolic{AbstractKet}) + conj(x::Symbolic{AbstractBra}) + conj(x::Symbolic{AbstractOperator}) + conj(x::Symbolic{AbstractSuperOperator}) + +Symbolic transpose operation. See also [`SConjugate`](@ref). +""" conj(x::Symbolic{T}) where {T<:QObj} = SConjugate{T}(x) conj(x::SZero) = x conj(x::SConjugate) = x.obj @@ -126,6 +140,11 @@ arguments(x::SProjector) = [x.ket] operation(x::SProjector) = projector head(x::SProjector) = :projector children(x::SProjector) = [:projector,x.ket] +""" + projector(x::Symbolic{AbstractKet}) + +Symbolic projection operation. See also [`SProjector`](@ref). +""" projector(x::Symbolic{AbstractKet}) = SProjector(x) projector(x::SZeroKet) = SZeroOperator() basis(x::SProjector) = basis(x.ket) @@ -160,9 +179,14 @@ arguments(x::STranspose) = [x.obj] operation(x::STranspose) = transpose head(x::STranspose) = :transpose children(x::STranspose) = [:transpose, x.obj] -transpose(x::Symbolic{AbstractOperator}) = STranspose{AbstractOperator}(x) -transpose(x::Symbolic{AbstractKet}) = STranspose{AbstractBra}(x) -transpose(x::Symbolic{AbstractBra}) = STranspose{AbstractKet}(x) +""" + transpose(x::Symbolic{AbstractKet}) + transpose(x::Symbolic{AbstractBra}) + transpose(x::Symbolic{AbstractOperator}) + +Symbolic transpose operation. See also [`STranspose`](@ref). +""" +transpose(x::Symbolic{T}) where {T<:Union{AbstractKet,AbstractBra,AbstractOperator}} = STranspose{T}(x) transpose(x::SScaled) = x.coeff*transpose(x.obj) transpose(x::SAdd) = (+)((transpose(i) for i in arguments(x))...) transpose(x::SMulOperator) = (*)((transpose(i) for i in reverse(x.terms))...) @@ -207,9 +231,14 @@ arguments(x::SDagger) = [x.obj] operation(x::SDagger) = dagger head(x::SDagger) = :dagger children(x::SDagger) = [:dagger, x.obj] -dagger(x::Symbolic{AbstractBra}) = SDagger{AbstractKet}(x) -dagger(x::Symbolic{AbstractKet}) = SDagger{AbstractBra}(x) -dagger(x::Symbolic{AbstractOperator}) = SDagger{AbstractOperator}(x) +""" + dagger(x::Symbolic{AbstractKet}) + dagger(x::Symbolic{AbstractBra}) + dagger(x::Symbolic{AbstractOperator}) + +Symbolic transpose operation. See also [`STranspose`](@ref). +""" +dagger(x::Symbolic{T}) where {T<:Union{AbstractKet,AbstractBra,AbstractOperator}} = SDagger{T}(x) dagger(x::SScaled) = conj(x.coeff)*dagger(x.obj) dagger(x::SAdd) = (+)((dagger(i) for i in arguments(x))...) dagger(x::SMulOperator) = (*)((dagger(i) for i in reverse(x.terms))...) @@ -258,6 +287,11 @@ operation(x::STrace) = tr head(x::STrace) = :tr children(x::STrace) = [:tr, x.op] Base.show(io::IO, x::STrace) = print(io, "tr($(x.op))") +""" + tr(x::Symbolic{AbstractOperator}) + +Symbolic trace operation. See also [`STrace`](@ref). +""" tr(x::Symbolic{AbstractOperator}) = STrace(x) tr(x::SScaled{AbstractOperator}) = x.coeff*tr(x.obj) tr(x::SAdd{AbstractOperator}) = (+)((tr(i) for i in arguments(x))...) @@ -321,6 +355,11 @@ function basis(x::SPartialTrace) tensor(new_bases...) end Base.show(io::IO, x::SPartialTrace) = print(io, "tr$(x.sys)($(x.obj))") +""" + ptrace(x::Symbolic{AbstractOperator}) + +Symbolic partial trace operation. See also [`SPartialTrace`](@ref). +""" function ptrace(x::Symbolic{AbstractOperator}, s) ex = isexpr(x) ? qexpand(x) : x if isa(ex, typeof(x)) @@ -411,6 +450,11 @@ basis(x::SInvOperator) = basis(x.op) Base.show(io::IO, x::SInvOperator) = print(io, "$(x.op)⁻¹") Base.:(*)(invop::SInvOperator, op::SOperator) = isequal(invop.op, op) ? IdentityOp(basis(op)) : SMulOperator(invop, op) Base.:(*)(op::SOperator, invop::SInvOperator) = isequal(op, invop.op) ? IdentityOp(basis(op)) : SMulOperator(op, invop) +""" + inv(x::Symbolic{AbstractOperator}) + +Symbolic inverse of an operator. See also [`SInvOperator`](@ref). +""" inv(x::Symbolic{AbstractOperator}) = SInvOperator(x) @@ -434,6 +478,11 @@ head(x::SExpOperator) = :exp children(x::SExpOperator) = [:exp, x.op] basis(x::SExpOperator) = basis(x.op) Base.show(io::IO, x::SExpOperator) = print(io, "exp($(x.op))") +""" + exp(x::Symbolic{AbstractOperator}) + +Symbolic inverse of an operator. See also [`SExpOperator`](@ref). +""" exp(x::Symbolic{AbstractOperator}) = SExpOperator(x) @@ -460,6 +509,11 @@ head(x::SVec) = :vec children(x::SVec) = [:vec, x.op] basis(x::SVec) = (⊗)(fill(basis(x.op), length(basis(x.op)))...) Base.show(io::IO, x::SVec) = print(io, "|$(x.op)⟩⟩") +""" + vec(x::Symbolic{AbstractOperator}) + +Symbolic vector representation of an operator. See also [`SVec`](@ref). +""" vec(x::Symbolic{AbstractOperator}) = SVec(x) vec(x::SScaled{AbstractOperator}) = x.coeff*vec(x.obj) vec(x::SAdd{AbstractOperator}) = (+)((vec(i) for i in arguments(x))...)