add linear algebra and documentation

docs/make.jl

@@ -25,8 +25,9 @@ function main()
     authors = "Stefan Krastanov",
     pages = [
         "QuantumSymbolics.jl" => "index.md",
-        "Qubit Basis Choice" => "qubit_basis.md",
+        "Getting Started with QuantumSymbolics.jl" => "introduction.md",
         "Express Functionality" => "express.md",
+        "Qubit Basis Choice" => "qubit_basis.md",
         "API" => "API.md",
     ]
     )

docs/src/introduction.md

@@ -0,0 +1,247 @@
+# Getting Started with QuantumSymbolics.jl
+
+```@meta
+DocTestSetup = quote
+    using QuantumSymbolics
+end
+```
+
+QuantumSymbolics is designed for manipulation and numerical translation of symbolic quantum objects. This tutorial introduces basic features of the package.
+
+## Installation
+
+QuantumSymbolics.jl can be installed through the Julia package system in the standard way:
+
+```@example 1
+using Pkg
+Pkg.add("QuantumSymbolics")
+```
+
+## Literal Symbolic Quantum Objects
+
+Basic objects of type `SBra`, `SKet`, and `SOperator` represent symbolic quantum objects with `name` and `basis` properties. Each type can be generated with a straightforward macro:
+
+```jldoctest
+julia> using QuantumSymbolics
+
+julia> @bra b # object of type SBra
+⟨b|
+
+julia> @ket k # object of type SKet
+|k⟩
+
+julia> @op A # object of type SOperator
+A
+```
+
+By default, each of the above macros defines a symbolic quantum object in the spin-1/2 basis. One can simply choose a different basis, such as the Fock basis or a tensor product of several bases, by passing an object of type `Basis` to the second argument in the macro call:
+
+```jldoctest
+julia> @op B FockBasis(5)
+B
+
+julia> basis(B)
+Fock(cutoff=5)
+
+julia> @op C SpinBasis(1//2)⊗SpinBasis(5//2)
+C
+
+julia> basis(C)
+[Spin(1/2) ⊗ Spin(5/2)]
+```
+Here, we extracted the basis of the defined symbolic operators using the `basis` function.
+
+
+Symbolic quantum objects with additional properties can be defined, such as a Hermitian operator, or the zero ket (i.e., a symbolic ket equivalent to the zero vector $\bm{0}$).
+
+## Basic Operations
+
+Expressions containing symbolic quantum objects can be built with a variety of functions. Let us consider the most fundamental operations: multiplication `*`, addition `+`, and the tensor product `⊗`. 
+
+We can multiply, for example, a ket by a scalar value, or apply an operator to a ket:
+
+```jldoctest
+julia> @ket k; @op A;
+
+julia> 2*k
+2|k⟩
+
+julia> A*k
+A|k⟩
+```
+
+Similar scaling procedures can be performed on bras and operators. Addition between symbolic objects is also available, for instance:
+
+```jldoctest
+julia> @op A₁; @op A₂;
+
+julia> A₁+A₂
+(A₁+A₂)
+
+julia> @bra b;
+
+julia> 2*b + 5*b
+7⟨b|
+```
+Built into the package are straightforward automatic simplification rules, as shown in the last example, where `2⟨b|+5⟨b|` evaluates to `7⟨b|`. 
+
+Tensor products of symbolic objects can be performed, with basis information transferred:
+
+```jldoctest
+julia> @ket k₁; @ket k₂;
+
+julia> tp = k₁⊗k₂
+|k₁⟩|k₂⟩
+
+julia> basis(tp)
+[Spin(1/2) ⊗ Spin(1/2)]
+```
+
+Inner and outer products of bras and kets can be generated:
+
+```jldoctest
+julia> @bra b; @ket k;
+
+julia> b*k
+⟨b||k⟩
+
+julia> k*b
+|k⟩⟨b|
+```
+
+More involved combinations of operations can be explored. Here are few other straightforward examples:
+
+```jldoctest
+julia> @bra b; @ket k; @op A; @op B;
+
+julia> 3*A*B*k
+3AB|k⟩
+
+julia> A⊗(k*b + B)
+(A⊗(B+|k⟩⟨b|))
+
+julia> A-A
+𝟎
+```
+In the last example, a zero operator, denoted `𝟎`, was returned by subtracting a symbolic operator from itself. Such an object is of the type `SZeroOperator`, and similar objects `SZeroBra` and `SZeroKet` correspond to zero bras and zero kets, respectively.
+
+## Linear Algebra on Bras, Kets, and Operators
+
+QuantumSymbolics supports a wide variety of linear algebra on symbolic bras, kets, and operators. For instance, the commutator and anticommutator of two operators, can be generated:
+
+```jldoctest
+julia> @op A; @op B;
+
+julia> commutator(A, B)
+[A,B]
+
+julia> anticommutator(A, B)
+{A,B}
+
+julia> commutator(A, A)
+𝟎
+```
+Or, one can take the dagger of a quantum object with the `dagger` function:
+
+```jldoctest
+julia> @ket k; @op A; @op B;
+
+julia> dagger(A)
+A†
+
+julia> dagger(A*k)
+|k⟩†A†
+
+julia> dagger(A*B)
+B†A†
+```
+Below, we state all of the supported linear algebra operations on quantum objects:
+
+- commutator of two operators: `commutator`,
+- anticommutator of two operators: `anticommutator`,
+- complex conjugate: `conj`,
+- transpose: `transpose`,
+- projection of a ket: `projector`,
+- adjoint or dagger: `dagger`,
+- inverse of an operator: `inv`,
+- exponential of an operator: `exp`,
+- vectorization of an operator: `vec`.
+
+## Simplifying Expressions
+
+For predefined objects such as the Pauli operators `X`, `Y`, and `Z`, manual simplification can be performed with the [`qsimplify`](@ref) function. Take the following example:
+
+```jldoctest
+julia> qsimplify(X*Z)
+(0 - 1im)Y
+```
+
+Here, we have the relation $XZ = -iY$, so calling `qsimplify` on the expression `X*Z` will rewrite the expression as `-im*Y`.
+
+Note that simplification rewriters used in QuantumSymbolics are built from the interface of [`SymbolicUtils.jl`](https://github.com/JuliaSymbolics/SymbolicUtils.jl). By default, when called on an expression, `qsimplify` will iterate through every defined simplification rule in the QuantumSymbolics package until the expression can no longer be simplified. 
+
+Now, suppose we only want to use a specific subset of rules. For instance, say we wish to simplify commutators, but not anticommutators. Then, we can pass the keyword argument `rewriter=qsimplify_commutator` to `qsimplify`, as done in the following example:
+
+```jldoctest
+julia> qsimplify(commutator(X, Y), rewriter=qsimplify_commutator)
+(0 + 2im)Z
+
+julia> qsimplify(anticommutator(X, Y), rewriter=qsimplify_commutator)
+{X,Y}
+```
+As shown above, we apply `qsimplify` to two expressions: `commutator(X, Y)` and `anticommutator(X, Y)`. We specify that only commutator rules will be applied, thus the first expression is rewritten to `(0 + 2im)Z` while the second expression is simply returned. This feature can greatly reduce the time it takes for an expression to be simplified.
+
+Below, we state all of the simplification rule subsets that can be passed to `qsimplify`:
+
+- `qsimplify_pauli` for Pauli multiplication,
+- `qsimplify_commutator` for commutators of Pauli operators,
+- `qsimplify_anticommutator` for anticommutators of Pauli operators.
+
+## Expanding Expressions
+
+Symbolic expressions containing quantum objects can be expanded with the [`qexpand`](@ref) function. We demonstrate this capability with the following examples.
+
+```jldoctest
+julia> @op A; @op B; @op C;
+
+julia> qexpand(A⊗(B+C))
+((A⊗B)+(A⊗C))
+
+julia> qexpand((B+C)*A)
+(BA+CA)
+
+julia> @ket k₁; @ket k₂; @ket k₃;
+
+julia> qexpand(k₁⊗(k₂+k₃))
+(|k₁⟩|k₂⟩+|k₁⟩|k₃⟩)
+
+julia> qexpand((A*B)*(k₁+k₂))
+(AB|k₁⟩+AB|k₂⟩)
+```
+
+## Numerical Translation of Symbolic Objects
+
+Symbolic expressions containing predefined objects can be converted to numerical representations with [`express`](@ref). Numerics packages supported by this translation capability are [`QuantumOptics.jl`](https://github.com/qojulia/QuantumOptics.jl) and [`QuantumClifford.jl`](https://github.com/QuantumSavory/QuantumClifford.jl/).
+
+By default, `express` converts an object to the quantum optics state vector representation. For instance, we can represent the exponential of the Pauli operator `X` numerically as follows:
+
+```jldoctest
+julia> using QuantumOptics
+
+julia> express(exp(X))
+Operator(dim=2x2)
+  basis: Spin(1/2)sparse([1, 2, 1, 2], [1, 1, 2, 2], ComplexF64[1.5430806327160496 + 0.0im, 1.1752011684303352 + 0.0im, 1.1752011684303352 + 0.0im, 1.5430806327160496 + 0.0im], 2, 2)
+```
+
+To convert to the Clifford representation, an instance of `CliffordRepr` must be passed to `express`. For instance, we can represent the projection of the basis state [`X1`](@ref) of the Pauli operator `X` as follows:
+
+```jldoctest
+julia> using QuantumClifford
+
+julia> express(projector(X1), CliffordRepr())
+𝒟ℯ𝓈𝓉𝒶𝒷
++ Z
+𝒮𝓉𝒶𝒷
++ X
+```
+For more details on using [`express`](@ref), refer to the [express functionality page](@ref express).

src/QSymbolicsBase/QSymbolicsBase.jl

@@ -6,7 +6,7 @@ using TermInterface
 import TermInterface: isexpr,head,iscall,children,operation,arguments,metadata,maketerm
 
 using LinearAlgebra
-import LinearAlgebra: eigvecs,ishermitian,inv
+import LinearAlgebra: eigvecs,ishermitian,conj,transpose,inv,exp,vec
 
 import QuantumInterface:
     apply!,
@@ -28,14 +28,15 @@ export SymQObj,QObj,
        H,CNOT,CPHASE,XCX,XCY,XCZ,YCX,YCY,YCZ,ZCX,ZCY,ZCZ,
        X1,X2,Y1,Y2,Z1,Z2,X₁,X₂,Y₁,Y₂,Z₁,Z₂,L0,L1,Lp,Lm,Lpi,Lmi,L₀,L₁,L₊,L₋,L₊ᵢ,L₋ᵢ,
        vac,F₀,F0,F₁,F1,
-       N,n̂,Create,âꜛ,Destroy,â,SpinBasis,FockBasis,
+       N,n̂,Create,âꜛ,Destroy,â,basis,SpinBasis,FockBasis,
        SBra,SKet,SOperator,SHermitianOperator,SUnitaryOperator,SHermitianUnitaryOperator,
        @ket,@bra,@op,
        SAdd,SAddBra,SAddKet,SAddOperator,
        SScaled,SScaledBra,SScaledOperator,SScaledKet,
        STensorBra,STensorKet,STensorOperator,
        SZeroBra,SZeroKet,SZeroOperator,
-       SProjector,MixedState,IdentityOp,SInvOperator,
+       SConjugate,STranspose,SProjector,SInvOperator,SExpOperator,SVec,
+       MixedState,IdentityOp,
        SApplyKet,SApplyBra,SMulOperator,SSuperOpApply,SCommutator,SAnticommutator,SDagger,SBraKet,SOuterKetBra,
        HGate,XGate,YGate,ZGate,CPHASEGate,CNOTGate,
        XBasisState,YBasisState,ZBasisState,

src/QSymbolicsBase/basic_ops_homogeneous.jl

@@ -3,7 +3,7 @@
 # that are homogeneous in their arguments.
 ##
 
-"""Scaling of a quantum object (ket, operator, or bra) by a number
+"""Scaling of a quantum object (ket, operator, or bra) by a number.
 
 ```jldoctest
 julia> @ket k
@@ -69,7 +69,7 @@
     end
 end
 
-"""Addition of quantum objects (kets, operators, or bras)
+"""Addition of quantum objects (kets, operators, or bras).
 
 ```jldoctest
 julia> @ket k₁; @ket k₂;
@@ -118,7 +118,7 @@
     print(io, "("*join(ordered_terms,"+")::String*")") # type assert to help inference
 end
 
-"""Symbolic application of operator on operator
+"""Symbolic application of operator on operator.
 
 ```jldoctest
 julia> @op A; @op B;
@@ -149,7 +149,7 @@
 Base.show(io::IO, x::SMulOperator) = print(io, join(map(string, arguments(x)),""))
 basis(x::SMulOperator) = basis(x.terms)
 
-"""Tensor product of quantum objects (kets, operators, or bras)
+"""Tensor product of quantum objects (kets, operators, or bras).
 
 ```jldoctest
 julia> @ket k₁; @ket k₂;
@@ -191,65 +191,4 @@
 const STensorOperator = STensor{AbstractOperator}
 Base.show(io::IO, x::STensorOperator) = print(io, "("*join(map(string, arguments(x)),"⊗")*")")
 const STensorSuperOperator = STensor{AbstractSuperOperator}
-Base.show(io::IO, x::STensorSuperOperator) = print(io, "("*join(map(string, arguments(x)),"⊗")*")")
-
-"""Symbolic commutator of two operators
-
-```jldoctest
-julia> @op A; @op B;
-
-julia> commutator(A, B)
-[A,B]
-
-julia> commutator(A, A)
-𝟎
-```
-"""
-@withmetadata struct SCommutator <: Symbolic{AbstractOperator}
-    op1
-    op2
-end
-isexpr(::SCommutator) = true
-iscall(::SCommutator) = true
-arguments(x::SCommutator) = [x.op1, x.op2]
-operation(x::SCommutator) = commutator
-head(x::SCommutator) = :commutator
-children(x::SCommutator) = [:commutator, x.op1, x.op2]
-function commutator(o1::Symbolic{AbstractOperator}, o2::Symbolic{AbstractOperator})
-    coeff, cleanterms = prefactorscalings([o1 o2])
-    cleanterms[1] === cleanterms[2] ? SZeroOperator() : coeff * SCommutator(cleanterms...)   
-end
-commutator(o1::SZeroOperator, o2::Symbolic{AbstractOperator}) = SZeroOperator()
-commutator(o1::Symbolic{AbstractOperator}, o2::SZeroOperator) = SZeroOperator()
-commutator(o1::SZeroOperator, o2::SZeroOperator) = SZeroOperator()
-Base.show(io::IO, x::SCommutator) = print(io, "[$(x.op1),$(x.op2)]")
-basis(x::SCommutator) = basis(x.op1)
-
-"""Symbolic anticommutator of two operators
-
-```jldoctest
-julia> @op A; @op B;
-
-julia> anticommutator(A, B)
-{A,B}
-```
-"""
-@withmetadata struct SAnticommutator <: Symbolic{AbstractOperator}
-    op1
-    op2
-end
-isexpr(::SAnticommutator) = true
-iscall(::SAnticommutator) = true
-arguments(x::SAnticommutator) = [x.op1, x.op2]
-operation(x::SAnticommutator) = anticommutator
-head(x::SAnticommutator) = :anticommutator
-children(x::SAnticommutator) = [:anticommutator, x.op1, x.op2]
-function anticommutator(o1::Symbolic{AbstractOperator}, o2::Symbolic{AbstractOperator})
-    coeff, cleanterms = prefactorscalings([o1 o2])
-    coeff * SAnticommutator(cleanterms...)
-end
-anticommutator(o1::SZeroOperator, o2::Symbolic{AbstractOperator}) = SZeroOperator()
-anticommutator(o1::Symbolic{AbstractOperator}, o2::SZeroOperator) = SZeroOperator()
-anticommutator(o1::SZeroOperator, o2::SZeroOperator) = SZeroOperator()
-Base.show(io::IO, x::SAnticommutator) = print(io, "{$(x.op1),$(x.op2)}")
-basis(x::SAnticommutator) = basis(x.op1)
+Base.show(io::IO, x::STensorSuperOperator) = print(io, "("*join(map(string, arguments(x)),"⊗")*")")