update docstrings

README.md

@@ -44,14 +44,13 @@ $ julia j1j2.jl measure --help
 ## Documentations
 
 * paper: Variational Quantum Eigensolver with Fewer Qubits ([pdf]()), [arXiv:xxxxxx](https://arxiv.org/abs/xxxxxx), Jin-Guo Liu, Yihong Zhang, Yuan Wan and Lei Wang
-* slides: [online]()
 
 ## Citation
 
 You are welcome to use this code for your research. Please kindly cite:
 
 ```
-<arXiv citation>
+<arXiv preprint will release soon.>
 ```
 
 ## Authors

applications.jl

@@ -5,6 +5,7 @@ using DelimitedFiles, JLD2, FileIO, Pkg
 
 # CUDA switch
 const USE_CUDA = haskey(Pkg.installed(), "CuYao")
+if USE_CUDA && println("Using CUDA since `CuYao` is detected. Edit `applications.jl` file to modify CUDA settings, like switching computing devices.")
 USE_CUDA && include("CuChem.jl")
 USE_CUDA && device!(CuDevice(0))
 
@@ -61,8 +62,15 @@ end
 
 """
     run_train(ansatz, model; SAVE_ID, niter=500, start_point=0, save_step=0)
+
+Run a variational quantum eigensolver to solve a `model` Hamiltonian with MPS inspired `ansatz`
+
+* SAVE_ID, token used for saving data,
+* niter, number of training steps,
+* start_point, load a save point, default is 0 (random parameters).
+* save_step, save the training every `save_step` steps.
 """
-function run_train(ansatz, model; SAVE_ID, niter=500, start_point=0, save_step=10)
+function run_train(ansatz, model; SAVE_ID, niter::Int=500, start_point::Int=0, save_step::Int=10)
     nbit = nbit_simulated(ansatz)
     V = ansatz.nbit_virtual
     filename(k::Int) = "data/chem_$(SAVE_ID)_N$(nbit)_V$(V)_S$(k).jld2"

src/AbstractModel.jl

@@ -7,6 +7,8 @@ abstract type AbstractHeisenberg{D} <: AbstractModel{D} end
 nspin(model::AbstractModel) = prod(size(model))
 
 """
+    energy_exact(tc::QuantumMPS, model::AbstractModel) -> Float64
+
 Exact ground state energy.
 """
 function energy_exact(tc::QuantumMPS, model::AbstractModel)
@@ -15,6 +17,8 @@ function energy_exact(tc::QuantumMPS, model::AbstractModel)
 end
 
 """
+    energy(chem::QuantumMPS, model::AbstractHeisenberg) -> Float64
+
 Ground state energy by sampling Quantum MPS.
 The hamiltonian is limited to Heisenberg and J1J2 Type.
 """
@@ -31,13 +35,24 @@ function energy(chem::QuantumMPS, pauli::PauliGate, model::AbstractHeisenberg)
     eng/4
 end
 
+"""
+    ground_state(model::AbstractModel) -> DefaultRegister
+
+Get the exact ground state of a model.
+"""
 function ground_state(model::AbstractModel)
     # get the ground state
     hami = hamiltonian(model)
     E, v = eigsolve(mat(hami), 1, :SR)
     register(v[1])
 end
 
+"""
+    get_bonds(model::AbstractHeisenberg) -> Vector
+
+Get the weighted bonds of a Heisenberg model in the form Tuple(i,j,w_ij).
+"""
+function get_bonds end
 
 include("Heisenberg.jl")
 include("J1J2.jl")

src/J1J2.jl

@@ -1,5 +1,10 @@
 export J1J2
 
+"""
+    J1J2{D} <: AbstractHeisenberg{D}
+
+frustrated Heisenberg model.
+"""
 struct J1J2{D} <: AbstractHeisenberg{D}
     size::NTuple{D, Int}
     periodic::Bool

src/ansatz/su2_circuit.jl

@@ -2,6 +2,11 @@ function su2_unit(nbit::Int, i::Int, j::Int)
     put(nbit, (i,j)=>rot(SWAP, 0.0))
 end
 
+"""
+    su2_circuit(nbit_virtual::Int, nlayer::Int, nrepeat::Int, pairs::Vector) -> Sequence
+
+SU(2) symmetry quantum circuit ansatz for evolving states in S^2 = 0 good quantum number block. It requires `2+nbit_virtual` qubits, `pairs` is the geometry of entanglements.
+"""
 function su2_circuit(nbit_virtual::Int, nlayer::Int, nrepeat::Int, pairs::Vector)
     circuit = sequence()
     nbit_used = 2 + nbit_virtual
@@ -30,6 +35,7 @@ function su2_circuit(nbit_virtual::Int, nlayer::Int, nrepeat::Int, pairs::Vector
     dispatch!(circuit, :random)
 end
 
+"""construct a circuit for generating singlets."""
 function singlet_block(nbit::Int, i::Int, j::Int)
     unit = chain(nbit)
     push!(unit, put(nbit, i=>chain(X, H)))

src/ansatz/u1_circuit.jl

@@ -5,6 +5,11 @@ function u1_unit(nbit::Int, i::Int, j::Int)
     )
 end
 
+"""
+    u1_circuit(nbit_measure::Int, nbit_virtual::Int, nlayer::Int, nrepeat::Int, entangler_pairs) -> Sequence
+
+U(1) symmetric quantum circuit ansatz.
+"""
 function u1_circuit(nbit_measure::Int, nbit_virtual::Int, nlayer::Int, nrepeat::Int, entangler_pairs)
     circuit = sequence()
     nbit_used = nbit_measure + nbit_virtual