From 9e58f33c84ad51b816d4bea84300cd7712a06fdb Mon Sep 17 00:00:00 2001
From: Gard Spreemann <gspreemann@gmail.com>
Date: Tue, 29 Mar 2016 11:08:30 +0200
Subject: More docstrings.

---
 phstuff/diphawrapper.py | 88 ++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 87 insertions(+), 1 deletion(-)

diff --git a/phstuff/diphawrapper.py b/phstuff/diphawrapper.py
index ac3983f..46aaea1 100644
--- a/phstuff/diphawrapper.py
+++ b/phstuff/diphawrapper.py
@@ -9,6 +9,11 @@ import subprocess
 
 import phstuff.barcode as bc
 
+"""Handle marshalling data into and out of DIPHA's formats, and
+optionally manage running the DIPHA executable.
+
+"""
+
 # FIXME, TODO: These magic numbers should really be read from the
 # DIPHA header files.
 DIPHA_MAGIC = 8067171840
@@ -145,6 +150,23 @@ def save_edge_list(fname, edge_list):
 
 
 def load_barcode(fname, top_dim = None):
+    """Load a barcode as written by DIPHA.
+
+    Parameters:
+    -----------
+
+    fname: File name to load.
+    
+    top_dim: Integer. Exclude degrees above this.
+
+    Returns:
+    --------
+
+    A dict keyed on persistent homology degree. Associated to each
+    degree is a list of `Interval`s.
+
+    """
+    
     ret = dict()
     
     with open(fname, "rb") as f:
@@ -171,6 +193,19 @@ def load_barcode(fname, top_dim = None):
     return ret
 
 def save_text_barcode(fname, barcode):
+    """Saves a barcode as a human- and machine-readable text file in an
+    ad-hoc format.
+
+    Parameters:
+    -----------
+    
+    fname: File name to save to.
+    
+    barcode: The barcode to save, a dictionary keyed on degree, each
+    entry being a list of `Interval`s.
+
+    """
+
     with open(fname, "w") as f:
         for dim in barcode.keys():
             for interval in barcode[dim]:
@@ -181,7 +216,47 @@ def save_text_barcode(fname, barcode):
     
 
 class DiphaRunner:
+    """For long-running computations that may fail, or computations
+    involving huge amounts of data, I recommend that you run DIPHA
+    yourself. If you prefer to avoid doing that, this class helps you
+    run DIPHA without leaving your Python script.
+
+    In order to do so, the `DiphaRunner` object needs to know where to
+    find the `mpirun` and `dipha` executables. If they are somewhere
+    in your environment's `PATH`, then everything is fine. If not, you
+    need to specify where these can be foind either by setting the
+    environment variables `DIPHA`/`MPIRUN` (to the full path of the
+    executables, not just their directories) or through the optional
+    arguments of the class constructor.
+
+    """
+
     def __init__(self, top_dim, cpu_count = None, quiet = True, mpirun = None, dipha = None):
+        """Constructor.
+        
+        Parameters:
+        -----------
+        
+        top_dim: Highest simplex dimension to include.
+
+        cpu_count (optional): The number of parallell DIPHA processes
+        to run. If `None` (default), try to autodetect. The actual
+        number that will be used can be found in the `cpu_count`
+        member of the returned object.
+
+        quiet (optional): Don't print anything in normal situations
+        (default).
+
+        mpirun (optional): Full path of the `mpirun` executable. If
+        `None` (default), use environment variable `MPIRUN` or look in
+        `PATH`.
+
+        dipha (optional): Full path of the `dipha` executable. If
+        `None` (default), use environment variable `DIPHA` or look in
+        `PATH`.
+
+        """
+    
         self.top_dim = int(top_dim)
         if top_dim <= 0:
             raise ValueError("Top dimension must be postitive.")
@@ -232,18 +307,29 @@ class DiphaRunner:
 
         
     def weight_matrix(self, weights):
+        """Initialize to run with a weight matrix. See `save_weight_matrix`."""
+        
         save_weight_matrix(self.ifile, weights)
         self.ready = True
 
     def masked_weight_matrix(self, weights):
+        """Initialize to run with a masked weight matrix. See
+        `save_masked_weight_matrix`."""
+        
         save_masked_weight_matrix(self.ifile, weights)
         self.ready = True
 
     def edge_list(self, edge_list):
+        """Initialize to run with an edge list. See `save_edge_list`."""
+        
         save_edge_list(self.ifile, edge_list)
         self.ready = True
 
     def run(self):
+        """Run DIPHA. Success is indicated by `code` member of the object
+        being zero. If that is the case, then the result is available
+        in the `barcode` member."""
+
         if not self.ready:
             self.cleanup()
             raise RuntimeError("Not ready to run. Maybe you haven't given me data, or I've already been run?")
@@ -266,7 +352,7 @@ class DiphaRunner:
             self.cleanup()
 
         if self.code == 0:
-            self.barcode = load_barcode(self.ofile)
+            self.barcode = load_barcode(self.ofile, top_dim = self.top_dim - 1)
 
         self.ready = False
         self.cleanup()
-- 
cgit v1.2.3