Documentation for parametrization using persistent cohomology dev
authorDmitriy Morozov <dmitriy@mrzv.org>
Thu, 09 Jul 2009 02:46:53 -0700
branchdev
changeset 139 656ec2838fb8
parent 138 96030f8d2f2c
child 140 9851fee5a33b
Documentation for parametrization using persistent cohomology
doc/examples/cohomology.rst
doc/examples/index.rst
doc/index.rst
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/examples/cohomology.rst	Thu Jul 09 02:46:53 2009 -0700
@@ -0,0 +1,87 @@
+.. _cohomology-parametrization:
+
+Parametrizing a point set using circle valued functions
+=======================================================
+
+The procedure described below is explained in detail in [dSVJ09]_.
+
+.. program:: rips-pairwise-cohomology
+
+One can use :sfile:`examples/cohomology/rips-pairwise-cohomology.cpp` to compute
+persistent pairing of the Rips filtration using the persistent cohomology
+algorithm. It takes as input a file containing a point set in Euclidean space
+(one per line) as well as the following command-line flags:
+
+.. cmdoption:: -p, --prime
+
+    The prime to use in the computation (defaults to 11).
+
+.. cmdoption:: -m, --max-distance
+
+    Maximum cutoff parameter up to which to compute the complex.
+
+.. cmdoption:: -s, --skeleton-dimension
+
+    Skeleton to compute; persistent pairs output will be this number minus 1
+    (defaults to 2).
+
+.. cmdoption:: -b, --boundary
+
+    Filename where to output the boundary matrix.
+
+.. cmdoption:: -c, --cocycle
+
+    Prefix of the filenames where to output the 1-dimensional cocycles.
+
+.. cmdoption:: -v, --vertices
+
+    Filename where to output the simplex vertex mapping.
+
+.. cmdoption:: -d, --diagram
+
+    Filename where to output the persistence diagram.
+
+
+For example::
+
+    rips-pairwise-cohomology points.txt -m 1 -b points.bdry -c points -v points.vrt -d points.dgm
+
+Assuming that at the threshold value of 1 (``-m 1`` above) Rips complex contains
+1-dimensional cocycles, they will be output into filenames of the form
+``points-0.ccl``, ``points-1.ccl``, etc.
+
+Subsequently one can use :sfile:`examples/cohomology/cocycle.py` to assign to
+each vertex of the input point set a circle-valued function. It takes the
+boundary matrix, cocycle, and simplex-vertex map as an input (all produced at
+the previous step)::
+
+    cocycle.py points.bdry points-0.ccl points.vrt
+
+The above command outputs a file ``points-0.val`` which contains values assigned
+to the input points (the lines match the lines of the input file
+``points.txt``, but also contains the indices).
+
+
+Plotting
+--------
+
+Two auxilliary tools allow one to visualize the values assigned to the points
+(using Matplotlib_): :sfile:`tools/plot-values/plot.py` and
+:sfile:`tools/plot-values/scatter.py`::
+    
+    plot.py points-0.val points.txt scatter.py points-0.val points-1.val
+
+.. _Matplotlib:                             http://matplotlib.sourceforge.net/    
+
+
+Dependency
+----------
+
+The Python `LSQR code`_ (ported from the `Stanford MATLAB implementation`_ to
+Python by `Jeffery Kline`_) included with Dionysus, and used in
+:sfile:`examples/cohomology/cocycle.py`, requires CVXOPT_.
+
+.. _`LSQR code`:                            http://pages.cs.wisc.edu/~kline/cvxopt/
+.. _CVXOPT:                                 http://abel.ee.ucla.edu/cvxopt/
+.. _`Stanford MATLAB implementation`:       http://www.stanford.edu/group/SOL/software/lsqr.html
+.. _`Jeffery Kline`:                        http://pages.cs.wisc.edu/~kline/
--- a/doc/examples/index.rst	Thu Jul 09 02:42:47 2009 -0700
+++ b/doc/examples/index.rst	Thu Jul 09 02:46:53 2009 -0700
@@ -32,3 +32,13 @@
     :maxdepth: 1
 
     rips
+
+One may use persistent cohomology algorithm to extract persistent cocycles,
+turn them into harmonic cocycles, and use them to parametrize the input point
+set; for details see [dSVJ09]_. The explanation of how to use Dionysus to
+achieve this is available.
+
+.. toctree::
+    :maxdepth: 1
+
+    cohomology
--- a/doc/index.rst	Thu Jul 09 02:42:47 2009 -0700
+++ b/doc/index.rst	Thu Jul 09 02:46:53 2009 -0700
@@ -13,6 +13,7 @@
   * :ref:`Alpha shape construction <alpha-shape-example>` in 2D and 3D
   * :ref:`Rips complex construction <rips-example>`
   * Cech complex construction       |cpp-only|
+  * :ref:`Circle-valued parametrization using persistent cohomology <cohomology-parametrization>`
 
 .. todo:: 
    Document more examples.