Merge pull request #35

Add struct Parity

docs/src/heom_matrix/HEOMLS_intro.md

@@ -50,28 +50,28 @@ M = M_Boson_Fermion(Hs, Btier, Ftier, Bbath, Fbath; threshold=1e-7)
     The full hierarchical equations can be recovered in the limiting case ``\mathcal{I}_\textrm{th}\rightarrow 0``, which is the default value of the parameter : `threshold=0.0`. This means that all of the ADOs will be taken into account by default.
 
 ## [Parity Support for HEOMLS Matrices](@id doc-Parity)
-When the system Hamiltonian contains fermionic systems, the HEOMLS matrix ``\hat{\mathcal{M}}`` might be constructed into a different one depend on the parity of the input operator (HEOMLS) it is acting on. Usually, it is acting on the reduced density operator and [auxiliary density operators (ADOs)](@ref doc-ADOs), which are all in `:even`-parity. However, there are some situations (for example, [calculating spectrum for fermionic systems](@ref doc-DOS)) where ``\hat{\mathcal{M}}`` is acting on ADOs with `:odd`-parity.
+When the system Hamiltonian contains fermionic systems, the HEOMLS matrix ``\hat{\mathcal{M}}`` might be constructed into a different one depend on the parity of the input operator (HEOMLS) it is acting on. Usually, it is acting on the reduced density operator and [auxiliary density operators (ADOs)](@ref doc-ADOs), which are all in `EVEN`-parity. However, there are some situations (for example, [calculating spectrum for fermionic systems](@ref doc-DOS)) where ``\hat{\mathcal{M}}`` is acting on ADOs with `ODD`-parity.
 
-One can specify the parameter `parity::Symbol` in the function of constructing ``\hat{\mathcal{M}}`` to be `:even` or `:odd`. The default value of the parameter is `parity=:even`.
+One can specify the parameter `parity::AbstractParity` in the function of constructing ``\hat{\mathcal{M}}`` to be [`EVEN`](@ref) or [`ODD`](@ref). The default value of the parameter is `parity=EVEN`.
 ```julia
 Hs::AbstractMatrix  # system Hamiltonian
 Bbath::BosonBath    # bosonic   bath object
 Fbath::FermionBath  # fermionic bath object
 Btier::Int          # bosonic   truncation level 
 Ftier::Int          # fermionic truncation level 
 
-# create HEOMLS matrix in :even or :odd parity
-M_even = M_S(Hs, :even)
-M_odd  = M_S(Hs, :odd)
+# create HEOMLS matrix in EVEN or ODD parity
+M_even = M_S(Hs, EVEN)
+M_odd  = M_S(Hs, ODD)
 
-M_even = M_Boson(Hs, Btier, Bbath, :even) 
-M_odd  = M_Boson(Hs, Btier, Bbath, :odd) 
+M_even = M_Boson(Hs, Btier, Bbath, EVEN) 
+M_odd  = M_Boson(Hs, Btier, Bbath, ODD) 
 
-M_even = M_Fermion(Hs, Ftier, Fbath, :even) 
-M_odd  = M_Fermion(Hs, Ftier, Fbath, :odd)
+M_even = M_Fermion(Hs, Ftier, Fbath, EVEN) 
+M_odd  = M_Fermion(Hs, Ftier, Fbath, ODD)
 
-M_even = M_Boson_Fermion(Hs, Btier, Ftier, Bbath, Fbath, :even) 
-M_odd  = M_Boson_Fermion(Hs, Btier, Ftier, Bbath, Fbath, :odd) 
+M_even = M_Boson_Fermion(Hs, Btier, Ftier, Bbath, Fbath, EVEN) 
+M_odd  = M_Boson_Fermion(Hs, Btier, Ftier, Bbath, Fbath, ODD) 
 ```
 
 ## Methods

docs/src/heom_matrix/M_Boson.md

