Add docstrings for Python helpers to improve hover docs

Analysis/convert_bins.py

@@ -62,6 +62,7 @@ def copy_parameters(sim_dir, hamiltonian_file):
 
 
 def _get_arg_parser():
+    """Build and return the argument parser for the CLI."""
     parser = ArgumentParser(
         description='Convert plain text bins and parameters to HDF5 file. '
         'Moves plain text bin and associated _info files to "old_bins" '

Analysis/fix-latt.py

@@ -13,6 +13,7 @@
 
 
 def _get_arg_parser():
+    """Create the CLI argument parser for lattice fix utility."""
     parser = ArgumentParser(
         description='Fix a mix-up between `Norb` and `N_coord` in lattice.',
         )
@@ -23,6 +24,7 @@ def _get_arg_parser():
     return parser
 
 def _fix_latt(latt_grp):
+    """Correct swapped Norb/N_coord attributes inside a lattice group."""
     orbital_positions = []
     i = 0
     while True:
@@ -46,13 +48,14 @@ def _fix_latt(latt_grp):
 
 
 def _fix_loc(hdf5_loc):
-    for i in hdf5_loc:
-        if isinstance(i, str):
-            print(i)
-            if i == 'lattice':
-                _fix_latt(hdf5_loc[i])
+    """Recursively traverse an HDF5 hierarchy and fix lattice groups."""
+    for item in hdf5_loc:
+        if isinstance(item, str):
+            print(item)
+            if item == 'lattice':
+                _fix_latt(hdf5_loc[item])
             else:
-                _fix_loc(hdf5_loc[i])
+                _fix_loc(hdf5_loc[item])
 
 
 if __name__ == '__main__':

Prog/parse_ham_mod.py

@@ -103,10 +103,12 @@ def parse_line(line):
 
 
 def _max_len(dictionary):
-    return max(len(i) for i in dictionary)
+    """Return length of the longest key in a mapping."""
+    return max(len(key) for key in dictionary)
 
 
 def _dtype_name(parameter):
+    """Return Fortran dtype name corresponding to a Python value."""
     if isinstance(parameter, list):
         return _dtype_name(parameter[0])
     if isinstance(parameter, bool):
@@ -334,6 +336,7 @@ def create_read_write_par(filename, parameters, ham_name):
 
 
 def _to_value(dtype, value):
+    """Convert a string representation to the corresponding Python value."""
     if 'real' in dtype:
         return float(value.replace('d', 'e').replace('D', 'e'))
     # if 'complex' in dtype:
@@ -359,6 +362,7 @@ def _to_value(dtype, value):
 
 
 def _get_mpi_dtype(parameter):
+    """Return the MPI datatype constant matching the parameter type."""
     if isinstance(parameter, list):
         return _get_mpi_dtype(parameter[0])
     if isinstance(parameter, bool):
@@ -375,6 +379,7 @@ def _get_mpi_dtype(parameter):
 
 
 def _get_mpi_len(parameter):
+    """Return the number of MPI elements that need to be broadcast."""
     if isinstance(parameter, list):
         return _get_mpi_len(parameter[0]) * len(parameter)
     if isinstance(parameter, (bool, float, complex, int)):

testsuite/compare_dirs.py

@@ -15,13 +15,15 @@
 from py_alf.utils import find_sim_dirs
 
 def analyze_and_load(root_dir):
+    """Run analysis for all simulations under root_dir and load results."""
     dirs = find_sim_dirs(root_dir)
-    for dir in dirs:
-        analysis(dir)
+    for sim_dir in dirs:
+        analysis(sim_dir)
     return load_res(dirs)
 
 
 def compare_dirs(dir_R, dir_T, resultsfile):
+    """Compare observables from two simulation directories and write a report."""
     obs_R = analyze_and_load(dir_R)
     obs_T = analyze_and_load(dir_T)
 
@@ -42,6 +44,7 @@ def compare_dirs(dir_R, dir_T, resultsfile):
 
 
 def _get_arg_parser():
+    """Return an argument parser for comparing two simulation directories."""
     parser = argparse.ArgumentParser(
         description='Testing two directories of ALF simulations'
                     'for identical results.')

testsuite/test_branch_generate_config.py

@@ -140,6 +140,7 @@
 
 
 def prep_runs(test_specs, env_name, env_spec):
+    """Populate pipeline_config with compile/run jobs for one environment."""
     jobname_compile = f'{env_name}_compile'
     pipeline_config[jobname_compile] = {
         **{'extends': '.compile_template'},

testsuite/test_vs_ed/analysis.py

@@ -20,6 +20,7 @@
 res.to_json("results.json")
 
 def func(x, y0, a):
+    """Quadratic function used to fit energy extrapolation."""
     return y0 + a*x**2
 x = res.dtau
 y = res.Ener_scal0