--- /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.