@@ -10,7 +10,7 @@ To construct the HEOM matrix in this case, one can call
  - `Hsys` : The time-independent system Hamiltonian
  - `tier::Int` : the tier (cutoff level) for the bosonic bath
  - `Bath::Vector{BosonBath}` : objects for different [bosonic baths](@ref doc-Bosonic-Bath)
- - `parity::Symbol` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on. Defaults to `:even`.
+ - `parity::AbstractParity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on. Defaults to `EVEN`.
 
 *kwargs* (Keyword Arguments)
  - `threshold::Real` : The threshold of the [importance value](@ref doc-Importance-Value-and-Threshold). Defaults to `0.0`.
@@ -34,7 +34,7 @@ The fields of the structure [`M_Boson`](@ref) are as follows:
  - `dim` : the dimension of system
  - `N` : the number of total [ADOs](@ref doc-ADOs)
  - `sup_dim` : the dimension of system superoperator
- - `parity` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on.
+ - `parity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on.
  - `bath::Vector{BosonBath}` : the vector which stores all [`BosonBath`](@ref doc-Bosonic-Bath) objects
  - `hierarchy::HierarchyDict`: the object which contains all [dictionaries](@ref doc-Hierarchy-Dictionary) for boson-bath-ADOs hierarchy.
 

docs/src/heom_matrix/M_Boson_Fermion.md

@@ -12,7 +12,7 @@ To construct the HEOM matrix in this case, one can call
  - `Ftier::Int` : the tier (cutoff level) for the fermionic bath
  - `Bbath::Vector{BosonBath}` : objects for different [bosonic baths](@ref doc-Bosonic-Bath)
  - `Fbath::Vector{FermionBath}` : objects for different [fermionic baths](@ref doc-Fermionic-Bath)
- - `parity::Symbol` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on. Defaults to `:even`.
+ - `parity::AbstractParity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on. Defaults to `EVEN`.
 
 *kwargs* (Keyword Arguments)
  - `threshold::Real` : The threshold of the [importance value](@ref doc-Importance-Value-and-Threshold). Defaults to `0.0`.
@@ -26,9 +26,9 @@ Ftier = 4
 Bbath::BosonBath
 Fbath::FermionBath
 
-# create HEOMLS matrix in both :even and :odd parity
+# create HEOMLS matrix in both EVEN and ODD parity
 M_even = M_Fermion(Hs, Btier, Ftier, Bbath, Fbath) 
-M_odd  = M_Fermion(Hs, Btier, Ftier, Bbath, Fbath, :odd) 
+M_odd  = M_Fermion(Hs, Btier, Ftier, Bbath, Fbath, ODD) 
 ```
 
 ## Fields
@@ -39,7 +39,7 @@ The fields of the structure [`M_Boson_Fermion`](@ref) are as follows:
  - `dim` : the dimension of system
  - `N` : the number of total [ADOs](@ref doc-ADOs)
  - `sup_dim` : the dimension of system superoperator
- - `parity` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on.
+ - `parity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on. 
  - `Bbath::Vector{BosonBath}` : the vector which stores all [`BosonBath`](@ref doc-Bosonic-Bath) objects
  - `Fbath::Vector{FermionBath}` : the vector which stores all [`FermionBath`](@ref doc-Fermionic-Bath) objects
  - `hierarchy::MixHierarchyDict`: the object which contains all [dictionaries](@ref doc-Hierarchy-Dictionary) for mixed-bath-ADOs hierarchy.

docs/src/heom_matrix/M_Fermion.md

@@ -10,7 +10,7 @@ To construct the HEOM matrix in this case, one can call
  - `Hsys` : The time-independent system Hamiltonian
  - `tier::Int` : the tier (cutoff level) for the fermionic bath
  - `Bath::Vector{FermionBath}` : objects for different [fermionic baths](@ref doc-Fermionic-Bath)
- - `parity::Symbol` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on. Defaults to `:even`.
+ - `parity::AbstractParity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on. Defaults to `EVEN`.
 
 *kwargs* (Keyword Arguments)
  - `threshold::Real` : The threshold of the [importance value](@ref doc-Importance-Value-and-Threshold). Defaults to `0.0`.
