Add StateVectorRepr backend with tests and documentation

CHANGELOG.md

@@ -1,5 +1,9 @@
 # News
 
+## [Unreleased]
+### Added
+- New `StateVectorRepr` backend for converting symbolic quantum objects to numerical vectors/matrices using `QuantumOpticsRepr` (Conversion of symbolic objects to base linear algebra objects (vectors, matrices, sparse matrices, etc)) (#118).
+
 ## v0.4.10 - 2025-05-11
 
 - Polish `Base.show` methods for application products and scaled quantum objects.

Project.toml

@@ -16,11 +16,12 @@ TermInterface = "8ea1fca8-c5ef-4a55-8b96-4e9afe9c9a3c"
 [weakdeps]
 QuantumClifford = "0525e862-1e90-11e9-3e4d-1b39d7109de1"
 QuantumOpticsBase = "4f57444f-1401-5e15-980d-4471b28d5678"
+QuantumOptics = "6e4d0e0e-3d2e-5f0e-8f3f-2b5b8e8d2f1e"
 
 [extensions]
 MixedCliffordOpticsExt = ["QuantumClifford", "QuantumOpticsBase"]
 QuantumCliffordExt = "QuantumClifford"
-QuantumOpticsExt = "QuantumOpticsBase"
+QuantumOpticsExt = ["QuantumOpticsBase", "QuantumOptics"]
 
 [compat]
 Latexify = "0.16"
@@ -29,6 +30,7 @@ MacroTools = "0.5.13"
 PrecompileTools = "1.2"
 QuantumClifford = "0.8.19, 0.9"
 QuantumInterface = "0.3.7"
+QuantumOptics = "0.9"
 QuantumOpticsBase = "0.4.22, 0.5"
 SymbolicUtils = "3.7"
 Symbolics = "6"

docs/src/index.md

@@ -203,3 +203,18 @@ express(MixedState(X1)/2+SProjector(Z1)/2, CliffordRepr())
 !!! warning "Stabilizer state expressions"
 
     The state written as $\frac{|Z₁⟩⊗|Z₁⟩+|Z₂⟩⊗|Z₂⟩}{√2}$ is a well known stabilizer state, namely a Bell state. However, automatically expressing it as a stabilizer is a prohibitively expensive computational operation in general. We do not perform that computation automatically. If you want to ensure that states you define can be automatically converted to tableaux for Clifford simulations, avoid using summation of kets. On the other hand, in all of our Clifford Monte-Carlo simulations, `⊗` is fully supported, as well as [`projector`](@ref), [`MixedState`](@ref), [`StabilizerState`](@ref), and summation of density matrices.
+
+## Backends
+
+`QuantumSymbolics.jl` supports multiple numerical backends via the `express` API. In addition to structured representations like `QuantumOpticsRepr` and `CliffordRepr`, the new `StateVectorRepr` backend converts symbolic objects to basic linear algebra objects:
+
+```julia
+julia> express(X1, StateVectorRepr())
+2-element Vector{ComplexF64}:
+ 0.7071067811865475 + 0.0im
+ 0.7071067811865475 + 0.0im
+
+julia> express(Z1, StateVectorRepr())
+2×2 Matrix{ComplexF64}:
+ 1.0+0.0im   0.0+0.0im
+ 0.0+0.0im  -1.0+0.0im

ext/QuantumOpticsExt/QuantumOpticsExt.jl

@@ -15,6 +15,8 @@ import QuantumSymbolics: express, express_nolookup
 using TermInterface
 using TermInterface: isexpr, head, operation, arguments, metadata
 
+using SymbolicUtils
+
 const _b2 = SpinBasis(1//2)
 const _l0 = spinup(_b2)
 const _l1 = spindown(_b2)
@@ -100,4 +102,28 @@ express_nolookup(s::SOuterKetBra, r::QuantumOpticsRepr) = projector(express(s.ke
 
 include("should_upstream.jl")
 
+"""
+    StateVectorRepr(config=nothing)
+
+A custom backend for `QuantumSymbolics.express`. Converts symbolic quantum
+objects into Julia's `Vector{ComplexF64}` (kets) or `Matrix{ComplexF64}` (operators).
+
+Internally uses `QuantumOptics.QuantumOpticsRepr` and extracts `.data`.
+An optional `config` (e.g., `(cutoff=4,)`) is forwarded to `QuantumOptics.QuantumOpticsRepr`.
+"""
+struct StateVectorRepr{C}
+    config::C
+    StateVectorRepr(config=nothing) = new{typeof(config)}(config)
+end
+
+function QuantumSymbolics.express(sym_obj::SymbolicUtils.Symbolic, backend::StateVectorRepr)
+    qo_repr = if backend.config isa Nothing
+        QuantumOptics.QuantumOpticsRepr()
+    else
+        QuantumOptics.QuantumOpticsRepr(backend.config...)
+    end
+    qo_obj = QuantumSymbolics.express(sym_obj, qo_repr)
+    return qo_obj.data
+end
+
 end

test/Project.toml

@@ -2,7 +2,7 @@
 Aqua = "4c88cf16-eb10-579e-8560-4a9242c79595"
 Documenter = "e30172f5-a6a5-5a46-863b-614d45cd2de4"
 Graphs = "86223c79-3864-5bf0-83f7-82e725a168b6"
-InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
+InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27 wrapping-240"
 JET = "c3a54625-cd67-489e-a8e7-0a5a0ff4e31b"
 Latexify = "23fbe1c1-3f47-55db-b15f-69d7ec21a316"
 LinearAlgebra = "37e2e46d-f89d-539d-b4ee-838fcccc9c8e"
@@ -20,3 +20,13 @@ Symbolics = "0c5d862f-8b57-4792-8d23-62f2024744c7"
 TermInterface = "8ea1fca8-c5ef-4a55-8b96-4e9afe9c9a3c"
 Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
 TestItemRunner = "f8b46487-2199-4994-9208-9a1283c18c0a"
+
+[deps.QuantumSavory]
+git = "https://github.com/QuantumSavory/QuantumSavory.jl"
+
+[compat]
+julia = "1"
+QuantumSavory = "0.1"
+
+[targets]
+test = ["Test", "TestItemRunner", "QuantumSavory", "QuantumOptics", "QuantumClifford", "QuantumInterface", "QuantumOpticsBase", "SymbolicUtils", "TermInterface"]

test/test_statevectorrepr.jl

@@ -0,0 +1,37 @@
+using QuantumSymbolics
+using QuantumOptics
+using QuantumSavory
+
+@testitem "StateVectorRepr Conversion Tests" begin
+    # Test: Symbolic Ket (X1) conversion
+    sym_X1_test = QuantumSavory.X1
+    qo_X1_data = QuantumOptics.express(sym_X1_test, QuantumOptics.QuantumOpticsRepr()).data
+    sv_X1_data = express(sym_X1_test, StateVectorRepr())
+    @test sv_X1_data isa Vector{ComplexF64}
+    @test isapprox(sv_X1_data, qo_X1_data)
+    @test length(sv_X1_data) == 2
+
+    # Test: Symbolic Operator (Z1) conversion
+    sym_Z1_test = QuantumSavory.Z1
+    qo_Z1_data = QuantumOptics.express(sym_Z1_test, QuantumOptics.QuantumOpticsRepr()).data
+    sv_Z1_data = express(sym_Z1_test, StateVectorRepr())
+    @test sv_Z1_data isa Matrix{ComplexF64}
+    @test isapprox(sv_Z1_data, qo_Z1_data)
+    @test size(sv_Z1_data) == (2, 2)
+
+    # Test: Product operator (X1 * Y2) conversion
+    sym_XY_test = QuantumSavory.X1 * QuantumSavory.Y2
+    qo_XY_data = QuantumOptics.express(sym_XY_test, QuantumOptics.QuantumOpticsRepr()).data
+    sv_XY_data = express(sym_XY_test, StateVectorRepr())
+    @test sv_XY_data isa Matrix{ComplexF64}
+    @test isapprox(sv_XY_data, qo_XY_data)
+    @test size(sv_XY_data) == (4, 4)
+
+    # Test: Bosonic operator (N) with custom cutoff
+    sym_N_test = QuantumSavory.N
+    qo_N_cutoff4_data = QuantumOptics.express(sym_N_test, QuantumOptics.QuantumOpticsRepr(cutoff=4)).data
+    sv_N_cutoff4_data = express(sym_N_test, StateVectorRepr(cutoff=4))
+    @test sv_N_cutoff4_data isa Matrix{ComplexF64}
+    @test isapprox(sv_N_cutoff4_data, qo_N_cutoff4_data)
+    @test size(sv_N_cutoff4_data) == (5, 5)
+end