From 5ea832675702ae6715b07215de120315657ca03d Mon Sep 17 00:00:00 2001
From: Justus Kuhlmann <justus@kuhl-mann.de>
Date: Thu, 9 Apr 2026 10:26:47 +0200
Subject: [PATCH] add thin wrapper to accomodate for input conventions, add
 comments

---
 corrlib/input/openQCD.py | 62 +++++++++++++++++++++++++++++++++-------
 1 file changed, 52 insertions(+), 10 deletions(-)

diff --git a/corrlib/input/openQCD.py b/corrlib/input/openQCD.py
index 9c5fbbc..1d36e7f 100644
--- a/corrlib/input/openQCD.py
+++ b/corrlib/input/openQCD.py
@@ -307,27 +307,42 @@ def extract_t1(path: Path, project: str, dir_in_project: str, param: dict[str, A
     return t1_dict
 
 
-def read_par_file(fname: str) -> dict[str, dict[str, Any]]:
+def read_qcd2_par_file(fname: Path) -> dict[str, dict[str, Any]]:
+    """
+    The subroutines written here have names according to the openQCD programs and functions that write out the data.
 
+    Parameters
+    ----------
+    fname: Path
+        Location of the parameter file.
+
+    Returns
+    -------
+    par_dict: dict
+        Dictionary holding the parameters specified in the given file.
+    """
     def _qcd2_write_lat_parms() -> dict[str, Any]:
+        """
+        Unpack the lattice parameters written by write_lat_parms.
+        """
         lat_pars = {}
-
         t = fp.read(16)
         lat_pars["N"] = list(struct.unpack('iiii', t)) # lattice extends
         t = fp.read(8)
-        nk, isw = struct.unpack('ii', t)
+        nk, isw = struct.unpack('ii', t) # number of kappas and isw parameter
         lat_pars["nk"] = nk
         lat_pars["isw"] = isw
         t = fp.read(8)
-        lat_pars["beta"] = struct.unpack('d', t)[0]
+        lat_pars["beta"] = struct.unpack('d', t)[0] # beta
         t = fp.read(8)
         lat_pars["c0"] = struct.unpack('d', t)[0]
         t = fp.read(8)
         lat_pars["c1"] = struct.unpack('d', t)[0]
         t = fp.read(8)
-        lat_pars["csw"] = struct.unpack('d', t)[0]
+        lat_pars["csw"] = struct.unpack('d', t)[0] # csw factor
         kappas = []
         m0s = []
+        # read kappas
         for ik in range(nk):
             t = fp.read(8)
             kappas.append(struct.unpack('d', t)[0])
@@ -338,14 +353,17 @@ def read_par_file(fname: str) -> dict[str, dict[str, Any]]:
         return lat_pars
 
     def _qcd2_write_bc_parms() -> dict[str, Any]:
-        bc_pars = {}
+        """
+        Unpack the boundary parameters written by write_bc_parms.
+        """
+        bc_pars: dict[str, Any] = {}
         t = fp.read(4)
-        bc_pars["type"] = struct.unpack('i', t)[0]
+        bc_pars["type"] = struct.unpack('i', t)[0] # type of hte boundaries
         t = fp.read(104)
         bc_parms = struct.unpack('d'*13, t)
-        bc_pars["cG"] = list(bc_parms[:2])
-        bc_pars["cF"] = list(bc_parms[2:4])
-        phi = [[], []]
+        bc_pars["cG"] = list(bc_parms[:2]) # boundary gauge field improvement
+        bc_pars["cF"] = list(bc_parms[2:4]) # boundary fermion field improvement
+        phi: list[list[float]] = [[], []]
         phi[0] = list(bc_parms[4:7])
         phi[1] = list(bc_parms[7:10])
         bc_pars["phi"] = phi
@@ -360,3 +378,27 @@ def read_par_file(fname: str) -> dict[str, dict[str, Any]]:
     par_dict["lat"] = lat_par_dict
     par_dict["bc"] = bc_par_dict
     return par_dict
+
+
+def load_qcd2_pars(path: Path, project: str, file_in_project: str)  -> dict[str, Any]:
+    """
+    Thin wrapper around read_qcd2_par_file, getting the file before reading.
+
+    Parameters
+    ----------
+    path: Path
+        Path of the corrlib repository.
+    project: str
+        UUID of the project of the parameter-file.
+    file_in_project: str
+        The loaction of the file in the project directory.
+
+    Returns
+    -------
+    par_dict: dict
+        The dict with the parameters read from the .par-file.
+    """
+    fname = path / "projects" / project / file_in_project
+    ds = os.path.join(path, "projects", project)
+    dl.get(fname, dataset=ds)
+    return read_qcd2_par_file(fname)