@@ -34,7 +34,7 @@ The fields of the structure [`M_Fermion`](@ref) are as follows:
  - `dim` : the dimension of system
  - `N` : the number of total [ADOs](@ref doc-ADOs)
  - `sup_dim` : the dimension of system superoperator
- - `parity` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on.
+ - `parity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on.
  - `bath::Vector{FermionBath}` : the vector which stores all [`FermionBath`](@ref doc-Fermionic-Bath) objects
  - `hierarchy::HierarchyDict`: the object which contains all [dictionaries](@ref doc-Hierarchy-Dictionary) for fermion-bath-ADOs hierarchy.
 

docs/src/heom_matrix/master_eq.md

@@ -29,13 +29,13 @@ M1 = addBosonDissipator(M0, J)
 ```
 
 ## Fermionic Dissipative Env.
-If the fermionic system is weakly coupled to an extra fermionic environment, the explicit form of the Lindbladian acting on `:even`-parity operators is given by
+If the fermionic system is weakly coupled to an extra fermionic environment, the explicit form of the Lindbladian acting on `EVEN`-parity operators is given by
 ```math
 \hat{\mathcal{D}}_{\textrm{even}}(J)\Big[\cdot\Big]=J\left[\cdot\right]J^\dagger-\frac{1}{2}\Big[J^\dagger J, \cdot\Big]_+,
 ```
 where ``J\equiv \sqrt{\gamma}V`` is the jump operator, ``V`` describes the dissipative part (operator) of the dynamics, ``\gamma`` represents a non-negative damping rate and ``[\cdot, \cdot]_+`` stands for anti-commutator.
 
-For acting on `:odd`-parity operators, the explicit form of the Lindbladian is given by
+For acting on `ODD`-parity operators, the explicit form of the Lindbladian is given by
 ```math
 \hat{\mathcal{D}}_{\textrm{odd}}(J)\Big[\cdot\Big]=-J\left[\cdot\right]J^\dagger-\frac{1}{2}\Big[J^\dagger J, \cdot\Big]_+,
 ```
@@ -47,12 +47,12 @@ One can add the Lindbladian ``\hat{\mathcal{D}}`` of fermionic environment to th
  - `jumpOP::AbstractVector` : The list of collapse (jump) operators ``\{J_i\}_i`` to add. Defaults to empty vector `[]`.
 
 !!! note "Parity"
-    The parity of the dissipator will be automatically determined by the [parity](@ref doc-Parity) of the given HEOMLS matrix `M`.
+    The parity of the dissipator will be automatically determined by the [`parity`](@ref doc-Parity) of the given HEOMLS matrix `M`.
 
 Finally, the function returns a new ``\hat{\mathcal{M}}`` with the same type and parity:
 ```julia
-M0_even::AbstractHEOMLSMatrix # constructed with :even-parity
-M0_odd::AbstractHEOMLSMatrix  # constructed with :odd-parity
+M0_even::AbstractHEOMLSMatrix # constructed with EVEN-parity
+M0_odd::AbstractHEOMLSMatrix  # constructed with  ODD-parity
 J = [J1, J2, ..., Jn]  # jump operators
 
 M1_even = addFermionDissipator(M0_even, J)

docs/src/heom_matrix/schrodinger_eq.md

@@ -14,7 +14,7 @@ To construct the HEOM matrix for Schrödinger Equation, one can call
 
 *args* (Arguments)
  - `Hsys` : The time-independent system Hamiltonian
- - `parity::Symbol` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on. Defaults to `:even`.
+ - `parity::AbstractParity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on. Defaults to `EVEN`.
 *kwargs* (Keyword Arguments)
  - `verbose::Bool` : To display verbose output during the process or not. Defaults to `true`.
 
