introduce field dimensions, and property dims (#361)

Author: ytdHuang

docs/src/resources/api.md

@@ -11,6 +11,9 @@ CurrentModule = QuantumToolbox
 ## [Quantum object (Qobj) and type](@id doc-API:Quantum-object-and-type)
 
 ```@docs
+Space
+Dimensions
+GeneralDimensions
 AbstractQuantumObject
 BraQuantumObject
 Bra

docs/src/tutorials/lowrank.md

@@ -41,7 +41,7 @@ M = latt.N + 1       # Number of states in the LR basis
 Define lr states. Take as initial state all spins up. All other N states are taken as those with miniman Hamming distance to the initial state.
 
 ```@example lowrank
-ϕ = Vector{QuantumObject{Vector{ComplexF64},KetQuantumObject,M-1}}(undef, M)
+ϕ = Vector{QuantumObject{Vector{ComplexF64},KetQuantumObject,Dimensions{M-1}}}(undef, M)
 ϕ[1] = kron(fill(basis(2, 1), N_modes)...)
 
 i = 1

ext/QuantumToolboxCUDAExt.jl

@@ -10,58 +10,59 @@ import SparseArrays: SparseVector, SparseMatrixCSC
 
 If `A.data` is a dense array, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CuArray` for gpu calculations.
 """
-CuArray(A::QuantumObject{Tq}) where {Tq<:Union{Vector,Matrix}} = QuantumObject(CuArray(A.data), A.type, A.dims)
+CuArray(A::QuantumObject{Tq}) where {Tq<:Union{Vector,Matrix}} = QuantumObject(CuArray(A.data), A.type, A._dims)
 
 @doc raw"""
     CuArray{T}(A::QuantumObject)
 
 If `A.data` is a dense array, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CuArray` with element type `T` for gpu calculations.
 """
-CuArray{T}(A::QuantumObject{Tq}) where {T,Tq<:Union{Vector,Matrix}} = QuantumObject(CuArray{T}(A.data), A.type, A.dims)
+CuArray{T}(A::QuantumObject{Tq}) where {T,Tq<:Union{Vector,Matrix}} = QuantumObject(CuArray{T}(A.data), A.type, A._dims)
 
 @doc raw"""
     CuSparseVector(A::QuantumObject)
 
 If `A.data` is a sparse vector, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CUSPARSE.CuSparseVector` for gpu calculations.
 """
-CuSparseVector(A::QuantumObject{<:SparseVector}) = QuantumObject(CuSparseVector(A.data), A.type, A.dims)
+CuSparseVector(A::QuantumObject{<:SparseVector}) = QuantumObject(CuSparseVector(A.data), A.type, A._dims)
 
 @doc raw"""
     CuSparseVector{T}(A::QuantumObject)
 
 If `A.data` is a sparse vector, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CUSPARSE.CuSparseVector` with element type `T` for gpu calculations.
 """
-CuSparseVector{T}(A::QuantumObject{<:SparseVector}) where {T} = QuantumObject(CuSparseVector{T}(A.data), A.type, A.dims)
+CuSparseVector{T}(A::QuantumObject{<:SparseVector}) where {T} =
+    QuantumObject(CuSparseVector{T}(A.data), A.type, A._dims)
 
 @doc raw"""
     CuSparseMatrixCSC(A::QuantumObject)
 
 If `A.data` is in the type of `SparseMatrixCSC`, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CUSPARSE.CuSparseMatrixCSC` for gpu calculations.
 """
-CuSparseMatrixCSC(A::QuantumObject{<:SparseMatrixCSC}) = QuantumObject(CuSparseMatrixCSC(A.data), A.type, A.dims)
+CuSparseMatrixCSC(A::QuantumObject{<:SparseMatrixCSC}) = QuantumObject(CuSparseMatrixCSC(A.data), A.type, A._dims)
 
 @doc raw"""
     CuSparseMatrixCSC{T}(A::QuantumObject)
 
 If `A.data` is in the type of `SparseMatrixCSC`, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CUSPARSE.CuSparseMatrixCSC` with element type `T` for gpu calculations.
 """
 CuSparseMatrixCSC{T}(A::QuantumObject{<:SparseMatrixCSC}) where {T} =
-    QuantumObject(CuSparseMatrixCSC{T}(A.data), A.type, A.dims)
+    QuantumObject(CuSparseMatrixCSC{T}(A.data), A.type, A._dims)
 
 @doc raw"""
     CuSparseMatrixCSR(A::QuantumObject)
 
 If `A.data` is in the type of `SparseMatrixCSC`, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CUSPARSE.CuSparseMatrixCSR` for gpu calculations.
 """
-CuSparseMatrixCSR(A::QuantumObject{<:SparseMatrixCSC}) = QuantumObject(CuSparseMatrixCSR(A.data), A.type, A.dims)
+CuSparseMatrixCSR(A::QuantumObject{<:SparseMatrixCSC}) = QuantumObject(CuSparseMatrixCSR(A.data), A.type, A._dims)
 
 @doc raw"""
     CuSparseMatrixCSR(A::QuantumObject)
 
 If `A.data` is in the type of `SparseMatrixCSC`, return a new [`QuantumObject`](@ref) where `A.data` is in the type of `CUDA.CUSPARSE.CuSparseMatrixCSR` with element type `T` for gpu calculations.
 """
 CuSparseMatrixCSR{T}(A::QuantumObject{<:SparseMatrixCSC}) where {T} =
-    QuantumObject(CuSparseMatrixCSR{T}(A.data), A.type, A.dims)
+    QuantumObject(CuSparseMatrixCSR{T}(A.data), A.type, A._dims)
 
 @doc raw"""
     cu(A::QuantumObject; word_size::Int=64)

src/correlations.jl

@@ -51,8 +51,7 @@ function correlation_3op_2t(
         ψ0 = steadystate(L)
     end
 
-    allequal((L.dims, ψ0.dims, A.dims, B.dims, C.dims)) ||
-        throw(DimensionMismatch("The quantum objects are not of the same Hilbert dimension."))
+    check_dimensions(L, ψ0, A, B, C)
 
     kwargs2 = merge((saveat = collect(tlist),), (; kwargs...))
     ρt_list = mesolve(L, ψ0, tlist; kwargs2...).states
@@ -137,7 +136,7 @@ function correlation_2op_2t(
     HOpType<:Union{OperatorQuantumObject,SuperOperatorQuantumObject},
     StateOpType<:Union{KetQuantumObject,OperatorQuantumObject},
 }
-    C = eye(prod(H.dims), dims = H.dims)
+    C = eye(prod(H.dimensions), dims = H.dimensions)
     if reverse
         corr = correlation_3op_2t(H, ψ0, tlist, τlist, c_ops, A, B, C; kwargs...)
     else

src/negativity.jl

@@ -39,7 +39,7 @@ julia> round(negativity(ρ, 2), digits=2)
 ```
 """
 function negativity(ρ::QuantumObject, subsys::Int; logarithmic::Bool = false)
-    mask = fill(false, length(ρ.dims))
+    mask = fill(false, length(ρ.dimensions))
     try
         mask[subsys] = true
     catch
@@ -68,17 +68,17 @@ Return the partial transpose of a density matrix ``\rho``, where `mask` is an ar
 # Returns
 - `ρ_pt::QuantumObject`: The density matrix with the selected subsystems transposed.
 """
-function partial_transpose(ρ::QuantumObject{T,OperatorQuantumObject}, mask::Vector{Bool}) where {T}
-    if length(mask) != length(ρ.dims)
+function partial_transpose(ρ::QuantumObject{DT,OperatorQuantumObject}, mask::Vector{Bool}) where {DT}
+    if length(mask) != length(ρ.dimensions)
         throw(ArgumentError("The length of \`mask\` should be equal to the length of \`ρ.dims\`."))
     end
     return _partial_transpose(ρ, mask)
 end
 
 # for dense matrices
-function _partial_transpose(ρ::QuantumObject{<:AbstractArray,OperatorQuantumObject}, mask::Vector{Bool})
-    isa(ρ.dims, CompoundDimensions) &&
-        (ρ.to != ρ.from) &&
+function _partial_transpose(ρ::QuantumObject{DT,OperatorQuantumObject}, mask::Vector{Bool}) where {DT<:AbstractArray}
+    isa(ρ.dimensions, GeneralDimensions) &&
+        (get_dimensions_to(ρ) != get_dimensions_from(ρ)) &&
         throw(ArgumentError("Invalid partial transpose for dims = $(ρ.dims)"))
 
     mask2 = [1 + Int(i) for i in mask]
@@ -87,27 +87,27 @@ function _partial_transpose(ρ::QuantumObject{<:AbstractArray,OperatorQuantumObj
     #   2 - the subsystem need be transposed
 
     nsys = length(mask2)
-    dimslist = dims_to_list(ρ.to)
+    dims = dimensions_to_dims(get_dimensions_to(ρ))
     pt_dims = reshape(Vector(1:(2*nsys)), (nsys, 2))
     pt_idx = [
-        [pt_dims[n, mask2[n]] for n in 1:nsys] # origin   value in mask2
-        [pt_dims[n, 3-mask2[n]] for n in 1:nsys]  # opposite value in mask2 (1 -> 2, and 2 -> 1)
+        [pt_dims[n, mask2[n]] for n in 1:nsys]   # origin   value in mask2
+        [pt_dims[n, 3-mask2[n]] for n in 1:nsys] # opposite value in mask2 (1 -> 2, and 2 -> 1)
     ]
     return QuantumObject(
-        reshape(permutedims(reshape(ρ.data, (dimslist..., dimslist...)), pt_idx), size(ρ)),
+        reshape(permutedims(reshape(ρ.data, (dims..., dims...)), pt_idx), size(ρ)),
         Operator,
-        Dimensions(ρ.dims.to),
+        Dimensions(ρ.dimensions.to),
     )
 end
 
 # for sparse matrices
 function _partial_transpose(ρ::QuantumObject{<:AbstractSparseArray,OperatorQuantumObject}, mask::Vector{Bool})
-    isa(ρ.dims, CompoundDimensions) &&
-        (ρ.to != ρ.from) &&
+    isa(ρ.dimensions, GeneralDimensions) &&
+        (get_dimensions_to(ρ) != get_dimensions_from(ρ)) &&
         throw(ArgumentError("Invalid partial transpose for dims = $(ρ.dims)"))
 
     M, N = size(ρ)
-    dimsTuple = Tuple(dims_to_list(ρ.to))
+    dimsTuple = Tuple(dimensions_to_dims(get_dimensions_to(ρ)))
     colptr = ρ.data.colptr
     rowval = ρ.data.rowval
     nzval = ρ.data.nzval
@@ -139,5 +139,5 @@ function _partial_transpose(ρ::QuantumObject{<:AbstractSparseArray,OperatorQuan
         end
     end
 
-    return QuantumObject(sparse(I_pt, J_pt, V_pt, M, N), Operator, ρ.dims)
+    return QuantumObject(sparse(I_pt, J_pt, V_pt, M, N), Operator, ρ.dimensions)
 end