Introduce show for TimeEvolutionSol and TimeEvolutionMCSol, also, adjust return states and expect from sesolve, mesolve, and mcsolve

[ytdHuang]

close #143

Summary of this PR:

1. Adjust many docstrings for time evolution functions (add @doc raw, LaTeX formula, and some minor changes)
2. Introduce show for TimeEvolutionSol and TimeEvolutionMCSol: take the brief example in README, here is the output if we show (or print) sol directly:

julia> sol = mesolve(H, ψ0, tlist, c_ops, e_ops = e_ops)
Solution of time evolution
(return code: Success)
--------------------------
num_states = 1
num_expect = 1
ODE alg.: Tsit5(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, thread = static(false),)
abstol = 1.0e-7
reltol = 1.0e-5

3. Adjust the return data for sesolve, mesolve, and mcsolve

For the current implementation, the users will only get a final state if they doesn't specify e_ops, which cause some ambiguity about the argument t_l. In this PR, the expect will be decide by the argument e_ops, and the states will be decide by the argument saveat:

• if the user specifies only e_ops: saveat = [t_l[end]], thus, return expectation values and the final state (which is same as current implementation)
• if the user doesn't specifies e_ops: saveat = t_l, thus, return all the states corresponding to t_l
• if the user specifies e_ops and saveat at the same time: expect will depend on e_ops, and states will depend on saveat.

Again, take the brief example in README:

if user doesn't specify e_ops:

julia> sol = mesolve(H, ψ0, tlist, c_ops)
Solution of time evolution
(return code: Success)
--------------------------
num_states = 100
num_expect = 0
ODE alg.: Tsit5(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, thread = static(false),)
abstol = 1.0e-7
reltol = 1.0e-5

if user specifies both e_ops and saveat:

julia> sol = mesolve(H, ψ0, tlist, c_ops, e_ops = e_ops, saveat = tlist)
Solution of time evolution
(return code: Success)
--------------------------
num_states = 100
num_expect = 1
ODE alg.: Tsit5(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, thread = static(false),)
abstol = 1.0e-7
reltol = 1.0e-5

julia> sol = mesolve(H, ψ0, tlist, c_ops, e_ops = e_ops, saveat = [])
Solution of time evolution
(return code: Success)
--------------------------
num_states = 0
num_expect = 1
ODE alg.: Tsit5(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, thread = static(false),)
abstol = 1.0e-7
reltol = 1.0e-5

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 93.22%. Comparing base (08e9772) to head (8763a20).
Report is 5 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #166      +/-   ##
==========================================
+ Coverage   93.10%   93.22%   +0.11%     
==========================================
  Files          28       28              
  Lines        2017     2051      +34     
==========================================
+ Hits         1878     1912      +34     
  Misses        139      139              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[albertomercurio]

Ok, yes. It makes sense that, when e_ops is empty, then it returns the states, yes. By the way, in the last example you made, I think that we should avoid to use save at=[]. As far as I remember, the option saveat = [] will return all the states at each time step (different from t_l). See, e.g., the documentation.

[albertomercurio]

Does it also work for mcsolve? It should call sesolveProblem at some point, so I would say yes.

[ytdHuang]

Ok, yes. It makes sense that, when e_ops is empty, then it returns the states, yes. By the way, in the last example you made, I think that we should avoid to use save at=[]. As far as I remember, the option saveat = [] will return all the states at each time step (different from t_l). See, e.g., the documentation.

The default of saveat will only be either [t_l[end]] or t_l.
It's just that we provide a degree of freedom for users to specify the saveat.
For example, saving both expectation values and all states:

sol = mesolve(H, ψ0, tlist, c_ops, e_ops = e_ops, saveat = tlist)

Yes, I understand that we should avoid saveat = [].

But I think no one will do this if we don't talk about it lol.

[ytdHuang]

some outputs of show function for TimeEvolutionMCSol:

(again, take Brief example in README as demonstration):

(without specifying e_ops)

sol = mcsolve(H, ψ0, tlist, c_ops, n_traj = 2)

Solution of quantum trajectories
(converged: true)
--------------------------------
num_trajectories = 2
num_states = 100
num_expect = 0
ODE alg.: Tsit5(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, thread = static(false),)
abstol = 1.0e-7
reltol = 1.0e-5

(specify e_ops)

sol = mcsolve(H, ψ0, tlist, c_ops, n_traj = 2, e_ops = e_ops)

Solution of quantum trajectories
(converged: true)
--------------------------------
num_trajectories = 2
num_states = 1
num_expect = 1
ODE alg.: Tsit5(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, thread = static(false),)
abstol = 1.0e-7
reltol = 1.0e-5

(specify both saveat and e_ops)

sol = mcsolve(H, ψ0, tlist, c_ops, n_traj = 2, e_ops = e_ops, saveat = tlist)

Solution of quantum trajectories
(converged: true)
--------------------------------
num_trajectories = 2
num_states = 100
num_expect = 1
ODE alg.: Tsit5(; stage_limiter! = trivial_limiter!, step_limiter! = trivial_limiter!, thread = static(false),)
abstol = 1.0e-7
reltol = 1.0e-5

[ytdHuang]

I've added the handling for unsupported keyword argument save_idxs, and also the corresponding runtests.