@@ -34,7 +34,7 @@ The fields of the structure [`M_S`](@ref) are as follows:
  - `dim` : the dimension of system
  - `N` : the number of total [ADOs](@ref doc-ADOs), which equals to `1` (only the reduced density operator) in this case
  - `sup_dim` : the dimension of system superoperator
- - `parity` : the [parity](@ref doc-Parity) label. This depends on the parity of the ADOs which the HEOMLS is acting on.
+ - `parity::AbstractParity` : the [parity](@ref doc-Parity) label of the operator which HEOMLS is acting on.
 
 One obtain the value of each fields as follows:
 ```julia

docs/src/libraryAPI.md

@@ -49,16 +49,24 @@ Fermion_Lorentz_Matsubara
 Fermion_Lorentz_Pade
 ```
 
+## Parity
+```@docs
+EvenParity
+OddParity
+EVEN
+ODD
+```
+
 ## HEOM Liouvillian superoperator matrices
 ```@docs
 M_S
-M_S(Hsys, parity::Symbol=:even; verbose::Bool=true)
+M_S(Hsys, parity::AbstractParity=EVEN; verbose::Bool=true)
 M_Boson
-M_Boson(Hsys, tier::Int, Bath::Vector{BosonBath}, parity::Symbol=:even; threshold::Real=0.0, verbose::Bool=true)
+M_Boson(Hsys, tier::Int, Bath::Vector{BosonBath}, parity::AbstractParity=EVEN; threshold::Real=0.0, verbose::Bool=true)
 M_Fermion
-M_Fermion(Hsys, tier::Int, Bath::Vector{FermionBath}, parity::Symbol=:even; threshold::Real=0.0, verbose::Bool=true)
+M_Fermion(Hsys, tier::Int, Bath::Vector{FermionBath}, parity::AbstractParity=EVEN; threshold::Real=0.0, verbose::Bool=true)
 M_Boson_Fermion
-M_Boson_Fermion(Hsys, tier_b::Int, tier_f::Int, Bath_b::Vector{BosonBath}, Bath_f::Vector{FermionBath}, parity::Symbol=:even; threshold::Real=0.0, verbose::Bool=true)
+M_Boson_Fermion(Hsys, tier_b::Int, tier_f::Int, Bath_b::Vector{BosonBath}, Bath_f::Vector{FermionBath}, parity::AbstractParity=EVEN; threshold::Real=0.0, verbose::Bool=true)
 size(M::AbstractHEOMLSMatrix)
 size(M::AbstractHEOMLSMatrix, dim::Int)
 eltype(M::AbstractHEOMLSMatrix)

docs/src/spectrum.md

@@ -6,8 +6,8 @@ We briefly summarize how to numerically compute the spectrum associated with the
 `HierarchicalEOM.jl` provides a function [`spectrum`](@ref) which performs the calculation in frequency domain. There are two different methods (as shown below) which depends on the [parity](@ref doc-Parity) of the HEOMLS matrices ``\hat{\mathcal{M}}`` corresponds to different system degree of freedom. 
 
 If you want to calculate the spectrum associated with
- - [bosonic systems (Power Spectral Density)](@ref doc-PSD) : you have to provide ``\hat{\mathcal{M}}`` constructed in `:even` parity.
- - [fermionic systems (Density of States)](@ref doc-DOS) : you have to provide ``\hat{\mathcal{M}}`` constructed in `:odd` parity.
+ - [bosonic systems (Power Spectral Density)](@ref doc-PSD) : you have to provide ``\hat{\mathcal{M}}`` constructed in `EVEN` parity.
+ - [fermionic systems (Density of States)](@ref doc-DOS) : you have to provide ``\hat{\mathcal{M}}`` constructed in `ODD` parity.
 
 The function [`spectrum`](@ref) will automatically detect the [parity](@ref doc-Parity) of ``\hat{\mathcal{M}}`` by itself. Furthermore, the output of the function [`spectrum`](@ref) for both cases will always be in the type of `Vector{Float64}`, which contains the list of the spectrum values corresponding to the given `ω_list`.
 
@@ -39,7 +39,7 @@ Finially, one can obtain the value of the power spectral density for specific ``
 See also the docstring : [`spectrum`](@ref)
 
 ```julia
