Improve deprecated functionality (#210)

Author: ytdHuang

src/deprecated.jl

@@ -1,26 +1,56 @@
 #=
 This file gathers all the deprecated names (structures, functions, or variables) which will be removed in the future major release.
 
-- Before the major release, the deprecated names will just throw errors when they are called.
+- Before the major release, the deprecated names will show warnings or just throw errors when they are called.
 - If the deprecated names were once exported, we will still export them here until next major release.
 - If we decide to push a major release, cleanup this file.
 
-Example:
-
+Example 1 [throw errors if the deprecation is fundamental, and there is no replacement for it]:
+```
 export deprecated_foo
+deprecated_foo(args...; kwargs...) = error("`deprecated_foo` is deprecated and will be removed in next major release.")
+```
+
+Example 2 ["force" show warning and tell the users that there is a replacement for the deprecated function]:
 
+```
+export deprecated_foo
 function deprecated_foo(args...; kwargs...)
-    error("`deprecated_foo` has been deprecated and will be removed in next major release, please use `new_foo` instead.")
+    Base.depwarn("`deprecated_foo` is deprecated and will be removed in next major release, use `new_foo` instead.", :deprecated_foo, force = true)
+    new_foo(args...; kwargs...)
 end
+```
 =#
 
-export evolution, SteadyState, C
-
-SteadyState(args...; kwargs...) = error("`SteadyState` has been deprecated, please use `steadystate` instead.")
+export SteadyState
+function SteadyState(args...; kwargs...)
+    Base.depwarn(
+        "`SteadyState` is deprecated and will be removed in next major release, use `steadystate` instead.",
+        :SteadyState,
+        force = true,
+    )
+    return steadystate(args...; kwargs...)
+end
 
-evolution(args...; kwargs...) = error("`evolution` has been deprecated, please use `HEOMsolve` instead.")
+export evolution
+function evolution(args...; kwargs...)
+    Base.depwarn(
+        "`evolution` is deprecated and will be removed in next major release, use `HEOMsolve` instead.",
+        :evolution,
+        force = true,
+    )
+    return HEOMsolve(args...; kwargs...)
+end
 
-C(args...; kwargs...) = error("`C` has been deprecated, please use `correlation_function` instead.")
+export C
+function C(args...)
+    Base.depwarn(
+        "`C` is deprecated and will be removed in next major release, use `correlation_function` instead.",
+        :C,
+        force = true,
+    )
+    return correlation_function(args...)
+end
 
 _HEOMSuperOp_deprecated_method_error() = error(
     "Specifying `mul_basis = \"L\", \"R\", or \"LR\"` to `HEOMSuperOp` has been deprecated, try to construct system SuperOperator manually by using `spre`, `spost`, or `sprepost`.",

src/heom_matrices/HierarchyDict.jl

@@ -288,7 +288,7 @@ Here is an example to use [`Bath`](@ref lib-Bath), [`Exponent`](@ref), [`Hierarc
 ```julia
 L::M_Fermion;          # suppose this is a fermion type of HEOM Liouvillian superoperator matrix you create
 HDict = L.hierarchy;   # the hierarchy dictionary
-ados = SteadyState(L); # the stationary state (ADOs) for L 
+ados = steadystate(L); # the stationary state (ADOs) for L 
 
 # Let's consider all the ADOs for first level
 idx_list = HDict.lvl2idx[1];

test/bath.jl

@@ -42,7 +42,7 @@
     types = ["bRI", "bRI", "bR", "bR", "bI", "bI", "bI"]
     @test length(b) == 7
     @test correlation_function(b, 0.183183)[1] ≈ correlation_function(bs, [0.183183])[1]
-    @test_throws ErrorException C(bs, [0.183183])
+    @test_logs (:warn,) C(bs, [0.183183]) # deprecated function
 
     ## check for η and γ list, and coupling operator
     η = Vector{ComplexF64}(undef, length(b))
@@ -82,7 +82,7 @@
     types = ["bA", "bA", "bA", "bA", "bA", "bE", "bE", "bE", "bE", "bE"]
     @test length(bs) == 10
     cp, cm = correlation_function(b, 0.183183)
-    @test_throws ErrorException C(b, [0.183183])
+    @test_logs (:warn,) C(b, [0.183183]) # deprecated function
     @test cp[1] ≈ 22.384506765987076 + 0.7399082821797519im
     @test cm[1] ≈ 26.994911851482776 - 0.799138487523946im
 
@@ -136,7 +136,7 @@
     types = ["fA", "fA", "fA", "fA", "fA", "fE", "fE", "fE", "fE", "fE"]
     @test length(b) == 10
     cp, cm = correlation_function(b, 0.183183)
-    @test_throws ErrorException C(b, [0.183183])
+    @test_logs (:warn,) C(b, [0.183183]) # deprecated function
     @test cp[1] ≈ 22.384506765987076 + 0.7399082821797519im
     @test cm[1] ≈ 26.994911851482776 - 0.799138487523946im
     for (i, e) in enumerate(b)

test/stationary_state.jl

@@ -30,8 +30,8 @@
     mat = Qobj(zeros(ComplexF64, 2, 2))
     mat2 = Qobj(zeros(ComplexF64, 3, 3))
     bathf = Fermion_Lorentz_Pade(mat, 1, 1, 1, 1, 2)
-    @test_throws ErrorException SteadyState(L)
-    @test_throws ErrorException SteadyState(L, ψ0)
+    @test_logs (:warn,) SteadyState(L) # deprecated function
+    @test_logs (:warn,) SteadyState(L, ψ0) # deprecated function
     @test_throws ErrorException steadystate(M_Fermion(mat, 2, bathf, ODD; verbose = false))
     @test_throws ErrorException steadystate(M_Fermion(mat, 2, bathf, ODD; verbose = false), mat)
     @test_throws ErrorException steadystate(L, mat2)

test/time_evolution.jl

@@ -33,7 +33,7 @@
     ρ_list_p = getRho.(ados_list)
     @test show(devnull, MIME("text/plain"), sol_p) === nothing
     @test length(sol_p.ados) == 1
-    @test_throws ErrorException evolution(L, ψ0, Δt, steps; verbose = false)
+    @test_logs (:warn,) evolution(L, ψ0, Δt, steps; verbose = false) # deprecated function
     @test_throws ErrorException heomsolve(L, ρ_wrong, Δt, steps; verbose = false)
     @test_throws ErrorException heomsolve(L, ados_wrong1, Δt, steps; verbose = false)
     @test_throws ErrorException heomsolve(L, ados_wrong2, Δt, steps; verbose = false)
@@ -46,7 +46,7 @@
     ρ_list_e = getRho.(sol_e.ados)
     expvals_e = sol_e.expect
     @test show(devnull, MIME("text/plain"), sol_e) === nothing
-    @test_throws ErrorException evolution(L, ψ0, tlist; progress_bar = Val(false))
+    @test_logs (:warn,) evolution(L, ψ0, tlist; progress_bar = Val(false)) # deprecated function
     @test_throws ErrorException heomsolve(L, ψ0, tlist; verbose = true)
     @test_throws ErrorException heomsolve(L, ψ0, tlist; filename = "test")
     @test_throws DimensionMismatch heomsolve(L, ρ_wrong, tlist; progress_bar = Val(false))