add documentation in source codes

Author: k-yoshimi

src/hwave/dos.py

@@ -9,19 +9,54 @@
 
 
 class DoS:
+    """
+    A class to represent the Density of States (DoS).
+
+    Attributes
+    ----------
+    dos : np.ndarray
+        The density of states array.
+    ene : np.ndarray
+        The energy levels array.
+    ene_num : int
+        The number of energy levels.
+    norb : int
+        The number of orbitals.
+    """
+
     dos: np.ndarray
     ene: np.ndarray
     ene_num: int
     norb: int
 
     def __init__(self, ene: np.ndarray, dos: np.ndarray):
+        """
+        Initialize the DoS object.
+
+        Parameters
+        ----------
+        ene : np.ndarray
+            The energy levels array.
+        dos : np.ndarray
+            The density of states array.
+        """
         assert ene.shape[0] == dos.shape[1]
         self.ene = ene
         self.dos = dos
         self.ene_num = ene.shape[0]
         self.norb = dos.shape[0]
 
     def plot(self, filename: str = "", verbose: bool = False):
+        """
+        Plot the density of states.
+
+        Parameters
+        ----------
+        filename : str, optional
+            The filename to save the plot (default is "").
+        verbose : bool, optional
+            If True, print additional information (default is False).
+        """
         try:
             import matplotlib.pyplot as plt
         except ImportError:
@@ -45,6 +80,16 @@ def plot(self, filename: str = "", verbose: bool = False):
         plt.close()
 
     def write_dos(self, output: str, verbose: bool = False):
+        """
+        Write the density of states to a file.
+
+        Parameters
+        ----------
+        output : str
+            The output filename.
+        verbose : bool, optional
+            If True, print additional information (default is False).
+        """
         if verbose:
             print("Writing DOS to file: ", output)
         total_dos = np.sum(self.dos, axis=0)
@@ -60,21 +105,51 @@ def write_dos(self, output: str, verbose: bool = False):
                     fw.write("{:15.8f} ".format(self.dos[j, i]))
                 fw.write("\n")
 
-
 def __read_geom(file_name="./dir-model/zvo_geom.dat"):
+    """
+    Read the geometry from a file.
+
+    Parameters
+    ----------
+    file_name : str, optional
+        The filename to read the geometry from (default is "./dir-model/zvo_geom.dat").
+
+    Returns
+    -------
+    np.ndarray
+        A 3x3 array representing the geometry.
+    """
     with open(file_name, "r") as fr:
         uvec = np.zeros((3, 3))
         for i, line in enumerate(itertools.islice(fr, 3)):  # take first 3 lines
             uvec[i, :] = np.array(line.split())
     return uvec
 
-
 def calc_dos(
     input_dict: dict,
     ene_window: list | None = None,
     ene_num: int = 101,
     verbose: bool = False,
 ) -> DoS:
+    """
+    Calculate the density of states (DoS).
+
+    Parameters
+    ----------
+    input_dict : dict
+        Dictionary containing input parameters and file paths.
+    ene_window : list, optional
+        List containing the energy window [ene_low, ene_high]. If None, defaults to [ene_min - 0.2, ene_max + 0.2].
+    ene_num : int, optional
+        Number of energy points (default is 101).
+    verbose : bool, optional
+        If True, print additional information (default is False).
+
+    Returns
+    -------
+    DoS
+        An instance of the DoS class containing the calculated density of states.
+    """
     try:
         import libtetrabz
     except ImportError:

src/hwave/qlms.py

@@ -16,6 +16,16 @@
 from requests.structures import CaseInsensitiveDict
 
 def run(*, input_dict: Optional[dict] = None, input_file: Optional[str] = None):
+    """
+    Run the main process with the given input dictionary or input file.
+
+    Parameters:
+    input_dict (Optional[dict]): A dictionary containing input parameters.
+    input_file (Optional[str]): A path to a TOML file containing input parameters.
+
+    Raises:
+    RuntimeError: If neither input_dict nor input_file is provided, or if both are provided.
+    """
     if input_dict is None:
         if input_file is None:
             raise RuntimeError("Neither input_dict nor input_file are passed")

src/hwave/qlmsio/read_input.py

@@ -7,8 +7,20 @@
 
 
 class QLMSInput():
+    """
+    Class to handle QLMS input files and parameters.
+    """
+
     valid_namelist = ["trans", "coulombinter", "coulombintra", "pairhop", "hund", "exchange", "ising", "pairlift", "interall", "initial", "onebodyg"]
+
     def __init__(self, file_name_list, solver_type="UHFr"):
+        """
+        Initialize the QLMSInput class.
+
+        Parameters:
+        file_name_list (dict): Dictionary of file names.
+        solver_type (str): Type of solver to use. Default is "UHFr".
+        """
         self.file_names = file_name_list
         self.ham_param = CaseInsensitiveDict()
         self.ham_param["Transfer"] = self._read_ham("trans", value_type="complex")