-M::AbstractHEOMLSMatrix # need to be in ":even" parity
+M::AbstractHEOMLSMatrix # need to be in "EVEN" parity
 
 # the input state can be in either type (but usually ADOs):
 ρ::AbstractMatrix # the reduced density operator
@@ -54,7 +54,7 @@ a::AbstractMatrix
 πSω = spectrum(M, ρ, a, ω_list)
 ```
 !!! note "Note"
-    To calculate power spectral density, remember to construct ``\hat{\mathcal{M}}`` with `:even` parity.
+    To calculate power spectral density, remember to construct ``\hat{\mathcal{M}}`` with `EVEN` [parity](@ref doc-Parity).
 
 ## [Density of States](@id doc-DOS)
 Start from the spectrum for fermionic systems (density of states) in the time-domain. We write the system two-time correlation function in terms of the propagator ``\hat{\mathcal{G}}(t)=\exp(\hat{\mathcal{M}} t)`` for ``t>0``. The density of states ``A(\omega)`` can be obtained as
@@ -82,8 +82,8 @@ Finially, one can obtain the density of states for specific ``\omega``, namely
 ```
 
 !!! note "Odd-Parity for Density of States"
-    As shown above, the HEOMLS matrix ``\hat{\mathcal{M}}`` acts on the `:odd`-parity space, compatibly with the parity of both the operators ``d\rho^{(m,n,+)}_{\textbf{j} \vert \textbf{q}}`` and ``d^\dagger\rho^{(m,n,+)}_{\textbf{j} \vert \textbf{q}}``.  
-    Therefore, remember to construct ``\hat{\mathcal{M}}`` with `:odd` [parity](@ref doc-Parity) for solving spectrum of fermionic systems.
+    As shown above, the HEOMLS matrix ``\hat{\mathcal{M}}`` acts on the `ODD`-parity space, compatibly with the parity of both the operators ``d\rho^{(m,n,+)}_{\textbf{j} \vert \textbf{q}}`` and ``d^\dagger\rho^{(m,n,+)}_{\textbf{j} \vert \textbf{q}}``.  
+    Therefore, remember to construct ``\hat{\mathcal{M}}`` with `ODD` [parity](@ref doc-Parity) for solving spectrum of fermionic systems.
 
 See also the docstring : [`spectrum`](@ref)
 
@@ -92,9 +92,9 @@ Hs::AbstractMatrix # system Hamiltonian
 bath::FermionBath  # fermionic bath object
 tier::Int          # fermionic truncation level 
 
-# create HEOMLS matrix in both :even and :odd parity
+# create HEOMLS matrix in both :even and ODD parity
 M_even = M_Fermion(Hs, tier, bath) 
-M_odd  = M_Fermion(Hs, tier, bath, :odd) 
+M_odd  = M_Fermion(Hs, tier, bath, ODD) 
 
 # the input state can be in either type of density operator matrix or ADOs (but usually ADOs):
 ados = SteadyState(M_even)

examples/SIAM.jl

@@ -49,7 +49,7 @@ bath_list = [bath_up, bath_dn]
 # (see also [HEOMLS Matrix for Fermionic Baths](@ref doc-M_Fermion))
 tier = 3
 M_even = M_Fermion(Hsys, tier, bath_list)
-M_odd  = M_Fermion(Hsys, tier, bath_list, :odd)
+M_odd  = M_Fermion(Hsys, tier, bath_list, ODD)
 
 # ## Solve stationary state of ADOs
 # (see also [Stationary State](@ref doc-Stationary-State))

examples/benchmark_LS_solvers.jl

