Updated docstrings for ground state functions

docs/source/api_doc.rst

@@ -1,5 +1,5 @@
-Module documentation
-====================
+API documentation of kitaev_clusters
+=============================
 
 symmetry_functions module
 -------------------------
@@ -12,3 +12,9 @@ hamiltonian_functions module
 
 .. automodule:: kitaev_clusters.hamiltonian_functions
    :members:
+
+ground_state_functions module
+-------------------------
+
+.. automodule:: kitaev_clusters.ground_state_functions
+   :members:

docs/source/index.rst

@@ -1,7 +1,13 @@
-kitaev_clusters Documentation
-=============================
+kitaev_clusters
+===============
 
-Brief Overview
+Welcome to the documentation for the **kitaev_clusters** library. Here you can find:
+
+* An overview of the library with reference paper
+* Package structure, requirements, and installation guide
+* API documentation of the **kitaev_clusters** library
+
+Overview
 --------------
 
 **kitaev_clusters** is a Python package designed for efficient Exact Diagonalization of the spin-1 Kitaev honeycomb model on finite-size clusters.
@@ -17,9 +23,9 @@ Package Structure
 -----------------
 * **kitaev_clusters** contains the main code files. The main modules are:
 
-    1. symmetry_functions: a collection of functions which use lattice symmetries to reduce the effective Hilbert space dimension.
-    2. hamiltonian_functions: a collection of functions for efficient construction of the sparse matrix Hamiltonian.
-    3. ground_state_functions: a collection functions for obtaining ground states and measuring physical quantities.
+ 1. symmetry_functions: a collection of functions which use lattice symmetries to reduce the effective Hilbert space dimension.
+ 2. hamiltonian_functions: a collection of functions for efficient construction of the sparse matrix Hamiltonian.
+ 3. ground_state_functions: a collection functions for obtaining ground states and measuring physical quantities.
 * **scripts** contains example scripts showing how the library can be used.
 * **docs** contains documentation files.
 * **tests** contains units tests of functions using the pytest framework.
@@ -46,8 +52,8 @@ Units tests can be run using pytest after installation. Install pytest if needed
 
 
 Module Documentation
-==================
-Here you can find documentation for each function in the main modules:
+====================
+Here you can find API documentation for each function in the main modules:
 
 .. toctree::
    :maxdepth: 2

kitaev_clusters/ground_state_functions.py

@@ -8,6 +8,30 @@
 
 def ground_state(H, L, k=1, ncv=20):
 
+    """
+    Finds the ground state psi_0 and the ground state energy E_0, by applying Lanczos algorithm to matrix Hamiltonian H.
+
+    Parameters
+    ----------
+    H : csr_matrix or lil_matrix
+        The full sparse matrix Hamiltonian.
+    L : int
+        The total number of lattice sites. Used to calculate the energy per site.
+    k : int, optional
+        Number of eigenvalues and eigenvectors desired. By default k=1 to find state only.
+    ncv : int, optional
+        Number of Lanczos vectors generated.
+
+
+    Returns
+    -------
+    E_0 : float
+        The ground state energy per site.
+    psi_0 : ndarray
+        The ground state, i.e. a 1d array with ndim complex coefficients.
+
+    """
+
     E, V = scipy.sparse.linalg.eigsh(H, k=k, which="SA", return_eigenvectors=True, ncv=ncv)
 
     # Get ground state energy per site (i.e. divide by L) and corresponding eigenvector
@@ -21,14 +45,59 @@ def ground_state(H, L, k=1, ncv=20):
 
 def s_squared(HD, L, psi_0):
 
+    """
+    Finds the expectation value of (Sx + Sy + Sz)^2 in the ground state (per site).
+
+    Parameters
+    ----------
+    HD : csr_matrix or lil_matrix
+        The sparse matrix HD corresponding to the single-ion anisotropy term in the Hamiltonian.
+    L : int
+        The total number of lattice sites. Used to calculate <(Sx + Sy + Sz)^2> per site.
+    psi_0 : ndarray
+        The ground state, i.e. a 1d array with ndim complex coefficients.
+
+
+    Returns
+    -------
+    Ss: float
+        The expectation value of (Sx + Sy + Sz)^2 in the ground state (per site).
+
+    """
+
     Ss = np.transpose(np.conjugate(psi_0)) @ HD @ psi_0
 
     Ss = np.real(Ss) / L  # Value per site
 
     return Ss
 
 
-def entanglement_entropy(L, psi, kept_ints, state_map, n_unique_list):
+def entanglement_entropy(L, psi, state_map, n_unique_list):
+
+    """
+    Finds the bipartite entanglement entropy when the system is divided into two equal halves. Performs a
+    singular value decomposition (SVD) to obtain the singular values.
+
+    Parameters
+    ----------
+    L : int
+        The total number of lattice sites. Used to calculate <(Sx + Sy + Sz)^2> per site.
+    psi : ndarray
+        The state of the system, i.e. a 1d array with ndim complex coefficients. Typically the ground state psi_0.
+    state_map : ndarray
+        An array containing the representative state (in base-10) for each of the 3^L possible states. This is
+        the second value returned by the function get_representative_states.
+    n_unique_list : ndarray
+        An array containing the number of unique mirror states for each representative state. This is the third value
+        returned by the function get_representative_states.
+
+
+    Returns
+    -------
+    entropy: float
+        The bipartite entanglement entropy when the system is divided into two equal halves.
+
+    """
 
     M_dim = 3**(L//2)