@@ -28,6 +40,15 @@ def __init__(self, file_name_list, solver_type="UHFr"):
         self.green["OneBodyG"] = self._read_green("onebodyg")
 
     def get_param(self, key):
+        """
+        Get parameters based on the key.
+
+        Parameters:
+        key (str): Key to identify the parameter type.
+
+        Returns:
+        dict or None: Returns the corresponding parameter dictionary or None if the key is invalid.
+        """
         if key == "mod" or key == "parameter":
             #return self.mod_param
             return None
@@ -41,6 +62,16 @@ def get_param(self, key):
             return None
 
     def _read_para(self, file_key, start_line=5):
+        """
+        Read parameters from a file.
+
+        Parameters:
+        file_key (str): Key to identify the file.
+        start_line (int): Line number to start reading from. Default is 5.
+
+        Returns:
+        CaseInsensitiveDict: Dictionary of parameters read from the file.
+        """
         file_name = self.file_names[file_key]
         value = CaseInsensitiveDict()
         with open(file_name, "r") as f:
@@ -54,13 +85,32 @@ def _read_para(self, file_key, start_line=5):
         return value
 
     def _read_ham(self, file_key, value_type="real"):
+        """
+        Read Hamiltonian parameters from a file.
+
+        Parameters:
+        file_key (str): Key to identify the file.
+        value_type (str): Type of values to read ("real" or "complex"). Default is "real".
+
+        Returns:
+        dict or None: Dictionary of Hamiltonian parameters or None if the file key is not found.
+        """
         if file_key in self.file_names:
             file_name = self.file_names[file_key]
             return self._load_text(file_name, value_type)
         else:
             return None
 
     def _read_green(self, file_key):
+        """
+        Read Green's function data from a file.
+
+        Parameters:
+        file_key (str): Key to identify the file.
+
+        Returns:
+        numpy.ndarray or None: Array of Green's function data or None if the file key is not found.
+        """
         if file_key in self.file_names:
             file_name = self.file_names[file_key]
             data = np.loadtxt(file_name, skiprows = 5)
@@ -69,6 +119,16 @@ def _read_green(self, file_key):
         return data
 
     def _load_text(self, file_name, value_type):
+        """
+        Load text data from a file.
+
+        Parameters:
+        file_name (str): Name of the file to read.
+        value_type (str): Type of values to read ("real" or "complex").
+
+        Returns:
+        dict: Dictionary of data read from the file.
+        """
         if value_type == "real":
             value_width = 1
             _make_value = lambda v: float(v[0])

src/hwave/qlmsio/read_input_k.py

@@ -10,9 +10,19 @@
 
 
 class QLMSkInput():
+    """
+    Class to handle QLMS input files and parameters.
+    """
     valid_namelist = [s.lower() for s in ["path_to_input", "Geometry", "Transfer", "CoulombIntra", "CoulombInter", "Hund", "Ising", "PairLift", "Exchange", "PairHop", "Extern"]]
 
     def __init__(self, info_inputfile, solver_type="UHFk"):
+        """
+        Initialize the QLMSkInput object.
+
+        Parameters:
+        info_inputfile (dict): Dictionary containing input file information.
+        solver_type (str): Type of solver to use. Default is "UHFk".
+        """
         logger.debug(">>> QLMSkInput init")
 
         # [file.input]
@@ -91,6 +101,16 @@ def __init__(self, info_inputfile, solver_type="UHFk"):
             self.green["onebodyg_uhf"] = self._read_green(file_name)
 
     def _read_data(self, file_name, value_type="real"):
+        """
+        Read data from a file.
+
+        Parameters:
+        file_name (str): Name of the file to read.
+        value_type (str): Type of values in the file ("real" or "complex"). Default is "real".
+
+        Returns:
+        dict: Dictionary containing the data read from the file.
+        """
         info = {}
         try:
             data = np.loadtxt(file_name, skiprows = 5)
@@ -110,6 +130,15 @@ def _read_data(self, file_name, value_type="real"):
         return info
 
     def _read_green(self, file_name):
+        """
+        Read green function data from a file.
+
+        Parameters:
+        file_name (str): Name of the file to read.
+
+        Returns:
+        numpy.ndarray: Array containing the green function data.
+        """
         try:
             _data = np.loadtxt(file_name, dtype=np.int32, skiprows = 5)
         except FileNotFoundError:
@@ -118,6 +147,15 @@ def _read_green(self, file_name):
         return _data
 
     def get_param(self, key):
+        """
+        Get parameters based on the provided key.
+
+        Parameters:
+        key (str): Key to specify which parameters to return ("mod", "ham", "output", etc.).
+
+        Returns:
+        dict or None: Dictionary containing the requested parameters or None if the key is invalid.
+        """
         if key == "mod" or key == "parameter":
             return None
         elif key == "ham" or key == "hamiltonian":