@@ -29,7 +29,7 @@ bath_up = Fermion_Lorentz_Pade(d_up, Γ, μ, W, kT, N)
 bath_dn = Fermion_Lorentz_Pade(d_dn, Γ, μ, W, kT, N)
 bath_list = [bath_up, bath_dn]
 M_even = M_Fermion(Hsys, tier, bath_list)
-M_odd  = M_Fermion(Hsys, tier, bath_list, :odd)
+M_odd  = M_Fermion(Hsys, tier, bath_list, ODD)
 ados_s = SteadyState(M_even);
 
 # ## LinearSolve Solver List

src/ADOs.jl

@@ -6,7 +6,7 @@ The Auxiliary Density Operators for HEOM model.
 - `data` : the vectorized auxiliary density operators
 - `dim` : the dimension of the system
 - `N` : the number of auxiliary density operators
-- `parity`: the parity label (`:even` or `:odd`).
+- `parity`: the parity label (`EVEN` or `ODD`).
 
 # Methods
 One can obtain the density matrix for specific index (`idx`) by calling : `ados[idx]`.
@@ -25,7 +25,7 @@ mutable struct ADOs
     data::SparseVector{ComplexF64, Int64}
     const dim::Int
     const N::Int
-    const parity::Symbol
+    const parity::AbstractParity
 end
 
 @doc raw"""
@@ -35,18 +35,14 @@ Gernerate the object of auxiliary density operators for HEOM model.
 # Parameters
 - `V::AbstractVector` : the vectorized auxiliary density operators
 - `N::Int` : the number of auxiliary density operators.
-- `parity::Symbol` : the parity label (`:even` or `:odd`). Default to `:even`.
+- `parity::AbstractParity` : the parity label (`EVEN` or `ODD`). Default to `EVEN`.
 """
-function ADOs(V::AbstractVector, N::Int, parity::Symbol=:even)
+function ADOs(V::AbstractVector, N::Int, parity::AbstractParity=EVEN)
     # check the dimension of V
     d  = size(V, 1)
     dim = √(d / N)
     if isinteger(dim)
-        if (parity == :even) || (parity == :odd)
-            return ADOs(sparsevec(V), Int(dim), N, parity)
-        else
-            error("The parity label should be either \":even\" or \":odd\".")
-        end
+        return ADOs(sparsevec(V), Int(dim), N, parity)
     else
         error("The dimension of vector is not consistent with the ADOs number \"N\".")
     end    
@@ -110,7 +106,7 @@ iterate(A::ADOs, ::Nothing) = nothing
 
 function show(io::IO, A::ADOs)
     print(io, 
-        "Auxiliary Density Operators with $(A.parity) parity, (system) dim = $(A.dim), number N = $(A.N)\n"
+        "Auxiliary Density Operators with $(A.parity), (system) dim = $(A.dim), number N = $(A.N)\n"
     )
 end
 function show(io::IO, m::MIME"text/plain", A::ADOs) show(io, A) end

src/HierarchicalEOM.jl

@@ -68,7 +68,7 @@ module HierarchicalEOM
 
         export
             AbstractHEOMLSMatrix, M_S, M_Boson, M_Fermion, M_Boson_Fermion,
-            odd, even,
+            AbstractParity, OddParity, EvenParity, value, ODD, EVEN,
             ADOs, getRho, getADO, Expect,
             Nvec, AbstractHierarchyDict, HierarchyDict, MixHierarchyDict, getIndexEnsemble,
             Propagator, addBosonDissipator, addFermionDissipator, addTerminator,
@@ -80,7 +80,7 @@ module HierarchicalEOM
 
     # sub-module Spectrum for HierarchicalEOM
     module Spectrum
-        import ..HeomAPI: AbstractHEOMLSMatrix, ADOs, spre
+        import ..HeomAPI: AbstractHEOMLSMatrix, OddParity, ADOs, spre
         import LinearAlgebra: I, kron
         import SparseArrays: sparse, sparsevec
         import LinearSolve: LinearProblem, init, solve!, UMFPACKFactorization