doc/examples/pl-vineyard.rst
 author Dmitriy Morozov Sat, 23 Nov 2019 21:29:50 -0800 changeset 294 5810d70ec967 parent 185 7241b887eabb permissions -rw-r--r--
Get rid of Boost.Signals dependency
```
.. _pl-vineyard:

Piecewise-Linear Vineyard
=========================

Given a simplicial complex :math:`K`, and a sequence of values on each one of
its vertices, one may construct a homotopy of PL functions on the complex that
interpolates linearly between the values. For any given time in the homotopy, we
get a function from the simplicial complex to the real line, and we can compute
its persistence diagram. Stacking all such diagrams together we get a
persistence vineyard [CEM06]_. An example that computes such a vineyard is in
:sfile:`examples/pl-functions/pl-vineyard.cpp`.

.. program:: pl-vineyard

Once compiled, it takes three files as the input::

pl-vineyard complex values output-prefix

``complex`` lists the simplices of the simplicial complex :math:`K`, one
per-line::

0
1
0 1
2
0 2
...

``values`` lists the vertex values of the consequtive "frames" of the homotopy.
Each line is a sequence of as many numbers as there are vertices in the complex.
It describes a single frame. :program:`pl-vineayrd` constructs the homotopy over
the interval :math:`[0,k-1]`, where :math:`k` is the number of frames. As an
example of ``values`` input::

3.3   6    2
1.2   3    10
7.5   2.1  0

This input means: :math:`f_0(0) = 3.3, f_1(0) = 1.2, f_2(0) = 7.5`. Similarly,
:math:`f_0(1) = 6, f_1(1) = 3, f_2(1) = 2.1`;
:math:`f_0(2) = 2, f_1(2) = 10, f_2(2) = 0`.

The vineyard is saved to the files prefixed with ``output-prefix``, followed by
the dimension and extension, e.g. ``myfunction1.vin`` or ``myfunction1.edg``,
depending on the format. The two formats are vines and edges. The former saves
one vine per line, listed as a stream of triplets BIRTH DEATH TIME::

4 5 0 3.4 5.6 0.4 3 6 1 ...

The edge format represents the vine as a sequence of edges, each given as a
start and end point. So the above vine would appear as::

4 5 0
3.4 5.6 0.4
3.4 5.6 0.4
3 6 1
...